Fitting

FSL-MRS fitting is performed using a linear combination model where a spectral basis is shifted, broadened, and scaled to fit the FID in the spectral domain. Additional nuisance parameters are 0th and 1st order phase, as well as a polynomial complex baseline.

Wrapper scripts for command-line fitting are provided for SVS and MRSI as shown below. For more details on the fitting model, algorithms, and advanced options see Details.

SVS

A basic call to fsl_mrs, the SVS wrapper script, is as follows:

fsl_mrs --data metab.nii.gz \
        --basis my_basis_spectra \
        --output example_fit

This will run non-linear optimisation using the Truncated Newton algorithm, as implemented in Scipy, and will produce a simple PNG file summarising the fit, and several CSV files containing concentrations, uncertainties, and QC parameters for further analysis.

A more complete call to fsl_mrs may be as follows.

fsl_mrs --data metab.nii.gz \
        --basis my_basis_spectra \
        --output example_fit \
        --h2o wref.nii.gz \
        --tissue_frac tissue_frac.json \
        --report

This will additionally run absolute quantification w.r.t the water reference (with partial volume adjustments) and will produce an interactive HTML report. Type: fsl_mrs --help to see all available options.

Output

Results from fsl_mrs are stored in a single folder that contains the following:

Interactive HTML Report (if the --report option was used.
CSV files summarising the metabolite concentrations (and uncertainties), fitted parameters, QC measures, and the used relaxation values for quantification.
PNG files with summary of the fitting and (optionally) voxel location.

A NIfTI file of the fitted spectrum, baseline, and individual metabolites can be generated using the results_to_spectrum script. For example:

results_to_spectrum --export_baseline example_fit

MRSI

A basic call to fsl_mrsi is given below:

fsl_mrsi --data mrsi.nii.gz \
         --basis my_basis_spectra \
         --output example_fit \
         --mask mask.nii.gz \
         --h2o wref.nii.gz \
         --tissue_frac WM.nii.gz GM.nii.gz CSF.nii.gz

This will fit the linear combination model to each voxel independently. Many additional options are available. Type fsl_mrsi --help for a list of all options.

Output

Results from fsl_mrsi are stored in a single folder containing the following output:

An interactive HTML report showing the fit to the average FID across all voxels in the mask.
NIfTI files summarising parameters, concentrations, and QC measures (one such file per metabolite)
Model prediction in the time domain (NIfTI)
Residuals (NIfTI)
Fitted Baseline (NIfTI)

The above NIfTI output can all be visualised in FSLeyes alongside the original data.

Python & Interactive Interface

FSL-MRS can also be used in an interactive Python environment. The following is an example fitting and visualisation of data that has already been processed (e.g. with fsl_mrs_proc).

In an IPython or Jupyter Notebook environment, run the following (the example data resides in the main fsl_mrs package folder):

Loading and preparing the data:

from fsl_mrs.utils import mrs_io

FID_file     = 'example_usage/example_data/metab.nii'
basis_folder = 'example_usage/example_data/steam_11ms'

data = mrs_io.read_FID(FID_file)
mrs = data.mrs(basis_file=basis_folder)
mrs.processForFitting()

Fitting the model to the data:

from fsl_mrs.utils import fitting
results = fitting.fit_FSLModel(mrs)

Visualising the fit:

from fsl_mrs.utils import plotting
plotting.plotly_fit(mrs,results)

Details

Modelling

At the core of FSL-MRS is a linear combination model. For more details on the modelling refer to [CLAR21].

The signal in the spectral domain \(\mathrm{Y}(v)\) is modelled as a linear combination of (shifted and broadened) metabolite basis spectra \(\mathrm{M}_{l,g}\) (metab = \(l\), metab group = \(g\)) plus a complex polynomial baseline \(\mathrm{B}(v)\). The signal model is as follows:

\[\begin{split}\begin{array}{c} \mathrm{Y}(v)=\mathrm{B}(v)+\exp \left[i\left(\phi_{0}+v \phi_{1}\right)\right] \sum_{g=1}^{N_{G}} \sum_{l=1}^{N_{g}} C_{l, g} M_{l, g}\left(v ; \gamma_{g}, \sigma_{g}, \epsilon_{g}\right) \\ M_{l, g}\left(v ; \gamma_{g}, \epsilon_{g}\right)=\mathcal{FFT}\left\{m_{l, g}(t) \exp \left[-\left(\left(\gamma_{g}+\sigma_{g}^{2} t\right)+i \epsilon_{g}\right) t\right]\right\} \end{array}\end{split}\]

Model parameters are summarised in the below table:

Symbol	Name	Units
\(\phi_0\)	zero-th order global phase	rad
\(\phi_1\)	first order global phase	rad/Hz
\(\epsilon_g\)	line shift for metab group \(g\)	rad/sec
\(\gamma_g\)	line broadening (Lorentizian) for metab group \(g\)	Hz
\(\sigma_g\)	line broadening (Gaussian) for metab group \(g\)	Hz
\(\mathrm{C}_{l,g}\)	concentration for metabolite \(l\) in group \(g\)	A.U.

Wrapper options

Below are detailed explanations of some of the optional arguments in the wrapper scripts. Type fsl_mrs --help or fsl_mrsi --help to get the full set of available options.

--algo ALGO: Algorithm to be used in the fitting. Either Newton (default) or MH. if MH is selected, the Metropolis hastings algorithm is run, initialised using the Newton algorithm (Truncated Newton as implemented in Scipy).
--ignore: List of metabolites to be removed from the basis file prior to fitting.
--keep: List of metabolites to include in the fitting, all other metabolites are excluded from the fitting
--combine: Combine sets of metabolites (not in the fitting, only in the quantification/display) - this option is repeatable.
--ppmlim: Only calculate the loss function within this ppm range.
--baseline_order: Polynomial baseline order. Set to -1 to remove the baseline altogether.
--metab_groups: Group metabolites into sub-groups that get their own lineshape parameters (shift and broadening). This can either be a list of integers (one per metabolite) from 0 to the max number of groups minus one. Or it could be a list of metabolites to be grouped. E.g. using the flag --metab_groups Mac NAA+NAAG+Cr then the Mac spectrum will have its own group, the NAA, NAAG, and Cr will be in a different group, and all other metabolites in a 3rd group. Other possibilities are combine_all and separate_all, where metabs are combined into a single group or separated into distinct groups respectively.
--lorentzian: By default the lineshape is a Voigt (lorentizian+gaussian). Use this flag to set to Lorentzian.
--ind_scale: Allow independent scaling of specified basis spectra before fitting. For example this can be used to independently scale empirically measured macromolecules combined with simulated metabolite spectra.
--disable_MH_priors: Disable the priors on the MH fitting. The priors are tuned for in vivo human brain spectroscopy. Use this option if your spectra has significantly different line widths, phases or large shifts. E.g. in liquid phase phantom or (potentially) pre-clinical systems. Priors can be fine tuned by altering the values in fsl_mrs.utils.constants.
--internal_ref: Set alternative metabolites for internal reference scaling (default is tCr = Cr + PCr). Multiple arguments can be specified for a combined internal reference.
--wref_metabolite: Set alternative water scaling reference or references (default is PCr+Cr). Must be used if none of Cr, PCr and NAA are present in the basis set.
--ref_protons: Number of protons that the water scaling reference is equivalent to (between defined integration limits). E.g. Cr is equivalent to 5 between 2 and 5 ppm. Only active when –wref_metabolite is used.
--ref_int_limits: Integration limits for water scaling reference. Only active when –wref_metabolite is used.
--t1-values / --t2-values: Specify custom t1 and/or t2 values by providing a JSON formatted file(s) containing values for H2O_WM, H2O_GM, H2O_CSF and METAB.

The wrapper scripts can also take a configuration file as an input. For example, say we have a text file called config.txt which contains the below:

# Any line beginning with this is ignored
ppmlim       = [0.3,4.1]
metab_groups = combine_all
TE           = 11
report

The the following calls to fsl_mrs or fsl_mrsi are equivalent:

fsl_mrs --config config.txt

fsl_mrs --ppmlim .3 4.1 --metab_groups combine_all --TE 11 --report

References

[CLAR21]

Clarke WT, Stagg CJ, Jbabdi S. FSL-MRS: An end-to-end spectroscopy analysis package. Magnetic Resonance in Medicine 2021;85:2950–2964 doi: 10.1002/mrm.28630.