Commit 4a3dbcdc authored by William Clarke's avatar William Clarke
Browse files

Update documentation for issues 24, 25, 27

parent 871deed1
......@@ -4,6 +4,7 @@ This document contains the FSL-MRS release history in reverse chronological orde
-----------------------------
- Now able to choose the number of workers in fsl_mrs_sim.
- HSLVD routines now use dense (non-sparse) routine for better numerical stability
- Updates and corrections to documentation, references to new FSL Course MRS section added.
1.1.10 (Thursday 12 January 2022)
......
......@@ -43,8 +43,11 @@ rst_epilog = """
.. |fslmrs_github_tracker| replace:: FSL-MRS GitHub Issue Tracker
.. _fslmrs_github_tracker: https://github.com/wexeee/fsl_mrs/issues
.. |fslmrs_pkg_data| replace:: FSL-MRS example data
.. _fslmrs_pkg_data: https://git.fmrib.ox.ac.uk/fsl/fsl_mrs/-/archive/master/fsl_mrs-master.zip?path=example_usage/example_data
.. |fslmrs_pkg_data_notebooks| replace:: FSL-MRS example data
.. _fslmrs_pkg_data_notebooks: https://git.fmrib.ox.ac.uk/fsl/fsl_mrs/-/archive/master/fsl_mrs-master.zip?path=example_usage
.. |fsl_course| replace:: FSL Course
.. _fsl_course: https://open.win.ox.ac.uk/pages/fslcourse/website/online_materials.html
.. |dev_email| replace:: developers
.. _dev_email: mailto:william.clarke@ndcn.ox.ac.uk,saad@fmrib.ox.ac.uk
......
......@@ -37,7 +37,7 @@ To check the version installed run :code:`fsl_mrs --version`. FSL-MRS can be upd
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_notebooks|_.
Operating systems
......
......@@ -2,10 +2,20 @@
Quick Start Guide
=================
This page aims to take you though fitting your first set of data in FSL-MRS. This web-based guide is now supplemented with a dedicated MRS section in the online FSL Course.
FSL Course
----------
The `FSL Course <https://open.win.ox.ac.uk/pages/fslcourse/website/index.html>`_ now contains a dedicated section on MRS. This includes three videos on:
Summary
-------
1. `An introduction to MRS analysis <https://youtu.be/rt-oP_XNqSQ>`_
2. `MRS pre-processing <https://youtu.be/L7V5Ffhf4EM>`_
3. `MRS fitting <https://youtu.be/tLJG28Gs_xE>`_
and an `online written practical <https://open.win.ox.ac.uk/pages/fslcourse/practicals/fsl_mrs/index.html>`_. Data for the practical is available by following the `online instructions <https://open.win.ox.ac.uk/pages/fslcourse/website/downloads.html>`_.
Online Guide
------------
Below we describe an end-to-end pipeline that includes data conversion, processing, model fitting, quantification, and visualisation of the results. To apply this step to the example data provided with FSL-MRS see the `example_usage` section in the main package.
......
......@@ -4,10 +4,17 @@ Basis Spectra Simulation
========================
The linear combination fitting method used by FSL-MRS requires the user to specify basis spectra. A basis spectrum must be supplied for each fitted metabolite. The basis spectra are specific to a sequence type, the precise sequence timings and RF pulses in the sequence. Each basis spectrum is effectively a “fingerprint” for a metabolite that will be scaled and manipulated simultaneously with all the other basis spectra during the fitting optimisation. Whilst the basis spectra can be generated from scanning phantoms, the recommended way is via simulation of the spectra using either a third-party software or FSL-MRS's own density matrix simulator.
Creation of basis spectra is a difficult step in the analysis of MRS data, with plenty of pitfalls even for experienced users. Please consult with local MRS experts or the technical community on the `MRSHub forums <https://forum.mrshub.org/>`_ for assistance and recommendations. The developers of FSL-MRS are aware that this area of the analysis pipeline remains a difficult stage and efforts are continuing to improve it for users.
FSL-MRS's simulation software may be accessed through the :code:`fsl_mrs_sim` command line program. This section describes how to construct a description of your sequence, run the simulation and the format of the output basis spectra. Please see the dedicated simulation page for detailed information for the underlying simulation library.
Getting started
---------------
Creation of basis spectra is a difficult step in the analysis of MRS data, with plenty of pitfalls even for experienced users. Please consult with local MRS experts or the technical community on the `MRSHub forums <https://forum.mrshub.org/>`_ for assistance and recommendations. The developers of FSL-MRS are aware that this area of the analysis pipeline remains a difficult stage and efforts are continuing to improve it for users. To that aim we have created two resources for understanding basis set simulation in FSL-MRS:
1. The section of the online |fsl_course|_ dedicated to MRS `basis set simulation <https://open.win.ox.ac.uk/pages/fslcourse/practicals/fsl_mrs/index.html#seq_description>`_.
2. The description in this documentation and the example python notebook `Example basis spectra creation.ipynb`, downloadable from this link: |fslmrs_pkg_data_notebooks|_.
Describing a sequence – the sequence file format
------------------------------------------------
......@@ -28,7 +35,7 @@ MEGA‐PRESS [-1,1,1,-1,-1]
For more information on coherence filters see this `reference <https://www.ncbi.nlm.nih.gov/pubmed/30390346>`_. The filter must end on –1. This is the only detected coherence in the simulator.
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 packaged in the `example_usage/example_data/example_sequences` directory (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.
......
......@@ -121,7 +121,7 @@
" --MM example_data/macSeed.json \\\n",
" --overwrite \\\n",
" -e 11.0 \\\n",
" example_data/steam11.json"
" example_data/example_sequences/exampleSTEAM.json"
]
},
{
......@@ -170,4 +170,4 @@
},
"nbformat": 4,
"nbformat_minor": 4
}
\ No newline at end of file
}
%% Cell type:markdown id: tags:
# Example basis spectra creation
This notebook demos the process of creating basis spectra for fitting in FSL-MRS.
### Contents:
- [1. Sequence JSON file](#1.-Sequence-JSON-file)
- [1.1. Defining MM](#1.1-Defining-MM)
- [2. Simulation](#2.-Simulation)
- [3. Visualisation](#3.-Visualisation)
Will Clarke
June 2020
University of Oxford
%% Cell type:markdown id: tags:
## 1. Sequence JSON file
%% Cell type:markdown id: tags:
The sequence to simulate and the system parameters are descibed in a json file. The file breaks the sequence into a series of RF pulses (+ slice selcect gradients) and delays with optional rephasing gradients. A coherence filter is used to crush unwanted coherences.
%% Cell type:markdown id: tags:
## 1.1 Defining MM
An experimentally measured (or otherwise derived) macromollecues basis spectrum can be included in the basis spectrum by defining an additional JSON file.
%% Cell type:markdown id: tags:
## 2. Simulation
%% Cell type:code id: tags:
``` python
%sx fsl_mrs_sim -b example_data/metabs.txt \
-o steam_basis \
-p -2.66 \
--MM example_data/macSeed.json \
--overwrite \
-e 11.0 \
example_data/steam11.json
example_data/example_sequences/exampleSTEAM.json
```
%%%% Output: execute_result
["Identified spinsystems: ['Ala', 'Asc', 'Asp', 'GPC', 'PCh', 'Cr', 'PCr', 'GABA', 'Glc', 'Gln', 'Glu', 'GSH', 'Ins', 'Lac', 'NAA', 'NAAG', 'PE', 'Scyllo', 'Tau']",
'Simulation running using mode 1d. Axis order = [0 1 2].',
'Auto-phase adjustment. Phasing peak position = 1.99 ppm',
'Rx_Phase: 2.3408',
'Additional phase: 0.059',
'Final Rx_Phase: 2.400',
'Running simulation on Asc.',
'Simulation running using mode 1d. Axis order = [0 1 2].',
'Running simulation on Glu.',
'Simulation running using mode 1d. Axis order = [0 1 2].',
'Running simulation on NAA.',
'Simulation running using mode 1d. Axis order = [0 1 2].',
'Simulation running using mode 1d. Axis order = [0 1 2].',
'Running simulation on PCr.',
'Simulation running using mode 1d. Axis order = [0 1 2].',
'Simulation running using mode 1d. Axis order = [0 1 2].',
'Running simulation on GSH.',
'Simulation running using mode 1d. Axis order = [0 1 2].',
'Simulation running using mode 1d. Axis order = [0 1 2].',
'Simulation running using mode 1d. Axis order = [0 1 2].',
'Running simulation on GABA.',
'Simulation running using mode 1d. Axis order = [0 1 2].',
'Running simulation on Lac.',
'Simulation running using mode 1d. Axis order = [0 1 2].',
'Running simulation on Scyllo.',
'Simulation running using mode 1d. Axis order = [0 1 2].',
'Running simulation on Tau.',
'Simulation running using mode 1d. Axis order = [0 1 2].',
'Running simulation on Cr.',
'Simulation running using mode 1d. Axis order = [0 1 2].',
'Running simulation on Ins.',
'Simulation running using mode 1d. Axis order = [0 1 2].',
'Running simulation on Ala.',
'Simulation running using mode 1d. Axis order = [0 1 2].',
'Running simulation on Gln.',
'Simulation running using mode 1d. Axis order = [0 1 2].',
'Simulation running using mode 1d. Axis order = [0 1 2].',
'Running simulation on NAAG.',
'Simulation running using mode 1d. Axis order = [0 1 2].',
'Simulation running using mode 1d. Axis order = [0 1 2].',
'Simulation running using mode 1d. Axis order = [0 1 2].',
'Running simulation on Asp.',
'Simulation running using mode 1d. Axis order = [0 1 2].',
'Running simulation on Glc.',
'Simulation running using mode 1d. Axis order = [0 1 2].',
'Simulation running using mode 1d. Axis order = [0 1 2].',
'Running simulation on PCh.',
'Simulation running using mode 1d. Axis order = [0 1 2].',
'Simulation running using mode 1d. Axis order = [0 1 2].',
'Running simulation on PE.',
'Simulation running using mode 1d. Axis order = [0 1 2].']
%% Cell type:markdown id: tags:
## 3. Visualisation
%% Cell type:code id: tags:
``` python
%%capture
%sx mrs_tools vis --save basis_fig.png steam_basis
```
%% Cell type:markdown id: tags:
![basis spectra](basis_fig.png)
......
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