Commit b823bdef authored by Saad Jbabdi's avatar Saad Jbabdi
Browse files

more doc

parent 4dc8990e
......@@ -111,7 +111,7 @@ Modelling
At the core of FSL-MRS is a linear combination model. For more details on the modelling refer to [CLAR20]_.
The signal in the spectral domain :math:`\mathrm{Y}(v)` is modelled as a linear combination of (shifted and broadened) metabolite basis spectra plus a complex baseline :math:`\mathrm{B}(v)` and
The signal in the spectral domain :math:`\mathrm{Y}(v)` is modelled as a linear combination of (shifted and broadened) metabolite basis spectra :math:`\mathrm{M}_{l,g}` (metab = :math:`l`, metab group = :math:`g`) plus a complex polynomial baseline :math:`\mathrm{B}(v)`. The signal model is as follows:
.. math::
......@@ -120,10 +120,69 @@ The signal in the spectral domain :math:`\mathrm{Y}(v)` is modelled as a linear
M_{l, g}\left(v ; \gamma_{g}, \epsilon_{g}\right)=\mathcal{FFT}\left\{m_{l, g}(t) \exp \left[-\left(\left(\gamma_{g}+\sigma_{g}^{2} t\right)+i \epsilon_{g}\right) t\right]\right\}
\end{array}
Model parameters are summarised in the below table:
========================== ============================================================ ============
Symbol Name Units
========================== ============================================================ ============
:math:`\phi_0` zero-th order global phase rad
:math:`\phi_1` first order global phase rad/Hz
:math:`\epsilon_g` line shift for metab group :math:`g` rad/sec
:math:`\gamma_g` line broadening (Lorentizian) for metab group :math:`g` Hz
:math:`\sigma_g` line broadening (Gaussian) for metab group :math:`g` Hz
:math:`\mathrm{C}_{l,g}` concentration for metabolite :math:`l` in group :math:`g` A.U.
========================== ============================================================ ============
Wrapper options
~~~~~~~~~~~~~~~
Type :code:`fsl_mrs --help` to get the full set of available options.
Below are detailed explanations of some of the optional arguments in the wrapper scripts. Type :code:`fsl_mrs --help` or :code:`fsl_mrsi --help` to get the full set of available options.
:code:`--algo ALGO`
Algorithm to be used in the fitting. Either *Newton* (default) or *MH*. if *MH* is selected, the Metropolis hastings algorithm is run, initialised using the Newton algorithm (Truncated Newton as implemented in Scipy).
:code:`--ignore`
List of metabolites to be removed from the basis file prior to fitting.
:code:`--keep`
List of metabolites to include in the fitting, all other metabolites are excluded from the fitting
:code:`--combine`
Combine sets of metabolites (not in the fitting, only in the quantification/display) - this option is repeatable.
:code:`--ppmlim`
Only calculate the loss function within this ppm range.
:code:`--baseline_order`
Polynomial baseline order. Set to -1 to remove the baseline altogether.
:code:`--metab_groups`
Group metaboites into sub-groups that get their own lineshape parameters (shift and broadening). This can either be a list of integers (one per metabolite) from 0 to the max number of groups minus one. Or it could be a list of metabolites to be grouped. E.g. using the flag :code:`--metab_groups Mac NAA+NAAG+Cr` then the Mac spectrum will have its own group, the NAA, NAAG, and Cr will be in a different group, and all other metabolites in a 3rd group. Other possibilities are combine_all and separate_all, where metabs are combined into a single group or separated into distinct groups respectively.
:code:`--add_MM`
Add macromolecule peaks at the following frequencies: 0.9, 1.2, 1.4, 1.7 ppm and a doublet at 2.08 & 3.0 ppm
:code:`--lorentzian`
By default the lineshape is a Voigt (lorentizian+gaussian). Use this flag to set to Lorentzian.
The wrapper scripts can also take a configuration file as an input. For example, say we have a text file called :code:`config.txt` which contains the below:
::
# Any line beginning with this is ignored
ppmlim = [0.3,4.1]
metab_groups = combine_all
TE = 11
add_MM
report
The the following calls to :code:`fsl_mrs` or :code:`fsl_mrsi` are equivalent:
::
fsl_mrs --config config.txt
::
fsl_mrs --ppmlim .3 4.1 --metab_groups combine_all --TE 11 --add_MM --report
References
----------
......
Reports and Visualisation
=========================
Data and analysis results can be viewed in a number of ways in FSL-MRS, and at all stages of processing.
There are 4 ways of visualising/interacting with MRS data in FSL-MRS:
1. Quick glance (human-readable, non-interactive)
2. CSV files (human- and machine-readable)
3. HTML reports (fairly interactive)
#. FSLeyes (highly interactive)
1. Quick glance
---------------
The first thing one might want to do when given a FID file or simulated spectra is to have a quick look at the FFTs to see if they look like one would expect. FSL-MRS provides a light-weight script (:code:`mrs_vis`) to quickly glance at the MRS or MRSI data. For example, running :code:`mrs_vis` on the provided example SVS data:
::
mrs_vis example_usage/example_data/metab.nii
gives the following basic plot:
.. image:: data/mrs_vis_svs.png
:width: 400
Note that the reason :code:`mrs_vis` "knows" how to scale the x-axis is that the relevant information is stored in the JSON sidecar (namely the *dwell time* and the *central frequency*).
We can also run :code:`mrs_vis` to visualise the metabolite basis. Again below we do so for the simulated basis provided with the example data:
::
mrs_vis example_usage/example_data/steam_11ms/
.. image:: data/mrs_vis_basis.png
:width: 400
Additionally, the :code:`fsl_mrs` and :code:`fsl_mrsi` wrapper scripts output a PNG file (**fit_summary.png**) that summarises the fitting (overlays the FID spectrum, baseline, and model prediction). An example such file is shown below:
.. image:: data/fit_summary.png
:width: 400
When a T1 image is provided, the SVS voxel location is also shown both the HTML reports and in a PNG file (**voxel_location.png**):
.. image:: data/voxel_location.png
:width: 600
2. CSV files
------------
The FSL-MRS wrapper scripts generate several CSV files containing the fitted concentrations, QC values, and MCMC samples (when using the flag :code:`--algo MH`). These can be read out by another tool (e.g. Pandas) for further analyses/statistics.
3. HTML Reports
---------------
FSL-MRS can generate interactive HTML reports either through the wrapper scripts (:code:`fsl_mrs` and :code:`fsl_mrsi`) or from within a python script or IPython/Jupyter Notebook session. The interactive visualisation uses the Plotly library and allows one to interrogate the FID data and fitting, as well as looking at the correlation between fitted concentrations, uncertainties, and visualising single metabolite spectra alongside the data.
4. FSLeyes
----------
A very powerful way to visualise MRS data is FSLeyes (for compatibility with FSL-MRS, this requires FSLeyes version 0.32.0 or later). This is particularly useful for MRSI data, where we can simultaneously view the spectrum and fitted model alongside the anatomical image and interactively navigate from voxel to voxel.
Below are instructions for loading and configuring FSLeyes to work with MRSI data. Say the input FID (used for fitting) is :code:`FID_Metab.nii.gz` and the output from :code:`fsl_mrsi` is a folder called :code:`mrsi_output`. You can load these data into FSLeyes with:
::
fsleyes mrsi_out/{fit.nii.gz,baseline.nii.gz,residual.nii.gz} FID_Metab.nii.gz T1.nii &
Then open *View=>Power Spectra*, select the FID/fit/baseline/residuals as required for display.
Now to make the powerspetrum display nicely, we need to change the x-axis scaling/shifting to be compatible with MRS conventions (shifted PPM). Open the Power spetrum control panel, and do the following:
- Invert X axis
- Set X axis scale to 1/{central frequency}
- Set X axis offset to 4.65 (Shift of water to Tetramethylsilane)
- Untick "Autoscale X" and Set X axis limits to a desired PPM range (e.g. [.2,4.2])
- Untick "Normalise to unit variance"
You should be able to see something like this (after playing around with changing the colours and the panel locations):
.. image:: data/fsleyes.png
:width: 700
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