# Introduction to spant

## Reading raw data and plotting

Load the spant package:

    library(spant)

Get the path to a data file included with spant:

    fname <- system.file("extdata", "philips_spar_sdat_WS.SDAT", package = "spant")

Read the file and save to the workspace as `mrs_data`:

    mrs_data <- read_mrs(fname)

Output some basic information about the data:

    print(mrs_data)
    #> MRS Data Parameters
    #> ----------------------------------
    #> Trans. freq (MHz)       : 127.7861
    #> FID data points         : 1024
    #> X,Y,Z dimensions        : 1x1x1
    #> Dynamics                : 1
    #> Coils                   : 1
    #> Voxel resolution (mm)   : 20x20x20
    #> Sampling frequency (Hz) : 2000
    #> Repetition time (s)     : 2
    #> Reference freq. (ppm)   : 4.65
    #> Nucleus                 : 1H
    #> Spectral domain         : FALSE
    #> Number of transients    : 128
    #> Echo time (s)           : 0.03
    #> Manufacturer            : Philips

Plot the spectral region between 5 and 0.5 ppm:

    plot(mrs_data, xlim = c(5, 0.5))

## Basic preprocessing

Apply a HSVD filter to the residual water region and align the spectrum to the tNAA resonance at 2.01 ppm:

    mrs_proc <- hsvd_filt(mrs_data)
    mrs_proc <- align(mrs_proc, 2.01)
    plot(mrs_proc, xlim = c(5, 0.5))

## Basis simulation

Simulate a typical basis set for short TE brain analysis, print some basic information and plot:

    basis <- sim_basis_1h_brain_press(mrs_proc)
    print(basis)
    #> Basis set parameters
    #> -------------------------------
    #> Trans. freq (MHz)       : 127.8
    #> Data points             : 1024
    #> Sampling frequency (Hz) : 2000
    #> Elements                : 27
    #>
    #> Names
    #> -------------------------------
    #> -CrCH2,Ala,Asp,Cr,GABA,Glc,Gln,
    #> GSH,Glu,GPC,Ins,Lac,Lip09,
    #> Lip13a,Lip13b,Lip20,MM09,MM12,
    #> MM14,MM17,MM20,NAA,NAAG,PCh,
    #> PCr,sIns,Tau
    stackplot(basis, xlim = c(4, 0.5), labels = basis$names, y_offset = 5)

Perform ABfit analysis of the processed data (`mrs_proc`):

    fit_res <- fit_mrs(mrs_proc, basis)

Plot the fit result:

    plot(fit_res)

Unscaled amplitudes, CRLB error estimates and other useful fitting diagnostics, such as SNR, are given in the `fit_res` results table:

    fit_res$res_tab
    #>   X Y Z Dynamic Coil X.CrCH2          Ala          Asp           Cr
    #> 1 1 1 1       1    1       0 9.363301e-06 3.329357e-05 4.021887e-05
    #>           GABA         Glc          Gln          GSH         Glu          GPC
    #> 1 1.691009e-05 4.03821e-06 4.651576e-06 2.169002e-05 6.72718e-05 1.610895e-05
    #>            Ins         Lac        Lip09       Lip13a Lip13b Lip20         MM09
    #> 1 6.027686e-05 5.93172e-06 2.340748e-05 2.821671e-06      0     0 1.008715e-05
    #>           MM12        MM14         MM17         MM20          NAA         NAAG
    #> 1 6.846165e-06 2.70834e-05 2.580652e-05 9.459224e-05 5.952934e-05 1.585882e-05
    #>   PCh          PCr         sIns Tau         tNAA          tCr         tCho
    #> 1   0 2.051214e-05 6.621278e-06   0 7.538816e-05 6.073101e-05 1.610895e-05
    #>            Glx        tLM09        tLM13        tLM20   X.CrCH2.sd       Ala.sd
    #> 1 7.192337e-05 3.349463e-05 3.675124e-05 9.459224e-05 2.364498e-06 4.359536e-06
    #>         Asp.sd        Cr.sd      GABA.sd       Glc.sd       Gln.sd       GSH.sd
    #> 1 8.966706e-06 3.745644e-06 4.456277e-06 4.324844e-06 4.893194e-06 2.018255e-06
    #>         Glu.sd       GPC.sd     Ins.sd       Lac.sd    Lip09.sd    Lip13a.sd
    #> 1 4.906394e-06 2.467175e-06 2.0219e-06 5.352922e-06 4.06975e-06 1.340768e-05
    #>      Lip13b.sd     Lip20.sd      MM09.sd      MM12.sd      MM14.sd      MM17.sd
    #> 1 6.513463e-06 7.382296e-06 3.769466e-06 4.494847e-06 7.120126e-06 3.582118e-06
    #>        MM20.sd       NAA.sd      NAAG.sd       PCh.sd      PCr.sd      sIns.sd
    #> 1 8.258685e-06 1.019012e-06 1.242431e-06 2.110543e-06 3.16171e-06 7.093103e-07
    #>         Tau.sd      tNAA.sd       tCr.sd      tCho.sd       Glx.sd     tLM09.sd
    #> 1 3.718437e-06 7.082524e-07 5.852189e-07 2.122582e-07 2.893516e-06 9.739827e-07
    #>       tLM13.sd    tLM20.sd    phase       lw        shift     asym res.deviance
    #> 1 1.526205e-06 2.88268e-06 10.73641 5.025062 -0.003467595 0.175015 7.467864e-05
    #>   res.niter res.info
    #> 1        27        2
    #>                                                        res.message bl_ed_pppm
    #> 1 Relative error between `par' and the solution is at most `ptol'.   1.969325
    #>   max_bl_flex_used     full_res   spec_resid fit_pts ppm_range      SNR
    #> 1            FALSE 8.218013e-05 7.467864e-05     497       3.8 63.12466
    #>        SRR      FQN   tNAA_lw    tCr_lw    tCho_lw auto_bl_crit_7
    #> 1 51.12924 1.524262 0.0457539 0.0517342 0.05458901      -8.893571
    #>   auto_bl_crit_5.901 auto_bl_crit_4.942 auto_bl_crit_4.12 auto_bl_crit_3.425
    #> 1          -8.937072          -8.970754         -8.994897          -9.010328
    #>   auto_bl_crit_2.844 auto_bl_crit_2.364 auto_bl_crit_1.969 auto_bl_crit_1.647
    #> 1          -9.020316          -9.026532          -9.028065          -9.015725
    #>   auto_bl_crit_1.384 auto_bl_crit_1.17 auto_bl_crit_0.997 auto_bl_crit_0.856
    #> 1          -8.964141         -8.847346          -8.690641          -8.560649
    #>   auto_bl_crit_0.743 auto_bl_crit_0.654 auto_bl_crit_0.593 auto_bl_crit_0.558
    #> 1           -8.48297          -8.444755          -8.427998          -8.421009
    #>   auto_bl_crit_0.54 auto_bl_crit_0.532 auto_bl_crit_0.529
    #> 1         -8.418108          -8.416892          -8.416378

Note that signal names appended with “.sd” are the CRLB estimates for the uncertainty (standard deviation) in the metabolite quantity estimate. e.g. to calculate the percentage s.d. for tNAA:

    fit_res$res_tab$tNAA.sd / fit_res$res_tab$tNAA * 100
    #> [1] 0.9394744

Spectral SNR:

    fit_res$res_tab$SNR
    #> [1] 63.12466

Linewidth of the tNAA resonance in PPM:

    fit_res$res_tab$tNAA_lw
    #> [1] 0.0457539

## Ratios to total-creatine

Amplitude estimates measured by the fitting method are essentially arbitrary unless scaled to a known reference signal. The simplest approach for proton-MRS is to simply divide all metabolite values by total-creatine:

    fit_res_tcr_sc <- scale_amp_ratio(fit_res, "tCr")
    amps <- fit_amps(fit_res_tcr_sc)
    print(t(amps))
    #>               [,1]
    #> X.CrCH2 0.00000000
    #> Ala     0.15417661
    #> Asp     0.54821368
    #> Cr      0.66224599
    #> GABA    0.27844251
    #> Glc     0.06649337
    #> Gln     0.07659309
    #> GSH     0.35714898
    #> Glu     1.10770094
    #> GPC     0.26525074
    #> Ins     0.99252194
    #> Lac     0.09767201
    #> Lip09   0.38542884
    #> Lip13a  0.04646179
    #> Lip13b  0.00000000
    #> Lip20   0.00000000
    #> MM09    0.16609549
    #> MM12    0.11272931
    #> MM14    0.44595676
    #> MM17    0.42493149
    #> MM20    1.55756077
    #> NAA     0.98021322
    #> NAAG    0.26113211
    #> PCh     0.00000000
    #> PCr     0.33775401
    #> sIns    0.10902631
    #> Tau     0.00000000
    #> tNAA    1.24134533
    #> tCr     1.00000000
    #> tCho    0.26525074
    #> Glx     1.18429403
    #> tLM09   0.55152433
    #> tLM13   0.60514786
    #> tLM20   1.55756077

## Water reference scaling, AKA “absolute-quantification”

A more sophisticated approach to scaling metabolite values involves the use of a separate water-reference acquisition - which can be imported in the standard way:

    fname_wref <- system.file("extdata", "philips_spar_sdat_W.SDAT", package = "spant")
    mrs_data_wref <- read_mrs(fname_wref)

The following code assumes the voxel contains 100% white matter tissue and scales the metabolite values into molal (mM) units (mol / kg tissue water) based on the method described by Gasparovic et al MRM 2006 55(6):1219-26:

    p_vols <- c(WM = 100, GM = 0, CSF = 0)
    TE = 0.03
    TR = 2
    fit_res_molal <- scale_amp_molal_pvc(fit_res, mrs_data_wref, p_vols, TE, TR)
    fit_res_molal$res_tab$tNAA
    #> [1] 13.91831

An alternative method scales the metabolite values into molar (mM) units (mol / Litre of tissue) based on assumptions outlined in the LCModel manual and references therein (section 10.2). This approach may be preferred when comparing results to those obtained LCModel or TARQUIN.

    fit_res_molar <- scale_amp_molar(fit_res, mrs_data_wref)
    #> Warning in scale_amp_molar(fit_res, mrs_data_wref): Function name
    #> (scale_amp_molar) is missleading and has been replaced with scale_amp_legacy.
    fit_res_molar$res_tab$tNAA
    #> [1] 6.818354

Note, while “absolute” units are attractive, a large number of assumptions about metabolite and water relaxation rates are necessary to arrive at these mM estimates. If you’re not confident at being able to justify these assumptions, scaling to a metabolite reference (eg tCr as above) is going to be a better option in most cases. Simple metabolite referenced ratios also have the benefit of being more reproducible due to the simplicity of the approach.