Commit 9c4434fc authored by William Clarke's avatar William Clarke
Browse files

Add user docs.

parent ac601540
......@@ -8,3 +8,13 @@ __pycache__
/dist
test
TODO
/docs/**/_build
.vscode
.coverage
*.code-workspace
fsl_mrs/pkg_data/mrs_fitting_challenge/datasets1_21.mat
example_usage/data/
example_usage/fsl_mrs_preproc/
example_usage/fsl_mrs_preproc_simple/
example_usage/fsl_mrs_proc/
example_usage/report.html
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS ?=
SPHINXBUILD ?= sphinx-build
SOURCEDIR = .
BUILDDIR = _build
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
import datetime
date = datetime.date.today()
# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
# -- Path setup --------------------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
# -- Project information -----------------------------------------------------
project = 'FSL-MRS'
copyright = f'{date.year}, Will Clarke & Saad Jbabdi, University of Oxford, Oxford, UK'
author = 'William Clarke'
# The full version, including alpha/beta/rc tags
version = '0.1'
release = version
# From PM's fsleyes doc
# Things which I want to be able to
# quote in the documentation go here.
rst_epilog = """
.. |fsl_version| replace:: 6.0.2
.. |fsleyes_gitlab| replace:: FSL-MRS GitLab
.. _fsleyes_gitlab: https://git.fmrib.ox.ac.uk/saad/fsl_mrs
"""
# -- General configuration ---------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
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 = ['_static']
\ No newline at end of file
.. _data_conversion:
Data Conversion
===============
There is a plethora of spectroscopy data formats in existence. Many are vendor specific and proprietary. The fitting capabilities of FSL-MRS can be used with either NIfTI or an ASCII file format, but to access the full features of the post-processing tools data must be in the NIfTI + JSON format. To facilitate the conversion of data to this format FSL-MRS is distributed with an additional conversion tool spec2nii. Spec2nii currently converts SVS and MRSI data to NIfTI from the following formats.
=============== ================ ===== ===== =======================
Format File extension SVS CSI Automatic orientation
=============== ================ ===== ===== =======================
Siemens Twix .dat Yes No Yes
Siemens DICOM .ima / .dcm Yes Yes Yes
Philips .SPAR/.SDAT Yes No No
GE .7 (pfile) Yes No No
LCModel .RAW Yes No No
jMRUI .txt Yes No No
ASCII .txt Yes No No
=============== ================ ===== ===== =======================
The authors of the tool are happy to provide additional conversion routines if sample data and a thorough description of the format is provided. Please see the spec2nii `project page on Github <https://github.com/wexeee/spec2nii>`_.
Use of spec2nii
---------------
To specify the creation of a json metadata file alongside a NIfTI file (recommended) use the ‘-j’ option with any other inputs.
File names can be specified with the -f option and output directories with the -o option.
Twix
~~~~
Spec2ni can be used to inspect the contents of a twix file before conversion.
::
spec2nii twix -v [file]
This will produce a list of the data with associated ‘evalinfo’ flags and data dimensions.
Spec2nii can then be run to convert all data from a single ‘evalinfo’ flag.
::
spec2nii twix -e [flag] [file]
‘Image’ is the most typically used for the main dataset. Other flags might be used for noise data, water reference data or any other use specified by the sequence programmer.
DICOM
~~~~~
Spec2nii can be passed a single file or directory of DICOM files for conversion.
::
spec2nii dicom [file or dir]
Philips
~~~~~~~
Conversion for Philips SDAT/SPAR files. Orientation information not validated.
::
spec2nii philips [SDAT] [SPAR]
GE
~~
Conversion for GE pfiles (.7). Orientation information not validated.
::
spec2nii GE [file]
Plain text format
~~~~~~~~~~~~~~~~~
Conversion for text files containing one FID specified as two columns of data (real and imaginary). Required inputs are central frequency (-i, --imagingfreq; MHz), bandwidth (-b, --bandwidth; Hz). Optionally specify location with a 4x4 affine matrix passed as a plain text file (-a, --affine)
::
spec2nii text -a [affine] -i [imaging_freq] -b [bandwidth] [file]
LCModel RAW format
~~~~~~~~~~~~~~~~~~
Conversion for .RAW text files containing one FID specified as two columns of data (real and imaginary). Optionally specify location with a 4x4 affine matrix passed as a plain text file (-a, --affine)
::
spec2nii raw -a [affine] [file]
jMRUI text format
~~~~~~~~~~~~~~~~~
Conversion for text files in the jMRUI format containing one FID specified as two columns of data (real and imaginary). Optionally specify location with a 4x4 affine matrix passed as a plain text file (-a, --affine)
::
spec2nii jmrui -a [affine] [file]
\ No newline at end of file
Fitting
=======
SVS
---
::
fsl_mrs --data metab.nii.gz --basis my_basis_spectra --output example_fit --algo MH --overwrite --report --h2o wref.nii.gz --TE 11 --tissue_frac tissue_frac.json
Output
~~~~~~
CSV files.
MRSI
----
::
fsl_mrsi --data mrsi.nii.gz --basis my_basis_spectra --output example_fit --overwrite --mask mask.nii.gz --h2o wref.nii.gz --TE 32 --tissue_frac WM.nii.gz GM.nii.gz CSF.nii.gz
Output
~~~~~~
Results from *fsl_mrsi* are output as directories containing NIfTI files with the same spatial size as the original data.
Python & Interactive Interface
------------------------------
fit_FSLModel in the fsl_mrs.utils.fitting module
\ No newline at end of file
FSL-MRS
=======
This is the user documentation for *FSL-MRS*, the `FSL
<http://fsl.fmrib.ox.ac.uk/fsl/fslwiki/>`_ spectroscopy package. This documentation
pertains to FSL-MRS |version|.
You can download the latest version of FSLeyes from the |fsleyes_gitlab|_ page.
If this is your first experience with FSL-MRS, get started with the :ref:`Quick start
<quick_start>` page. Otherwise, choose a topic from the list below.
.. toctree::
:name: mastertoc
:caption: Table of contents
:maxdepth: 1
introduction
install
quick_start
data_conversion
processing
fitting
quantitation
simulation
visualisation
troubleshooting
changelog
Installation Instructions
=========================
FSL-MRS can currently be installed using two methods
1. From GitLab
~~~~~~~~~~~~~~
Download or clone from |fsleyes_gitlab|_.
Run `pip install .` in the top level directory once downloaded.
2. From Conda
~~~~~~~~~~~~~
TBC
Introduction
============
FSL-MRS is a python-based command-line software tool for the fitting and quantification of proton magnetic resonance spectroscopy data. FSL-MRS handles both single voxel and multi-voxel (MRSI) datasets. FSL-MRS is part of FSL (FMRIB Software Library).
Alongside the core fitting features FSL-MRS contains tools for pre-processing, basis spectra simulation and data handling and conversion. FSL-MRS is designed to interface with existing FSL tools for data manipulation, quantification (FSL FAST) and display (Fsleyes).
FSL-MRS can be used purely from the command line for bulk scripting of MRS analysis of large datasets, interactively in IPython style notebooks, or in a customisable way by modifying the open-source python libraries.
At the core of FSL-MRS is a fitting tool that uses the linear combination of simulated basis spectra to estimate the relative or absolute concentrations of metabolites measured by the MRS sequence. The tool has been developed for 3T and 7T MRS and MRSI of teh human brain, but a number of advanced options are available providing increased flexibility for varied uses.
In keeping with FSL’s tradition of favouring Bayesian inference approaches, the tool calculates full posterior distributions of the fitted metabolite concentrations to estimate concentration covariances and uncertainties using the Metropolis-Hastings algorithm.
FSL-MRS typically takes a few seconds to analyse a single spectrum, producing an interactive HTML analysis report. In addition, we provide example post processing pipelines for an end-to-end solution for MRS processing.
Citing FSL-MRS
--------------
If you use FSL-MRS please cite:
Clarke, Near, Emir, Jbabdi - ISMRM 2020
\ No newline at end of file
@ECHO OFF
pushd %~dp0
REM Command file for Sphinx documentation
if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
)
set SOURCEDIR=.
set BUILDDIR=_build
if "%1" == "" goto help
%SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 (
echo.
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
echo.installed, then set the SPHINXBUILD environment variable to point
echo.to the full path of the 'sphinx-build' executable. Alternatively you
echo.may add the Sphinx directory to PATH.
echo.
echo.If you don't have Sphinx installed, grab it from
echo.http://sphinx-doc.org/
exit /b 1
)
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
goto end
:help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
:end
popd
Processing
==========
**For SVS**
Processed SVS data comprises a time domain signal localised to a single spatial volume. This is Fourier transformed to give a frequency domain spectrum. In an un-processed state, the data might not be coil-combined, might have multiple transients needing averaging and might have other acquisition loops requiring specific processing. Typically, SVS data requires no “reconstruction” per-se, but several steps must be followed to achieve the highest quality data possible from an acquisition.
For a complete overview of pre-processing we recommend this `reference <https://onlinelibrary.wiley.com/doi/full/10.1002/nbm.4257>`_. In short, the data must be coil combined, processed to remove small frequency drifts and corrupted transients, averaged, corrected for eddy currents and phased. Optionally large residual water signals can be removed. This is summarised in the table below:
**For MRSI**
MRSI comprises an “image” of spectroscopy data, each voxel contains time or frequency domain data. MRSI data will require reconstruction from the raw (k-space) data collected by the scanner. This may be carried out either online (on the scanner) or offline. Typically, this reconstruction incorporates some of the steps described above for SVS data (e.g. coil combination or averaging). Other steps used for SVS processing would not be commonly used for MRSI data (e.g. Bad average removal). However, the majority of the fsl_mrs_proc commands can be run on MRSI data stored in NIfTI format where the processing will be applied independently per-voxel.
Due to the complexity and specialism of MRSI reconstruction FSL-MRS does not provide MRSI reconstruction. Nor do we advise application of pre-processing beyond that the data should be coil-combined and repetitions averaged before fitting.
fsl_mrs_proc
------------
Processing in FSL-MRS is primarily accessed through the commandline program *fsl_mrs_proc*.
*fsl_mrs_proc* has a series of
Subcommands
~~~~~~~~~~~
======================= ==============================================================
fsl_mrs_proc operation Description
======================= ==============================================================
coilcombine Combine individual coils of receiver phased array.
average Average FIDs, with optional complex weighting.
align Phase and frequency align FIDs using spectral registration.
align-diff Phase and frequency align sub-spectra for differencing.
ecc Eddy current correction using a water phase reference scan.
remove Remove peak (typically residual water) using HLSVD.
tshift shift/re-sample in time domain.
truncate Truncate/pad time-domain data by an integer number of points.
apodize Apply choice of apodization function to the data.
fshift Frequency domain shift.
unlike Identify outlier FIDs and remove.
phase Zero-order phase spectrum by phase of maximum point in range
subtract Subtract two FIDs
add Add two FIDs
======================= ==============================================================
Specific help for each subcommand can be accessed using `fsl_mrs_proc [subcmd] --help`
Generic commands
~~~~~~~~~~~~~~~~
*fsl_mrs_proc* has a few arguments that are generic to each subcommand. These should be specified before the subcommand argument.
::
fsl_mrs_proc [generic commands] [subcmd] --help
Some common commands are:
- `-output` (required) : Output directory
- `-r, --generateReports` : Generate HTML report for this step
- `-filename` : Output file name.
Merging processing HTML reports
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
merge_mrs_reports -d [description] -o [output folder] -f [report name] *.html
fsl_mrs_preproc
---------------
*fsl_mrs_preproc* combines a number of processing steps to provide a one step processing of non-edited SVS data.
The script requires a list of transients to be averaged (--data), water reference data (--reference) and an output location (--output). The data can be coil combined or un-combined but must be consistent.
::
fsl_mrs_preproc --output my_subj --data metab*.nii.gz --reference wref*.nii.gz --report
Optionally the user may specify any of the following:
- `--quant`: Data to be used for quantitation
- `--ecc`: Data to be used for eddy current correction
- `--hlsvd`: Apply HLSVD to remove residual water
- `--leftshift POINTS`: Truncate FID at start by POINTS.
Python & Interactive Interface
------------------------------
To access the processing methods in either a python or interactive python enviroment load the `preproc` module
::
import fsl_mrs.utils.preproc
Reports can be generated using the associated [subcmd]_report functions in the preproc submodules.
fsl_mrs_proc subcommand specifics
---------------------------------
1. coilcombine (Coil combination)
Takes a list of files (--file) and runs wSVD coil combination on them optionally using a single water reference dataset (-r/--reference) to calculate the complex weightings of each coil. The function expects data to be stored as 5D data, with the last dimension storing individual coil data. Each file is treated separately. Pre-whitening can be disabled (--noprewhiten).
2. average (averaging)
Takes either a single file or list of files (--file) and takes the mean across the list of files (--avgfiles) or across a certain dimension (--dim, indexes from 0).
3. align (phase-frequency alignment)
Takes a list of files (--file) and aligns each FID to the FID nearest to the mean, or to a single passed reference FID (--reference). The ppm range can be defined (--ppm, default = 0.2->4.2 ppm).
4. ecc (eddy current correction)
Takes either a single file or list of files (--file) and applies eddy current correction based on the phase of a water reference scan (--reference, supplied either as a single reference or list of same length as --files). The reference must have experienced the same eddy current effects (i.e. same gradients).
5. remove (residual water removal - HLSVD)
Takes either a single file or list of files (--file) and applies HLSVD peak removal over the specified ppm limits (--ppm, default = 4.5->4.8 ppm)
6. tshift (time domain resampling)
Takes either a single file or list of files (--file) and resamples in the time domain to achieve a different number of points (--samples), and/or a different start time (--tshiftStart, in ms), and/or a different end time (--tshiftEnd, in ms).
7. truncate (truncation or zero padding)
Takes either a single file or list of files (--file) and adds or removes points (--points, positive to add, negative to remove) from the start or end (--pos, default end) of the FID. Points added are zeros.
8. apodize (filtering of data)
Takes either a single file or list of files (--file) and applies either an exponential or Lorentzian to Gaussian window (--filter) to the time domain data. The window parameters may be specified (--amount).
9. fshift (frequency shift)
Takes either a single file or list of files (--file) and shifts the data in the frequency domain by an amount specified in hertz (--shifthz) or in ppm (--shiftppm).
10. unlike (bad average removal)
Takes a list of files (--file) and returns files containing FIDS that are within N standard deviations (--sd) from the median. The ppm range over which the spectra are compared can be set (--ppm, default = 0.2->4.2 ppm) and the number of iterations of the algorithm can be controlled (--iter). Optionally the FIDs which are identified as failing the criterion can be output (--outputbad)
11. phase (zero order phasing)
Takes either a single file or list of files (--file) and applies zero-order phase to the FID/spectrum based on the phase at the maximum in a specified chemical shift range (--ppm)
\ No newline at end of file
Quantitation
============
Tissue Segmentation
-------------------
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 *svs_segment* and *mrsi_segment* commands.::
svs_segment -t T1.nii.gz -f tissue_frac svs_data.nii.gz
mrsi_segment -t T1.nii.gz -f tissue_frac mrsi_data.nii.gz
*svs_segment* creates a small JSON file which can be passed to the fitting routines. *mrsi_segment* creates NIfTI files of the fractional tissue volumes registered to the MRSI volume.
*svs_segment* and *mrsi_segment* both rely on fsl_anat to run FSL FAST tissue segmentation. If fsl_anat has already been run -t T1.nii.gz can be substituted with -a T1.anat.
\ No newline at end of file
.. _quick_start:
Quick Start Guide
=================
Summary
-------
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>`).
Example conversion::
spec2nii -f my_metab_file dicom -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.
For a list of supported formats see :ref:`Data Conversion <data_conversion>`.
2. Process your raw data
~~~~~~~~~~~~~~~~~~~~~~~~
Some data requires pre-processing. Often MRSI data will have gone through appropriate pre-processing during reconstruction, if so skip to step 3. For unprocessed single voxel (SVS) data, read on.
Use the *fsl_mrs_proc* commands to pre-process your raw data. *fsl_mrs_proc* contains routines for many common steps (e.g. coil combination, phase-frequency alignment, residual water removal). E.g.::
fsl_mrs_proc -r --filename combined coilcombine --file my_metab_file*.nii.gz --reference my_wref_file.nii.gz
fsl_mrs_proc -r --filename aligned align --file combined*.nii.gz --ppm 1.8 3.5
fsl_mrs_proc -r --filename avg average --file aligned*.nii.gz --avgfiles
fsl_mrs_proc -r --filename water_removed remove --file avg.nii.gz
fsl_mrs_proc -r --filename metab phase --file water_removed.nii.gz
The -r requests a HTML report to be generated, which can be merged using::
merge_mrs_reports -d example_processing -o . *.html
If your data is unedited single voxel (SVS) try out the prepackaged processing pipeline *fsl_mrs_preproc*. You will need to identify the water suppressed and water unsuppressed files to pass to the script.
::
fsl_mrs_preproc --output my_subj --data metab*.nii.gz --reference wref*.nii.gz --report
Have a look at the source code for 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
~~~~~~~~~~~~~~~~~~~~~~~
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 *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.
Have a quick check of your basis set using mrs_vis::
mrs_vis my_basis_spectra/
4. Tissue Segmentation
~~~~~~~~~~~~~~~~~~~~~~
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 *svs_segment* and *mrsi_segment* commands.::
svs_segment -t T1.nii.gz -f tissue_frac svs_data.nii.gz
mrsi_segment -t T1.nii.gz -f tissue_frac mrsi_data.nii.gz
*svs_segment* creates a small JSON file which can be passed to the fitting routines. *mrsi_segment* creates NIfTI files of the fractional tissue volumes registered to the MRSI volume.
*svs_segment* and *mrsi_segment* both rely on fsl_anat to run FSL FAST tissue segmentation. If fsl_anat has already been run -t T1.nii.gz can be substituted with -a T1.anat.
5. Fitting
~~~~~~~~~~
FSL-MRS provides two scripts for fitting: fsl_mrs (for SVS data) and fsl_mrsi (for MRSI data).
::
fsl_mrs --data metab.nii.gz --basis my_basis_spectra --output example_fit --algo MH --overwrite --report --h2o wref.nii.gz --TE 11 --tissue_frac tissue_frac.json
fsl_mrsi --data mrsi.nii.gz --basis my_basis_spectra --output example_fit --overwrite --mask mask.nii.gz --h2o wref.nii.gz --TE 32 --tissue_frac WM.nii.gz GM.nii.gz CSF.nii.gz
6. Visualise
~~~~~~~~~~~~
HTML processing reports merged using *merge_mrs_reports* and fitting reports made using *fsl_mrs* can be viewed in your browser.
For visualising MRSI data, fits and fitting results `FSLeyes
<https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FSLeyes>`_ is recommended.
.. _demos:
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.
.. _seq_file_params:
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]]
.. _simulation:
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.
FSL-MRS's simulation software may be accessed through the 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
------------------------------------------------
In FSL-MRS a sequence to be simulated is described in a json format file. The sequence description should comprise one transient (repetition time) of the sequence. The file breaks the sequence into a series of blocks that describe the preparation of the magnetization. Each block comprises an RF pulse, slice selection gradient, a delay with optional gradient rephasing/crushing and an optional coherence filter. The simulation does not simulate the read-out module of a sequence.