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


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

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

---
### Installation 

11
12
13
14
15
16
17
18
19
20
#### Conda package
The primary installation method is via _conda_. After installing conda and creating or activating a suitable [enviroment](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 install -c conda-forge \
                  -c https://fsl.fmrib.ox.ac.uk/fsldownloads/fslconda/channel/ \
                  fsl_mrs

#### Source code

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

    git clone --recurse-submodules https://git.fmrib.ox.ac.uk/saad/fsl_mrs.git
Saad Jbabdi's avatar
Saad Jbabdi committed
23
24
25
    cd fsl_mrs
    pip install .

William Clarke's avatar
William Clarke committed
26
#### Dependencies
27
28
29
30
31
The spec2nii package can be installed to convert data to NIfTI format.

    conda install -c conda-forge spec2nii

or
William Clarke's avatar
William Clarke committed
32
33
34

    pip install spec2nii

Saad Jbabdi's avatar
Saad Jbabdi committed
35
After installation see the [quick start guide](https://users.fmrib.ox.ac.uk/~saad/fsl_mrs/html/quick_start.html).
William Clarke's avatar
William Clarke committed
36

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

39
40
### Content

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

- **fsl\_mrs**
Saad Jbabdi's avatar
Saad Jbabdi committed
44
: fit a single voxel spectroscopy (SVS) spectrum 
Saad Jbabdi's avatar
Saad Jbabdi committed
45
- **fsl\_mrsi**
William Clarke's avatar
William Clarke committed
46
47
: fit a 3D volume of 1D spectra 
- **fsl\_mrs\_proc**
Saad Jbabdi's avatar
Saad Jbabdi committed
48
: pre-processing (coil combination, averaging, phase correction, outlier rejection, water suppression, eddy-current correction) 
William Clarke's avatar
William Clarke committed
49
50
- **fsl\_mrs\_preproc**
: Pre-packaged processing for non-edited SVS. 
Saad Jbabdi's avatar
Saad Jbabdi committed
51
- **fsl\_mrs\_sim**
William Clarke's avatar
William Clarke committed
52
: simulate basis spectra
Saad Jbabdi's avatar
Saad Jbabdi committed
53
- **mrs_vis**
William Clarke's avatar
William Clarke committed
54
55
56
: quick visualisation of the spectra or basis spectra
- **svs_segment & mrsi_segment**
: Run tissue segmentation for SVS/MRSI from T1 image.
Saad Jbabdi's avatar
Saad Jbabdi committed
57
58
59

---

60
61
62
### Documentation

Documentation can be found online [here](https://users.fmrib.ox.ac.uk/~saad/fsl_mrs/html/index.html).
Saad Jbabdi's avatar
Saad Jbabdi committed
63
64
65

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

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

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

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

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

William Clarke's avatar
William Clarke committed
74
### Working in python
Saad Jbabdi's avatar
Saad Jbabdi committed
75

William Clarke's avatar
William Clarke committed
76
77
78
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
79

William Clarke's avatar
William Clarke committed
80
### Permissions and citations
Saad Jbabdi's avatar
Saad Jbabdi committed
81

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

William Clarke's avatar
William Clarke committed
84
    Clarke WT, Stagg CJ, Jbabdi S. FSL-MRS: An end-to-end spectroscopy analysis package. Biorxiv 2020
Saad Jbabdi's avatar
Saad Jbabdi committed
85
86

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
87
88
89
90