2  Single-voxel analysis

In this section we describe the recommended way to perform analysis of single-voxel MRS data acquired from the human brain at a field strength of 1.5 or 3 Tesla with PRESS, STEAM or semi-LASER. We recommend attempting your first analysis using the provided example data to ensure the software is installed correctly.

Before starting analysis, make a note of the current working directory - as this is where the example data will be downloaded and results stored. To print the working directory enter getwd() on the command line. If you prefer to work in a different directory use the setwd("/my/new/path") command, or navigate to Session and Set Working Directory in the RStudio menu bar.

2.1 Minimal working example

Run the following code to download the example data to your working directory and unzip into a new directory called svs_slaser_example:

url <- "https://www.dropbox.com/scl/fo/ngjx9povyeroibz8cntwg/ALm-jZ_5zjygvnhXSxJyNWQ?rlkey=3ybqft2pfmkytjmolw6emnnnp&dl=1"
download.file(url, "svs_slaser_example.zip", mode = "wb")
unzip("svs_slaser_example.zip", exdir = "svs_slaser_example")

If the code fails for any reason you can use this link to manually download the data and use your system tools to copy it to your working directory and unzip.

To perform a basic analysis run the following commands:

1library(spant)
2ws_path <- file.path("svs_slaser_example", "sub-01_svs.nii.gz")
3fit_svs(metab = ws_path)
1
load the spant library, this only needs to be done at the start of the session
2
construct a path for the metabolite (also known as “water suppressed”) MRS data file, the file.path function is used to ensure the code is platform independent
3
run the analysis pipeline

Once the fit_svs function has completed, a new directory called sub-01_svs_nii_gz_results will have been created in the current working directory. The following three files will be inside the results directory:

  1. report.html - fitting result plots and tables, online example
  2. fit_res_tCr_ratio.csv - spreadsheet of metabolite quantities as ratios to total-creatine (tCr)
  3. fit_res_unscaled.csv - spreadsheet of unscaled metabolite quantities

2.2 Common analysis options

2.2.1 Output directory and ratio output

By default, spant will automatically generate an output directory in the current working directory based on the input file name. However, it is good practice to provide an explicit path using the output_dir argument show below. The metabolite ratio denominator can be changed with the output_ratio argument, changed from the default of total-creatine (“tCr”) to total-NAA (“tNAA”) below.

fit_svs(metab = ws_path, output_dir = "slaser_results_tnaa",
        output_ratio = "tNAA")

2.2.2 Water reference data

In addition to water-suppressed metabolite data, single-voxel MRS protocols typically incorporates a short water reference scan, used to scale the metabolite levels as concentrations. The fit_svs function performs this automatically, according to the method described by Gasparovic [1], when water reference data is available. Note that the default behaviour assumes the voxel contains 100% white matter, however it is good practice to explicitly set the p_vols argument. For further details on the default water scaling method and assumptions see Section 3.1. The example below performs water reference scaling assuming the voxel contains 100% gray matter.

wref_path <- file.path("svs_slaser_example", "sub-01_ref.nii.gz")
fit_svs(metab = ws_path, w_ref = wref_path, output_dir = "slaser_results_wref", 
        p_vols = c(WM = 0, GM = 100, CSF = 0))

Note that an additional file containing the water reference scaled metabolite values (fit_res_molal_conc.csv) will be generated in the results directory.

2.2.3 Basis signals

By default, fit_svs will automatically simulate a basis-set containing the following molecular signals:

"m_cr_ch2", "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"

The append_basis and remove_basis arguments may be used to adjust this list. Analyses may benefit from the inclusion of phosphoethanolamine and glycine for higher quality MRS acquired at 3 Tesla and above. The append_basis option may be specified to add these signals as follows:

fit_svs(metab = ws_path, w_ref = wref_path, output_dir = "slaser_results_peth_gly", 
        p_vols = c(WM = 0, GM = 100, CSF = 0), append_basis = c("peth", "gly"))

Other common metabolites to append for brain tumour analyses include 2-hydroxyglutarate "2hg" and citrate "cit". To see a full list of available molecular parameters run get_mol_names(). To print detailed output of a particular molecule, eg NAA, run get_mol_paras("naa") in the console.

2.2.4 HSVD water removal

HSVD water removal [2] may be applied as a preprocessing step by setting the hsvd_width option to a value representing the width of the filter in Hz. The following example will filter residual water signals between -30 and +30 Hz.

fit_svs(metab = ws_path, w_ref = wref_path, hsvd_width = 30)

Note that in rare cases HSVD filtering may introduce baseline distortions which are stronger than the residual water, it is recommended to check results with and without filtering to confirm the step results in an improvement.

2.2.5 Eddy current correction

Eddy current correction [3] may be applied as a preprocessing step by setting the ecc option to TRUE providing water reference data is available. Depending on how the water reference data was acquired, eddy current correction may not always yield improved spectral lineshape, it is recommended to check results with and without correction to confirm the step results in an improvement.

2.2.6 Dynamic frequency and phase correction

For data with very low single-shot SNR it may be beneficial to disable the dynamic frequency and phase correction preprocessing step by setting dfp_corr to FALSE. Always check the resultant SNR with and without to confirm the optimal setting for your data.

2.2.7 Summary measures table

Whilst around 30 signals are included in a typical analysis, and reported in the html results table, it is often the case that only a subset are of interest for clinical decision making. To aid evaluation speed, the summary_measures option allows a subset of signals levels and ratios to be included in a separate summary table in the html output. See below for example use:

biomarkers <- c("tNAA", "tNAA/tCr", "tNAA/tCho", "Lac/tNAA")
fit_svs(metab = ws_path, w_ref = wref_path, summary_measures = biomarkers)

2.3 Advanced analyses

For advanced users, further fitting options can be found in the on-line reference documentation: function reference.

2.4 Analysis using scripts

Interactively typing commands directly into the R console is a good way to get started, however using scripts is a far more reproducible way to perform analysis. The commands to run analyses for multiple datasets may be stored together in a single script ensuring you have a complete record of all the data files and fitting options used. See this guide for help on how to use scripts in RStudio. Copy and paste the following code into a new script and experiment with using Cmd/Ctrl + Enter to run line-by-line, and Cmd/Ctrl + Shift + S to run the full script.

# load the spant library
library(spant)

# define path to the MRS data files
ws_path   <- file.path("svs_slaser_example", "sub-01_svs.nii.gz")
wref_path <- file.path("svs_slaser_example", "sub-01_ref.nii.gz")

# a simple analysis
fit_svs(metab = ws_path, output_dir = "slaser_results_simple")

# an improved analysis
fit_svs(metab = ws_path, w_ref = wref_path,
        output_dir = "slaser_results_improved", 
        p_vols = c(WM = 0, GM = 100, CSF = 0),
        append_basis = c("peth", "gly"))

References

[1]
C. Gasparovic et al., “Use of tissue water as a concentration reference for proton spectroscopic imaging,” Magnetic Resonance in Medicine, vol. 55, no. 6, pp. 1219–1226, Jun. 2006, doi: 10.1002/mrm.20901.
[2]
H. Barkhuijsen, R. de Beer, and D. van Ormondt, “Improved algorithm for noniterative time-domain model fitting to exponentially damped magnetic resonance signals,” Journal of Magnetic Resonance (1969), vol. 73, no. 3, pp. 553–557, Jul. 1987, doi: 10.1016/0022-2364(87)90023-0.
[3]
U. Klose, “In vivo proton spectroscopy in presence of eddy currents,” Magnetic Resonance in Medicine, vol. 14, no. 1, pp. 26–30, Apr. 1990, doi: 10.1002/mrm.1910140104.