Commit 03a80b45 authored by William Clarke's avatar William Clarke
Browse files

Update docs.

parent dcade702
/* override table width restrictions */
/* https://rackerlabs.github.io/docs-rackspace/tools/rtd-tables.html*/
@media screen and (min-width: 767px) {
.wy-table-responsive table td {
/* !important prevents the common CSS stylesheets from overriding
this as on RTD they are loaded after this stylesheet */
white-space: normal !important;
}
.wy-table-responsive {
overflow: visible !important;
}
}
\ No newline at end of file
......@@ -76,4 +76,10 @@ html_theme = 'sphinx_rtd_theme'
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = []
\ No newline at end of file
html_static_path = ['_static']
html_context = {
'css_files': [
'_static/theme_overrides.css', # override wide tables in RTD theme
],
}
......@@ -43,4 +43,4 @@ To convert data to NIfTI install the spec2nii program from conda.
Operating systems
~~~~~~~~~~~~~~~~~
FSL-MRS has been tested throughly on Mac and Linux operating systems. FSL-MRS dependencies and FSL-MRS is availible 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 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
.. _processing:
Processing
==========
**For SVS**
......@@ -62,6 +63,7 @@ Merging processing HTML reports
merge_mrs_reports -d [description] -o [output folder] -f [report name] *.html
.. _fsl_mrs_preproc:
fsl_mrs_preproc
---------------
......@@ -78,6 +80,8 @@ Optionally the user may specify any of the following:
- `--hlsvd`: Apply HLSVD to remove residual water
- `--leftshift POINTS`: Truncate FID at start by POINTS.
The :code:`--ecc` option should be used to provide water reference data for eddy current correction. I.e. the data has experienced all gradients that the primary water suppressed data has. Conversely the :code:`--quant` option should be used to provide water reference data purely for final water reference scaling. The water reference data provided using the :code:`--reference` option will always be used for coil combination (if required) and if :code:`--quant` or :code:`--ecc` haven't been specified it will be used for quantification and ECC respectively.
Python & Interactive Interface
------------------------------
......
......@@ -11,15 +11,48 @@ Below we describe an end-to-end pipeline that includes data conversion, processi
1. Convert your data
~~~~~~~~~~~~~~~~~~~~
Before running FSL-MRS time domain data must be prepared in a complex 4D-NIFTI or ASCII based format. The formats accepted are described below. The recommended format is NIfTI + json which can be created by running the accompanying spec2nii tool (see :ref:`Data Conversion <data_conversion>`).
Before running FSL-MRS, time domain data must be prepared in a complex 4D-NIFTI + json format. You can do this by running the accompanying spec2nii tool (see :ref:`Data Conversion <data_conversion>`).
Example conversion::
spec2nii dicom -f my_metab_file -j metab.dcm
This will convert the dicom file (metab.dcm) to a NIfTI file named my_metab_file.nii and because the -j option was specified, a JSON file called my_metab_file.json.
This will convert the dicom file (metab.dcm) to a NIfTI file named my_metab_file.nii and because the -j option was specified, a JSON file called my_metab_file.json. Conversion of other formats is possible by changing the first argument "dicom" to another option. For a list of supported formats see :ref:`Data Conversion <data_conversion>`.
For a list of supported formats see :ref:`Data Conversion <data_conversion>`.
A directory of DICOM data can also be converted::
spec2nii dicom -f my_metab_file -j ./dcm_metab_dir/
The output of the above command will be `my_metab_file_000.nii.gz, *_001.nii.gz, *_002.nii.gz, ...` continuing up to the number of DICOM instances in the directory. This number should match the number of transients acquired in an SVS sequence. There will also be matching JSON files: `my_metab_file_000.json, *_001.json, *_002.json, ...`
You might need to covert multiple files to process a single spectroscopy acquisition. A typical single voxel dataset will have both water suppressed and water unsuppressed data. Depending on format these might be contained in a single raw data file or be spread over two or more. Some protocols may acquire additional data to be used in pre-processing, e.g. for eddy-current correction. These files should be converted with a different name::
spec2nii dicom -f my_wref_file -j ./dcm_wref_dir/
spec2nii dicom -f my_ecc_file -j ./dcm_ecc_dir/
But note that there are frequently multiple calibration scans for e.g. shimming and water suppression calibration acquired before the actual MRS acquisition. These files aren't used for analysis and can be safely ignored.
1.1 Take a look at your data
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
You can use :code:`mrs_vis` on the command line to view your data at any stage of the process::
mrs_vis my_metab_file_000.nii.gz
You should see some **noisy** data
.. image:: data/raw_conv.png
:width: 600
You can also see all the converted data in a directory::
mrs_vis ./my_conv_data/
.. image:: data/mrs_vis_dir.png
:width: 600
If you see a significantly different picture (no data, just noise, etc.) stop and investigate. See :ref:`Troubleshooting <TS_4>`.
Have a look at the :ref:`Visualisation <visualisation>` page for more information on :code:`mrs_vis`.
2. Process your raw data
~~~~~~~~~~~~~~~~~~~~~~~~
......@@ -37,21 +70,23 @@ The -r requests a HTML report to be generated for each stage of the processing.
merge_mrs_reports -d example_processing -o . *.html
If your data is unedited single voxel (SVS) try out the prepackaged processing pipeline :code:`fsl_mrs_preproc`. You will need to identify the water suppressed and water unsuppressed files to pass to the script.
If your data is unedited single voxel (SVS) try out the prepackaged processing pipeline :code:`fsl_mrs_preproc`. You will need to identify the water suppressed and water unsuppressed files to pass to the script. For details on which water reference to use if you have multiple see the :ref:`fsl_mrs_preproc <fsl_mrs_preproc>` section of the :ref:`processing <processing>` page.
::
fsl_mrs_preproc --output my_subj --data metab*.nii.gz --reference wref*.nii.gz --report
fsl_mrs_preproc --output processed --data my_metab_file*.nii.gz --reference my_wref_file*.nii.gz --report
Have a look at the source code for :code:`fsl_mrs_preproc` to see how you can construct your own python script using the processing modules. You can always prototype using Jupyter/IPython (see :ref:`Demos <demos>`)
3. Create Basis Spectra
~~~~~~~~~~~~~~~~~~~~~~~
If someone has provided you basis spectra, or you have an existing set in *.BASIS* format you can skip this section and go to step 4.
The fitting in FSL-MRS requires the user to provide basis spectra. Basis spectra are the simulated responses of the in vivo metabolites to the pulse sequence. FSL-MRS provides a simulator to create basis sets :code:`fsl_mrs_sim`::
fsl_mrs_sim -b metabs.txt my_sequence_description.json
my_sequence_description.json contains a description of the sequence broken down into blocks of RF pulses and gradients. Much more information on constructing a suitable sequence description JSON file can be found on the :ref:`Basis Spectra Simulation <simulation>` page.
`my_sequence_description.json` contains a description of the sequence broken down into blocks of RF pulses and gradients. This must be created for each sequence manually once. `metabs.txt` contains a list of metabolites to simulate. Much more information on constructing a suitable sequence description JSON file can be found on the :ref:`Basis Spectra Simulation <simulation>` page.
Have a quick check of your basis set using mrs_vis::
......@@ -61,14 +96,15 @@ Have a quick check of your basis set using mrs_vis::
~~~~~~~~~~~~~~~~~~~~~~
For FSL-MRS to produce accurate water scaled molarity or molality concentrations from the fitting results, it must be provided with estimates of the tissue (GM, WM, CSF) fractions in each voxel.
For this FSL-MRS provides the :code:`svs_segment` and :code:`mrsi_segment` commands.::
For this FSL-MRS provides the :code:`svs_segment` or :code:`mrsi_segment` commands for SVS and MRSI data respectively.::
svs_segment -t T1.nii.gz svs_data.nii.gz
svs_segment -t T1.nii.gz processed/metab.nii.gz
mrsi_segment -t T1.nii.gz mrsi_data.nii.gz
:code:`svs_segment` creates a small JSON file which can be passed to the fitting routines. :code:`mrsi_segment` creates NIfTI files of the fractional tissue volumes registered to the MRSI volume.
:code:`svs_segment` creates a small JSON file `segmentation.json` which can be passed to the fitting routines. :code:`mrsi_segment` creates NIfTI files of the fractional tissue volumes registered to the MRSI volume.
:code:`svs_segment` and :code:`mrsi_segment` both rely on `fsl_anat <https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/fsl_anat>`_ to run FSL FAST tissue segmentation. If fsl_anat has already been run, then the :code:`-t T1.nii.gz` option can be substituted with :code:`-a T1.anat`.
Inputs to the segment commands are raw T1 images (i.e. not skull stripped) or the output of fsl_anat (FSL FAST segmentation must have been run).
5. Fitting
~~~~~~~~~~
......@@ -76,7 +112,7 @@ FSL-MRS provides two wrapper scripts for fitting: :code:`fsl_mrs` (for SVS data)
::
fsl_mrs --data metab.nii.gz --basis my_basis_spectra --output example_svs --h2o wref.nii.gz --tissue_frac tissue_frac.json --report
fsl_mrs --data metab.nii.gz --basis my_basis_spectra --output example_svs --h2o wref.nii.gz --tissue_frac segmentation.json --report
fsl_mrsi --data mrsi.nii.gz --basis my_basis_spectra --output example_mrsi --h2o wref.nii.gz --mask mask.nii.gz --tissue_frac WM.nii.gz GM.nii.gz CSF.nii.gz --report
......@@ -92,5 +128,17 @@ For visualising MRSI data, fits, and fitting results, `FSLeyes
Demos
-----
Two demo Jupyter notebooks are provided alongside some sample data in the `example_usage` directory. These notebooks show an example processing pipeline implemented both on the command-line and in interactive python.
Two demo Jupyter notebooks are provided alongside some sample data in the `example_usage` directory. These notebooks show an example processing pipeline implemented both on the command-line and in interactive python.
To access these clone the |fslmrs_gitlab|_ with `Git LFS <https://git-lfs.github.com/>`_ installed, or download directly from |fslmrs_pkg_data|_.
You will need to have jupyter notebook installed::
conda install -c conda-forge notebook
Then start the notebook::
cd example_usage
jupyter-notebook
A window should open in your browser and you can select one of the four example notebooks.
.. _seq_file_params:
:orphan:
Sequence description parameters
===============================
.. csv-table::
:header: "Field", "Value type", "Description", "Required", "Example value"
:widths: 15, 10, 30, 10, 30
sequenceName, Str, Yes, Sequence name, svs_slaser
description, Str, Yes, User description, 3T slaser 28 ms
B0, float, Yes, Static field strength, 6.98
centralShift, float, No, Receiver offset from ppm reference. For most 1H MRS sequences this will be 4.65 ppm (the shift of water at 37 °C from TMS/DSS). Default = 0.0, 4.65
RX_Points, int, Yes, Number of points in the final spectrum, 4096
RX_SW, float, Yes, Receiver sweep-width (bandwidth) in Hz, 6000
RX_LW, float, Yes, FWHM of peaks in the output spectra. In Hz.,2.0
RX_Phase, float, Yes, Zero-order phase applied to final spectra. In radians., 0.0
x, float (1x2), Yes, Spatial range simulated in x direction. In units specified by spaceUnits.,[-25 25]
y, float (1x2), Yes, As above for y, [-25 25]
z, float (1x2), Yes, As above for z, [-25 25]
resolution, Int (1x3), Yes, Number of spatial points to simulate in each dimension., [25 25 1]
CoherenceFilter,Int (1x Nblocks),Yes, Coherence order NOT zeroed at end of block. Value of element can be ‘None’ for no coherence selection. See below for more information., [1 0 -1]
RFUnits, Str, No, Units of RF amplitude (options: ’Hz’,’T’,’mT’,’uT’; default=’Hz’) ,‘Hz’
GradUnits, Str, No, Units of gradient amplitude per meter (options: ’Hz’,’T’,’mT’; default=’T’), ‘mT’
spaceUnits, Str, No, Units of spatial position (options: ’mm’,’cm’,’m’; default=’m’), ‘mm’
RF, List of NBlocks,Yes, Sequence block description. Contains the fields listed below in italics., [block1,…,blockN]
time, float, Yes, Total pulse time. In seconds., 0.003
frequencyOffset,float, No, Offset of pulse central frequency from receiver centre. In Hz., -246
phaseOffset, float, No, Phase offset applied to whole pulse. In radians, default = 0., 0.0
amp, List of floats, Yes, List of amplitudes in units specified by RFUnits. Must contain >=1 points., [0,1.0,…,1.0,0.0]
phase, List of floats, Yes, List of pulse phase points. Must match the size of amp. In radians., [0,0.0,…,0.0,0.0]
grad, Float (1x3), Yes, Slice selection gradient amplitude (in GradUnits/m) for each of the three spatial axes., [3.5,0,0]
ampScale, Float, No, Optional scaling of the pulse amplitude. Default = 1.0., 2.0
delays, Float (1x Nblocks),Yes, Free evolution time after RF in each RF block. In seconds. Measured from end of RF to start of next RF., [0.005,0.001,0.005]
rephaseAreas, Float (Nblocksx3),Yes Area of gradients (in seconds.GradUnits/m) on each spatial axis during the delay time. Can be applied on more than one axis per block., [[-5.1e-3, 0, 0] [ 0, -5.1e-3, 0] [ 0, 0, -5.1e-3]]
:header: "Field", "Value type","Req?", "Description" , "Example value"
:widths: 15, 10, 5, 100, 30
sequenceName, Str, Y, Sequence name, svs_slaser
description, Str, Y, User description, 3T slaser 28 ms
B0, float, Y, Static field strength, 6.98
centralShift, float, N, Receiver offset from ppm reference. For most 1H MRS sequences this will be 4.65 ppm (the shift of water at 37 °C from TMS/DSS). Default = 0.0, 4.65
RX_Points, int, Y, Number of points in the final spectrum, 4096
RX_SW, float, Y, Receiver sweep-width (bandwidth) in Hz, 6000
RX_LW, float, Y, FWHM of peaks in the output spectra. In Hz., 2.0
RX_Phase, float, Y, Zero-order phase applied to final spectra. In radians., 0.0
x, float (1x2), Y, Spatial range simulated in x direction. In units specified by spaceUnits., [-25 25]
y, float (1x2), Y, As above for y, [-25 25]
z, float (1x2), Y, As above for z, [-25 25]
resolution, Int (1x3), Y, Number of spatial points to simulate in each dimension., [25 25 1]
CoherenceFilter,Int (1x Nblocks),Y, Coherence order NOT zeroed at end of block. Value of element can be ‘None’ for no coherence selection. See below for more information., [1 0 -1]
RFUnits, Str, N, Units of RF amplitude (options: ’Hz’ ’T’ ’mT’ ’uT’; default=’Hz’) ,‘Hz’
GradUnits, Str, N, Units of gradient amplitude per meter (options: ’Hz’ ’T’ ’mT’; default=’T’), ‘mT’
spaceUnits, Str, N, Units of spatial position (options: ’mm’ ’cm’ ’m’; default=’m’), ‘mm’
RF, List of NBlocks,Y, Sequence block description. Contains the fields listed below., [block1 … blockN]
Sequence block parameters
~~~~~~~~~~~~~~~~~~~~~~~~~
Parameters required for the nested sequence blocks of the RF array in the above table.
These parameters describe one block of the sequence RF (with or without gradient), rephasing, delay.
.. csv-table::
:header: "Field", "Value type","Req?", "Description" , "Example value"
:widths: 15, 10, 5, 30, 30
time, float, Y, Total pulse time. In seconds., 0.003
frequencyOffset,float, N, Offset of pulse central frequency from receiver centre. In Hz., -246
phaseOffset, float, N, Phase offset applied to whole pulse. In radians. Default = 0., 0.0
amp, List of floats, Y, List of amplitudes in units specified by RFUnits. Must contain >=1 points., [0 1.0 … 1.0 0.0]
phase, List of floats, Y, List of pulse phase points. Must match the size of amp. In radians., [0 0.0 … 0.0 0.0]
grad, Float (1x3), Y, Slice selection gradient amplitude (in GradUnits/m) for each of the three spatial axes., [3.5 0 0]
ampScale, Float, N, Optional scaling of the pulse amplitude. Default = 1.0., 2.0
delays, Float (1x Nblocks),Y, Free evolution time after RF in each RF block. In seconds. Measured from end of RF to start of next RF., [0.005 0.001 0.005]
rephaseAreas, Float (Nblocksx3),Y, Area of gradients (in seconds.GradUnits/m) on each spatial axis during the delay time. Can be applied on more than one axis per block., [[-5.1e-3 0 0] [ 0 -5.1e-3 0] [ 0 0 -5.1e-3]]
......
......@@ -4,6 +4,8 @@ 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.
Describing a sequence – the sequence file format
......@@ -70,7 +72,12 @@ glycine Gly
- :sup:`3` Tkac et al. proc intl soc magn reson med 2008: p1624
- :sup:`4` Bal et al. Magnetic Resonance in Chemistry. 2002;40:533–36
Metabolites to simulate can be specified on the command line using the :code:`–m` option with a list typed on the command line, with the :code:`–b` option specifying a text file with one metabolite listed per line, or the :code:`–s` option pointing to a spin system json file for custom spin systems.
Metabolites to simulate can be specified on the command line using the :code:`–m` option with a list typed on the command line, with the :code:`–b` option specifying a text file with one metabolite listed per line, or the :code:`–s` option pointing to a spin system json file for custom spin systems.
It is **not recommended** to simulate and use all of the metabolites. A typical list to start with for short echo time spectroscopy might be
:
Ala, Asp, GPC, PCh, Cr, PCr, GABA, Glc, Gln, Glu, GSH, Ins, Lac, NAA, NAAG, PE, Tau
Including macromolecules in your basis set
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
......
......@@ -19,8 +19,18 @@ Troubleshooting hints
If you installed FSL-MRS through conda the example data can be downloaded directly from the GitLab repository `folder <https://git.fmrib.ox.ac.uk/fsl/fsl_mrs/-/tree/master/example_usage>`_.
2. Poor fits
Two problems are commonley diagnosed when poor fits are seen:
Two problems are commonly diagnosed when poor fits are seen:
1) Basis spectra are inconsistently scaled. For example empirically derived macromolecular basis spectra can be orders of magnitude larger than the other basis spectra. Before fitting, fsl_mrs(i) scales the magnitude of the data and basis spectra to a known range. Relative scales are preserved within the basis spectra. To permit fsl_mrs(i) to apply different scales to individual basis spectra use the :code:`--ind_scale` option with a list of basis names.
2) The data might have parameters unlike a 7T or 3T human *in vivo* brain spectrum. I.e. the spectrum originates from a pre-clinical system or from phantom. In this case the MCMC priors which are suitable for *in vivo* human case can be disabled using the :code:`--disable_MH_priors` option.
\ No newline at end of file
2) The data might have parameters unlike a 7T or 3T human *in vivo* brain spectrum. I.e. the spectrum originates from a pre-clinical system or from phantom. In this case the MCMC priors which are suitable for *in vivo* human case can be disabled using the :code:`--disable_MH_priors` option.
3. Identifying the correct files for conversion
Raw data files, especially DICOM files can have obscure naming conventions. It can be difficult to determine which files should be converted for use in FSL-MRS. Tools such as gdcmdump from `GDCM <http://gdcm.sourceforge.net/>`_ can help in identifying the scans by giving you access to the DICOM headers.
.. _TS_4:
4. Data looks 'wrong' after conversion
If when using :code:`mrs_vis` you see no signal and just noise try conjugating the data using :code:`fsl_mrs_proc conj` or try expanding the ppm range plotted :code:`--ppmlim -10 10`. If you see a flat line, then conversion failed. The data might be corrupted - did the acquisition complete successfully?
.. image:: data/bad_data.png
:width: 600
\ No newline at end of file
.. _visualisation:
Reports and Visualisation
=========================
......@@ -26,6 +28,13 @@ gives the following basic plot:
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*).
:code:`mrs_vis` can also visualise a folder of mrs data::
mrs_vis ./converted_data_dir/
.. image:: data/mrs_vis_dir.png
:width: 600
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:
......@@ -74,7 +83,7 @@ Below are instructions for loading and configuring FSLeyes to work with MRSI dat
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:
Now to make the power-spectrum 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}
......
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