Fitting MRSI

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 or p-spline complex baseline.

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

Command-line script

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)

  • A file-tree file (mrsi.tree) that contains the folder and file structure information.

The above outputs can be visualised in FSLeyes alongside the original data. See instructions on how to best load MRSI results.

Python & Interactive Interface

Fitting for MRSI data can also be run in an interactive Python environment with fslpy.

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

from fsl.wrappers import fsl_mrsi

fsl_mrsi(
    data='metab.nii.gz',
    basis='3T_slaser_32vespa_1250_wmm',
    output='fit',
    metab_groups=['MM09', 'MM12', 'MM14', 'MM17', 'MM21'],
    h2o='wref.nii.gz',
    TE='30',
    TR='2.0',
    mask='mask.nii.gz',
    tissue_frac=['mrsi_seg_wm.nii.gz',
                 'mrsi_seg_gm.nii.gz',
                 'mrsi_seg_csf.nii.gz'],
    output_correlations=True,
    overwrite=True,
    combine=['Cr', 'PCr'],
)

Details

Modelling, Algorithms and Wrapper options

The main options for modelling, optimisation algorithms and wrapper optional arguments are common between fsl_mrsi and fsl_mrs commands. See Fitting SVS for details.

Advanced fsl_dynmrs options

Common options for dynamic fitting can be found in Dynamic Fitting. Below are detailed explanations of some additional MRSI-specific options.

--spatial-mask SPATIAL_MASK

A NIfTI binary mask for selecting which MRSI voxels to fit. If not provided, all voxels will be fitted.

--spatial-index X Y Z

Spatial index of a single MRSI voxel to fit. If not provided, all voxels will be fitted.

--mean_mrsi

If provided, the mean FID across MRSI voxels will also be fitted.

Parallel processing

Both fsl_mrsi and fsl_dynmrs use Dask for parallel processing across MRSI voxels. The following options are available for both commands.

--parallel PARALLEL

Control parallelisation. Set to: ‘off’, ‘local’ (default), or ‘cluster’. ‘off’ forces serial processing, ‘local’ parallelises over local CPUs, ‘cluster’ distributes over HPC SLURM nodes. See documentation for cluster configuration.

--parallel-workers PARALLEL_WORKERS

Number of cores (local), or workers (cluster) to use.

References