Skip to content

wtclarke/fsl_mrs

Repository files navigation

FSL-MRS

Description

FSL-MRS is a collection of python modules and wrapper scripts for pre-processing and model fitting of Magnetic Resonance Spectroscopy (MRS) data.


Installation

Conda package

The primary installation method is via conda. First you should install conda and creating a suitable environment. For example, in the base conda environment execute:

conda create --name fsl_mrs -c conda-forge python=3.11

Then activate the environment:

conda activate fsl_mrs

Finally install FSL-MRS and its dependencies from the FSL conda channel.

conda install -c conda-forge -c defaults \
              -c https://fsl.fmrib.ox.ac.uk/fsldownloads/fslconda/public/ \
              fsl_mrs

Source code

To get the source code with the packaged example data, make sure git-lfs is installed.

git clone --recurse-submodules https://git.fmrib.ox.ac.uk/fsl/fsl_mrs.git
cd fsl_mrs
pip install .

After installation see the quick start guide.


Content

Scripts:

  • fsl_mrs : fit a single voxel spectroscopy (SVS) spectrum
  • fsl_mrsi : fit a 3D volume of 1D spectra
  • fsl_mrs_proc : pre-processing (coil combination, averaging, phase correction, outlier rejection, water suppression, eddy-current correction)
  • fsl_mrs_preproc : Pre-packaged processing for non-edited SVS.
  • fsl_mrs_sim : simulate basis spectra
  • mrs_tools : Collection of tools for NIfTI-MRS. Includes quick visualisation and information.
  • basis_tools : Collection of tools for manipulating basis sets.
  • svs_segment & mrsi_segment : Run tissue segmentation for SVS/MRSI from T1 image.
  • results_to_spectrum : Generate spectrum representation of a fit from fsl_mrs results.

Documentation

Documentation can be found online on the WIN open science website.

For each of the wrapper scripts above, simply type <name_of_script> --help to get the usage.

Example command-line usage is demonstrated in the packaged Jupyter Notebook.

Getting help

Please seek help via the FSL JISC email list or by submitting an issue on the FSL-MRS Github mirror.

File types

FSL-MRS accepts FID data in NIfTI-MRS format. Some scripts can also read .RAW (LCModel) and text (jMRUI).

Conversion to NIfTI-MRS is provided by spec2nii.

Working in python

If you don't want to use the wrapper scripts, you can use the python modules directly in your own python scripts/programs. Or in an interactive Python environment (see example notebook)


Permissions and citations

If you use FSL-MRS in your research please cite:

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

Please see the LICENSE file for licensing information.