Commit 04855dd0 authored by William Clarke's avatar William Clarke
Browse files

Update documentation, especially around installation.

parent 822dfa3f
# FSL-MRS
### Description
## 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
## 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:
conda install -c conda-forge \
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 \
-c https://fsl.fmrib.ox.ac.uk/fsldownloads/fslconda/channel/ \
fsl_mrs
#### Source code
### Source code
To get the source code with the packaged example data, make sure [git-lfs](https://git-lfs.github.com/) is installed.
git clone --recurse-submodules https://git.fmrib.ox.ac.uk/saad/fsl_mrs.git
git clone --recurse-submodules https://git.fmrib.ox.ac.uk/fsl/fsl_mrs.git
cd fsl_mrs
pip install .
#### Dependencies
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
......@@ -59,7 +60,7 @@ After installation see the [quick start guide](https://open.win.ox.ac.uk/pages/f
---
### Documentation
## Documentation
Documentation can be found online on the [WIN open science website](https://open.win.ox.ac.uk/pages/fsl/fsl_mrs/).
......@@ -67,19 +68,22 @@ 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).
## 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](https://github.com/wexeee/spec2nii).
### Working in python
## 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:
......
......@@ -12,7 +12,7 @@ This is a short guide on setting up conda for the first time.
::
conda create --name fsl_mrs python=3.7
conda create --name fsl_mrs -c conda-forge python=3.7
3. Activate the enviroment.
......@@ -20,11 +20,11 @@ This is a short guide on setting up conda for the first time.
conda activate fsl_mrs
4. Optionally install Jupyter notebooks. This is required to run the example Jupyter notebooks.
4. Optionally install JupyterLab to access notebooks. This is required to run the example Jupyter notebooks.
::
conda install -c conda-forge notebook
conda install -c conda-forge jupyterlab
5. Follow the FSL-MRS & spec2nii install instructions on the :ref:`Installation
<install>` page.
......
......@@ -44,7 +44,7 @@ rst_epilog = """
.. _fslmrs_github_tracker: https://github.com/wexeee/fsl_mrs/issues
.. |fslmrs_pkg_data| replace:: FSL-MRS example data
.. _fslmrs_pkg_data: https://users.fmrib.ox.ac.uk/~wclarke/fsl_mrs/example_usage.zip
.. _fslmrs_pkg_data: https://git.fmrib.ox.ac.uk/fsl/fsl_mrs/-/archive/master/fsl_mrs-master.zip?path=example_usage/example_data
.. |dev_email| replace:: developers
.. _dev_email: mailto:william.clarke@ndcn.ox.ac.uk,saad@fmrib.ox.ac.uk
......
......@@ -23,7 +23,7 @@ The primary installation method is via *conda*. After installing conda and creat
::
conda install -c conda-forge \
conda install -c conda-forge -c defaults \
-c https://fsl.fmrib.ox.ac.uk/fsldownloads/fslconda/channel/ \
fsl_mrs
......@@ -32,15 +32,6 @@ Example data with conda
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.
\ No newline at end of file
......@@ -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.
Using fsl_mrs_sim
-----------------
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment