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

Update documentation, especially around installation.

parent 822dfa3f
# FSL-MRS # 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. 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 ### 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. 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/ \ -c https://fsl.fmrib.ox.ac.uk/fsldownloads/fslconda/channel/ \
fsl_mrs 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. 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 cd fsl_mrs
pip install . 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). 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** - **fsl\_mrs**
: fit a single voxel spectroscopy (SVS) spectrum : 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 ...@@ -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/). 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 ...@@ -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.). 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). 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). 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)) 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: 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. ...@@ -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. 3. Activate the enviroment.
...@@ -20,11 +20,11 @@ This is a short guide on setting up conda for the first time. ...@@ -20,11 +20,11 @@ This is a short guide on setting up conda for the first time.
conda activate fsl_mrs 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 5. Follow the FSL-MRS & spec2nii install instructions on the :ref:`Installation
<install>` page. <install>` page.
......
...@@ -44,7 +44,7 @@ rst_epilog = """ ...@@ -44,7 +44,7 @@ rst_epilog = """
.. _fslmrs_github_tracker: https://github.com/wexeee/fsl_mrs/issues .. _fslmrs_github_tracker: https://github.com/wexeee/fsl_mrs/issues
.. |fslmrs_pkg_data| replace:: FSL-MRS example data .. |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| replace:: developers
.. _dev_email: mailto:william.clarke@ndcn.ox.ac.uk,saad@fmrib.ox.ac.uk .. _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 ...@@ -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/ \ -c https://fsl.fmrib.ox.ac.uk/fsldownloads/fslconda/channel/ \
fsl_mrs fsl_mrs
...@@ -32,15 +32,6 @@ Example data with conda ...@@ -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|_. 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 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. 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 \ No newline at end of file
...@@ -30,6 +30,8 @@ For more information on coherence filters see this `reference <https://www.ncbi. ...@@ -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). 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 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