FSL-MRS is a collection of python modules and wrapper scripts for pre-processing and model fitting of Magnetic Resonance Spectroscopy (MRS) data.
---
### Installation
## Installation
#### Conda package
The primary installation method is via _conda_. After installing conda and creating or activating a suitable [environment](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html) you can install FSL-MRS from the FSL conda channel.
### Conda package
The primary installation method is via _conda_. First you should install conda and creating a suitable [environment](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html). For example, in the base conda environment execute:
The spec2nii package can be installed to convert data to NIfTI format.
conda install -c conda-forge spec2nii
or
pip install spec2nii
After installation see the [quick start guide](https://open.win.ox.ac.uk/pages/fsl/fsl_mrs/quick_start.html).
---
### Content
## Content
#### Scripts:
### Scripts:
-**fsl\_mrs**
: fit a single voxel spectroscopy (SVS) spectrum
...
...
@@ -53,13 +54,13 @@ After installation see the [quick start guide](https://open.win.ox.ac.uk/pages/f
-**mrs_vis**
: quick visualisation of the spectra or basis spectra
-**mrs_info**
: quick information on NIfTIMRS file
: quick information on a NIfTI-MRS file
-**svs_segment & mrsi_segment**
: Run tissue segmentation for SVS/MRSI from T1 image.
---
### Documentation
## Documentation
Documentation can be found online on the [WIN open science website](https://open.win.ox.ac.uk/pages/fsl/fsl_mrs/).
...
...
@@ -67,23 +68,27 @@ For each of the wrapper scripts above, simply type `<name_of_script> --help` to
Example command-line usage is demonstrated in the packaged [Jupyter Notebook](https://git.fmrib.ox.ac.uk/saad/fsl_mrs/-/blob/master/example_usage/Example%20SVS%20processing%20-%20command-line.ipynb.).
### File types
## Getting help
Please seek help via the [FSL JISC email list](mailto:FSL@JISCMAIL.AC.UK) or by submitting an issue on the [FSL-MRS Github mirror](https://github.com/wexeee/fsl_mrs/issues).
FSL-MRS accepts FID data in NIfTI + JSON format. Some scripts can also read .RAW (LCModel) and text (jMRUI).
## File types
Conversion to NIfTI is provided by [spec2nii](https://github.com/wexeee/spec2nii).
FSL-MRS accepts FID data in NIfTI-MRS format. Some scripts can also read .RAW (LCModel) and text (jMRUI).
### Working in python
Conversion to NIfTI-MRS is provided by [spec2nii](https://github.com/wexeee/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](https://git.fmrib.ox.ac.uk/saad/fsl_mrs/-/blob/master/example_usage/Example%20SVS%20processing%20-%20interactive%20notebook.ipynb))
---
### Permissions and citations
## 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. Biorxiv 2020
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](https://git.fmrib.ox.ac.uk/saad/fsl_mrs/-/blob/master/LICENSE) file for licensing information.
Installation with conda is easy, but you won't get the packaged example data and notebooks. This can be downloaded separately here: |fslmrs_pkg_data|_.
spec2nii
~~~~~~~~
To convert data to NIfTI install the spec2nii program from conda.
::
conda install -c conda-forge spec2nii
Operating systems
~~~~~~~~~~~~~~~~~
FSL-MRS has been tested thoroughly on Mac and Linux operating systems. FSL-MRS dependencies and FSL-MRS is available on native Windows installations, but has not currently been tested. `Windows Subsytem for Linux <https://docs.microsoft.com/en-us/windows/wsl/install-win10>`_ (or WSL2) offers a Linux interface on Windows. FSL-MRS has been tested on WSL.
\ No newline at end of file
FSL-MRS has been tested thoroughly on Mac and Linux operating systems. FSL-MRS dependencies and FSL-MRS is available on native Windows installations, but has not currently been tested. `Windows Subsystem for Linux <https://docs.microsoft.com/en-us/windows/wsl/install-win10>`_ (or WSL2) offers a Linux interface on Windows. FSL-MRS has been tested on WSL.
@@ -30,6 +30,8 @@ For more information on coherence filters see this `reference <https://www.ncbi.
For a description of the sequence file parameters see the :ref:`sequence file <seq_file_params>` page. Alternatively see the examples in the simulator package (examplePRESS.json & exampleSTEAM.json).
Please note that delays in the sequence description file do not include the duration of the pulse. I.e., the time from the centroid to the start/end of the RF pulse must be added to the delay to calculate the time between pulse centroids.
# Example of SVS processing - interactive notebook
%% Cell type:markdown id: tags:
This notebook demos the process of fitting a single voxel scan in an interactive notebook using the underlying python libraries in FSL-MRS.
To view the plots in this notebook in Jupyter please consult the [plotly getting-started guide](https://plotly.com/python/getting-started/#jupyterlab-support-python-35).
### Contents:
1.[File conversion using spec2nii](#1.-File-conversion-using-spec2nii)
3.[Fitting of the resultant spectrum](#3.-Fitting)
4.[Display of fitting results in a notebook](#4.-Display)
Will Clarke
June 2020
University of Oxford
%% Cell type:markdown id: tags:
## 1. File conversion using spec2nii
__THIS IS DONE ON THE COMMAND LINE__
Run spec2nii twix -v to establish the file contents, then using this information run spec2nii twix -e with the appropriate flags to extract the required scans. The -q flag suppresses text output.
This dataset uses a modified versions of the CMRR spectro package sequences on a Siemens scanner. It has three sets of water reference scans. The first is tagged as a phase correction, ans is collected at the start of the main suppressed water scan and will be used for eddy current correction.
The second is collected in a separate scan with only the RF portion of the water suppression disabled. This is used for coil combination (and could be used for eddy current correction). The third is collected with the OVS and all aspects of the water suppression disabled. It therefore experiences eddy currents unlike all the other scans. It will be used for final concentration scaling.
From the final lines of the output of the first cell we can see that this "twix" file contains two groups of data.
The first is tagged as "image" and contains 64 repetitions (sets) of 4096 point FIDs collected on 32 channels.
The second has a single FID on each channel.
We now call spec2nii again specifying the group we want to extract each time. Each call to spec2nii will generate a NIfTI MRS file with a size of 1x1x1x4096x32xNdyn, where Ndyn is the number of dynamics (repeats).
We repeat this for the water reference scans, extracting just the image data.
In this section we will preprocess the data using functions in the preproc package in fsl_mrs. This example could be used as a template to construct your own preprocessing script in python.
#### Description of steps
0. Load the data
1. Take averages of water references used for combination across files
2. Coil combine the metab data, the ecc data and the quantification data using the "comb" data as the reference.
3. Phase and frequency align the data where there are multiple transients.
4. Combine data across those transients by taking the mean.
5. Run eddy current correction using the appropriate reference.
6. In this data an additional FID point is collected before the echo centre. Remove this.
7. Run HLSVD on the data to remove the residual water in the water suppressed data.
6. Phase the data by a single peak as a crude zero-order phase correction.
%% Cell type:code id: tags:
``` python
importfsl_mrs.utils.mrs_ioasmrs_io
```
%% Cell type:markdown id: tags:
#### 0. Load data
Load all the data into lists of data using the mrs_io.read_FID function
- Read pre-baked basis file (this one was generated with `fsl_mrs_sim`).
- Create main MRS object.
- Prepare the data for fitting (this does additional checks such as whether the data needs to be conjugated, and scales the data to improve fitting robustness)
