@@ -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|_.
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>`_
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.
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.
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.
