README.md 3.44 KB
Newer Older
1
# FSL-MRS
Saad Jbabdi's avatar
Saad Jbabdi committed
2
3


4
## Description
Saad Jbabdi's avatar
Saad Jbabdi committed
5

Saad Jbabdi's avatar
Saad Jbabdi committed
6
7
8
FSL-MRS is a collection of python modules and wrapper scripts for pre-processing and model fitting of Magnetic Resonance Spectroscopy (MRS) data.

---
9
## Installation 
Saad Jbabdi's avatar
Saad Jbabdi committed
10

11
12
### 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: 
13

14
15
16
17
18
19
20
21
22
23
    conda create --name fsl_mrs -c conda-forge python=3.8

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 \
24
25
26
                  -c https://fsl.fmrib.ox.ac.uk/fsldownloads/fslconda/channel/ \
                  fsl_mrs

27
### Source code
28
29

To get the source code with the packaged example data, make sure [git-lfs](https://git-lfs.github.com/) is installed.
30

31
    git clone --recurse-submodules https://git.fmrib.ox.ac.uk/fsl/fsl_mrs.git
Saad Jbabdi's avatar
Saad Jbabdi committed
32
33
34
    cd fsl_mrs
    pip install .

William Clarke's avatar
William Clarke committed
35

36
After installation see the [quick start guide](https://open.win.ox.ac.uk/pages/fsl/fsl_mrs/quick_start.html).
William Clarke's avatar
William Clarke committed
37

Saad Jbabdi's avatar
Saad Jbabdi committed
38
---
Saad Jbabdi's avatar
Saad Jbabdi committed
39

40
## Content
41

42
### Scripts:
Saad Jbabdi's avatar
Saad Jbabdi committed
43
44

- **fsl\_mrs**
Saad Jbabdi's avatar
Saad Jbabdi committed
45
: fit a single voxel spectroscopy (SVS) spectrum 
Saad Jbabdi's avatar
Saad Jbabdi committed
46
- **fsl\_mrsi**
William Clarke's avatar
William Clarke committed
47
48
: fit a 3D volume of 1D spectra 
- **fsl\_mrs\_proc**
Saad Jbabdi's avatar
Saad Jbabdi committed
49
: pre-processing (coil combination, averaging, phase correction, outlier rejection, water suppression, eddy-current correction) 
William Clarke's avatar
William Clarke committed
50
51
- **fsl\_mrs\_preproc**
: Pre-packaged processing for non-edited SVS. 
Saad Jbabdi's avatar
Saad Jbabdi committed
52
- **fsl\_mrs\_sim**
William Clarke's avatar
William Clarke committed
53
: simulate basis spectra
54
55
- **mrs_tools**
: Collection of tools for NIfTI-MRS. Includes quick visualisation and information.
William Clarke's avatar
William Clarke committed
56
57
- **basis_tools**
: Collection of tools for manipulating basis sets.
William Clarke's avatar
William Clarke committed
58
59
- **svs_segment & mrsi_segment**
: Run tissue segmentation for SVS/MRSI from T1 image.
60
61
- **results_to_spectrum**
: Generate spectrum representation of a fit from *fsl_mrs* results.
Saad Jbabdi's avatar
Saad Jbabdi committed
62
63
---

64
## Documentation
65

66
Documentation can be found online on the [WIN open science website](https://open.win.ox.ac.uk/pages/fsl/fsl_mrs/).
Saad Jbabdi's avatar
Saad Jbabdi committed
67
68
69

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

William Clarke's avatar
William Clarke committed
70
71
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.).

72
73
74
75
## 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).

## File types
Saad Jbabdi's avatar
Saad Jbabdi committed
76

William Clarke's avatar
William Clarke committed
77
FSL-MRS accepts FID data in NIfTI-MRS format. Some scripts can also read .RAW (LCModel) and text (jMRUI).
Saad Jbabdi's avatar
Saad Jbabdi committed
78

William Clarke's avatar
William Clarke committed
79
Conversion to NIfTI-MRS is provided by [spec2nii](https://github.com/wexeee/spec2nii).
Saad Jbabdi's avatar
Saad Jbabdi committed
80

81
## Working in python
Saad Jbabdi's avatar
Saad Jbabdi committed
82

William Clarke's avatar
William Clarke committed
83
84
85
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)) 

---
Saad Jbabdi's avatar
Saad Jbabdi committed
86

87
## Permissions and citations
Saad Jbabdi's avatar
Saad Jbabdi committed
88

William Clarke's avatar
William Clarke committed
89
If you use FSL-MRS in your research please cite:
Saad Jbabdi's avatar
Saad Jbabdi committed
90

William Clarke's avatar
William Clarke committed
91
92
    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.

Saad Jbabdi's avatar
Saad Jbabdi committed
93
94

Please see the [LICENSE](https://git.fmrib.ox.ac.uk/saad/fsl_mrs/-/blob/master/LICENSE) file for licensing information.
Saad Jbabdi's avatar
Saad Jbabdi committed
95
96
97
98