README.md 3.28 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
- **svs_segment & mrsi_segment**
: Run tissue segmentation for SVS/MRSI from T1 image.
Saad Jbabdi's avatar
Saad Jbabdi committed
58
59
60

---

61
## Documentation
62

63
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
64
65
66

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

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

69
70
71
72
## 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
73

William Clarke's avatar
William Clarke committed
74
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
75

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

78
## Working in python
Saad Jbabdi's avatar
Saad Jbabdi committed
79

William Clarke's avatar
William Clarke committed
80
81
82
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
83

84
## Permissions and citations
Saad Jbabdi's avatar
Saad Jbabdi committed
85

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

William Clarke's avatar
William Clarke committed
88
89
    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
90
91

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
92
93
94
95