Commit d4ee2e20 authored by William Clarke's avatar William Clarke
Browse files

Merge branch 'enh/v2_dynamic_update' into 'master'

FSL-MRS V2: Basis rework and dynamic fitting release

See merge request fsl/fsl_mrs!56
parents 39289655 32dc615d
Pipeline #14988 canceled with stage
......@@ -19,3 +19,4 @@ example_usage/fsl_mrs_preproc_simple/
example_usage/fsl_mrs_proc/
example_usage/report.html
*.egg-info
.idea
......@@ -74,7 +74,7 @@ flake8:
pytest:
<<: *except_releases
image: wtclarke/fsl_mrs_tests:1.0
image: wtclarke/fsl_mrs_tests:2.0
stage: test
variables:
GIT_SUBMODULE_STRATEGY: normal
......@@ -105,7 +105,7 @@ pages:
stage: doc
script:
- git describe --tag --dirty
- pip install -U sphinx sphinx_rtd_theme==0.5.2
- pip install -U sphinx sphinx_rtd_theme
- pip install .
- sphinx-build -b html ./docs/user_docs public
artifacts:
......
This document contains the FSL-MRS release history in reverse chronological order.
1.1.14 (Wednesday 29th June)
----------------------------
2.0.0 (Wednesday 6th July 2022)
-------------------------------
**Major rework of basis and fitting script interaction. First release of dynamic MRS fitting.**
*Static fitting*
- Default macromolecules are now added through basis_tools script rather than fitting. Fitting does not alter basis at run time now.
- Fixed bug in calculation of concentration covariances. New MC tests included.
- Better and faster covariance estimation via analytical jacobian.
- Update to QC SNR calculation to improve stability.
*Dynamic fitting*
- Saved dynamic results now contain free parameter covariances.
- New documentation for dynamic fitting
- New fmrs_stats module and script for higher-level GLM analysis.
*Other new features*
- Experimental SVS results dashboard - view the results of multiple SVS fits together in a single summary.
- New documentation for dynamic fitting and all new features.
- Refactored imports to improve CLI startup times
- Conversion of LCModel raw formatted basis sets using basis_tools convert.
1.1.14 (Wednesday 29th June 2022)
---------------------------------
- Fixed variability in HLSVD by moving to Scipy dense svd.
- Fix for -ve ISHIFT in LCModel basis read. Also throws helpful error for encrypted basis.
- Fixed incorrect plotting of svs voxel orientation in fitting report.
- Fix issue in results_to_spectrum for disabled baseline.
1.1.13 (Wednesday 1st June)
---------------------------
1.1.13 (Wednesday 1st June 2022)
--------------------------------
- Updated setup script to allow command line scripts to run on MS Windows.
- Any FSL cmd-line scripts used operate through fslpy wrappers (including WSL interface).
- Updated install instructions for Windows.
- Added the fsl_mrs_verify script which can be run to verify correct function of FSL-MRS.
1.1.12 (Wednesday 20th April)
-----------------------------
1.1.12 (Wednesday 20th April 2022)
----------------------------------
- Update to fslpy version (to 3.9.0) to substantially speed up MRSI preprocessing.
- Fixes to NIFTI_MRS class for compatibility with new fslpy version.
- Previous versions of FSL-MRS will not be compatible with fslpy >= 3.9.0
......
......@@ -22,7 +22,8 @@ vis
convert
*******
| *Example* :code:`basis_tools convert path/to/my/lcmbasis.BASIS path/to/my/fslbasis`
| Convert LCModel (.Basis) or JMRUI format basis sets to FSL-MRS (.json) format.
| Convert LCModel (.Basis), LCModel (directory of .raw) or JMRUI format basis sets to FSL-MRS (.json) format.
| Note that the bandwidth and fieldstrength must be supplied manually to the CLI for the .raw format.
add
***
......@@ -42,4 +43,13 @@ scale
diff
****
| *Example* :code:`basis_tools diff --add_or_sub sub mega_on mega_off mega_diff`
| Form a basis set for a difference method using two other basis set. Add or subtract using :code:`--add_or_sub {'add'|'sub}`.
\ No newline at end of file
| Form a basis set for a difference method using two other basis set. Add or subtract using :code:`--add_or_sub {'add'|'sub}`.
add_set
*******
| *Example* :code:`basis_tools add_set --add_MM basis_without_mm/ basis_with_default_mm/`
| Add a (predefined) set of Gaussian peaks to a basis set. Three defualt sets are defined:
| 1) The FSL 'default' with peaks at 0.9, 1.2, 1.4, 1.7 ppm and a linked set at 2.08 & 3.0 ppm
| 2) The (experimental) MEGA edited MM peaks at 0.915 & 3.0 ppm (ratio of 3.75:2.0).
| 3) A water peak at 4.65 ppm
| The other options (:code:`--gamma --sigma`) allow a custom set of peaks to be specified.
......@@ -83,8 +83,9 @@ html_theme = 'sphinx_rtd_theme'
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
html_context = {
'css_files': [
'_static/theme_overrides.css', # override wide tables in RTD theme
],
}
# html_context = {
# 'css_files': [
# '_static/theme_overrides.css', # override wide tables in RTD theme
# ],
# }
html_css_files = ["_static/theme_overrides.css"] # override wide tables in RTD theme
Dynamic Fitting
===============
The dynamic fitting module :code:`fsl_mrs.dynamic` and command-line tool :code:`fsl_dynmrs` can simultaneously fit multiple spectra which are linked by an arbitrary model.
"Dynamic" MRS is defined as spectra acquired under changing experimental and/or acquisition conditions. For example functional (fMRS), diffusion weighted MRS (dwMRS), or edited MRS. The FSL-MRS dynamic fitting tools are suitable for fitting all of these types of data.
Requirements
~~~~~~~~~~~~
Three things are needed to use the dynamic fitting tools:
1. A 2D (or higher) dataset - This contains a spectral dimension and at least one other dimension across which spectra change.
2. A model configuration file - This specifies how each spectrum is related to the others by describing a dynamic model.
3. A description of the modulating input variables - For example, a file or files with time values or b-values / gradient directions.
4. One or more sets of basis spectra - Used to perform the linear combination fitting. Different spectra can be fitted using different basis sets.
To run the fitting use the :code:`fsl_dynmrs` interface. An example using the packaged dwMRS data (found in example_usage/example_data/example_dwmrs) is::
fsl_dynmrs\
--data metab.nii.gz\
--basis basis\
--dyn_config config.py\
--time_variables bvals\
--output dyn_results
The same fit, but run using the interactive python interface is demonstrated in the packaged :file:`Example Dynamic Fitting.ipynb`
Dataset
-------
The dynamic data should be formatted as `NIfTI-MRS <https://wtclarke.github.io/mrs_nifti_standard/>`_ with a single 'higher dimension' in use. I.e. the fifth dimension should contain the dynamically varying spectra (with the first three dimensions encoding spatial extent and the fourth, the spectral time domain.)
Requisite pre-processing (e.g. coil combination, phase & frequency alignment, etc.) should already have been carried out.
Shaping of the NIfTI-MRS file can be carried out using the :code:`mrs_tools` command-line tool.
Configuration file
------------------
Purpose
*******
The configuration file is a python-formatted (*.py*) file that describes how the parameters of the dynamic model, known here as *free parameters*, correspond to the parameters of spectral fitting (e.g., concentrations, lineshapes, phases etc.), known as *mapped parameters*.
The file contains the explicit mappings, any bounds on the free parameters, and finally a functional description of the dynamic model.
Sections
********
The file come in three parts:
:code:`Parameters` variable - :code:`dict`:
For each spectral fitting parameter type (e.g. concentration, or line-shift `eps`) this dict parameter defines whether that parameter:
- Takes a different (unconstrained) value for each b value - **variable**
- Has a fixed value across all b values - **fixed**
- Or is described by a function of the varying acquisition (time, b-value, etc.) - **dynamic**
:code:`Bounds` variable - :code:`dict`:
This dictionary provides lower and upper bounds for free parameters.
Dynamic models and gradients variable - function definitions:
If a mapped parameter has been identified as `dynamic` then a functional relationship between the mapped parameter and the time variable and free parameters must be given.
These relationships are described using python functions. Each function listed in the `Parameters` dict must be defined. In addition a function providing the gradient of that function must be defined.
Example Syntax
**************
.. code-block::
:caption: Example Parameters dict
Parameters = {
'conc' : {'dynamic': 'model_exp', 'params':['c_amp','c_adc']},
'gamma' : 'fixed',
'eps' : 'fixed',
'Phi_0' : 'variable',
'Phi_1' : 'fixed'
}
Here we see a simple example of a :code:`Parameters` dict. It defines a (exponentially decaying) dynamic model for metabolite concentration mapped parameters. In doing so it requires a function :code:`model_exp`, and defines two free parameters :code:`c_amp, c_adc`. Zero-order phase :code:`Phi_0` is free to vary across all spectra, whilst all other parameters are fixed (including the not listed :code:`baseline`, which defaults to *fixed*.)
The above listing of :code:`model_exp` requires a definition and a definition of the gradient function.
.. code-block::
:caption: Example function definitions
from numpy import exp, asarray
def model_exp(p, t):
# p = [amp,adc]
return p[0] * exp(-p[1] * t)
def model_exp_grad(p, t):
e1 = exp(-p[1] * t)
g0 = e1
g1 = -t * p[0] * e1
return asarray([g0, g1], dtype=object)
We may also wish to place bounds on the new free parameters. Below we limit the metabolite amplitudes, decay time constants and the line broadening to positive (but otherwise unbounded) values.
.. code-block::
:caption: Example free parameter bounds
Bounds = {
'c_amp' : (0, None),
'c_adc' : (0, None),
'gamma' : (0,None)
}
More complex models can be defined, with different dynamic models defined per-metabolite (for concentrations) or per-metabolite-group for line widths (:code:`sigma, gamma`) and shifts (:code:`eps`).
.. code-block::
:caption: Example multi-model Parameters dict
Parameters = {
'conc' : {'other': {'dynamic': 'model_exp', 'params': ['c_amp', 'c_adc']},
'Mac': {'dynamic': 'model_lin', 'params': ['c_amp', 'c_slope']}
'H2O': 'variable'}}
In the above we provide a nested dict entry for the metabolite concentrations :code:`conc` entry. This defines that all metabolites except water (H2O) and the macromolecules (Mac) should follow the above exponential decay model. Macromolecules follow a linear decay, and water is free to vary unconstrained by a particular model. Note the names of water and macromolecules would be linked to the specific basis spectra set. Additional function definitions for :code:`model_lin` and :code:`model_lin_grad` would be needed. All other parameters would take the default *fixed* profile.
Other requirements
------------------
Two further items are needed:
A set of basis spectra:
In the standard FSL-MRS format (directory of :code:`.json` files). A different set of basis spectra can be used for each dynamically linked spectra, though all metabolites must appear in each set.
A file (or files) defining the dynamically changing variable(s):
Each file contains a list of one dynamically varying acquisition parameters, one value per spectrum. These values are passed to the functions defined in the configuration file.
Command line Interface Options
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Below are detailed explanations of some of the optional arguments in the wrapper script. Type :code:`fsl_dynmrs --help` to get the full set of available options.
:code:`--ppmlim LOW HIGH`
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 metabolites 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:`--lorentzian`
By default the lineshape is a Voigt (lorentizian+gaussian). Use this flag to set to Lorentzian.
:code:`--report`
Generate an HTML report of the fitting.
:code:`--no_rescale`
Do not rescale the input data before fitting. By default all spectra are rescaled using a single scaling factor.
......@@ -161,11 +161,7 @@ Below are detailed explanations of some of the optional arguments in the wrapper
: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:`--add_MM_MEGA`
Add linked macromolecule peaks at 0.915 & 3.0 ppm (ratio of 3.75:2.0). This option is experimental!
Group metabolites 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:`--lorentzian`
By default the lineshape is a Voigt (lorentizian+gaussian). Use this flag to set to Lorentzian.
:code:`--ind_scale`
......@@ -189,7 +185,6 @@ The wrapper scripts can also take a configuration file as an input. For example,
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:
......@@ -199,7 +194,7 @@ The the following calls to :code:`fsl_mrs` or :code:`fsl_mrsi` are equivalent:
::
fsl_mrs --ppmlim .3 4.1 --metab_groups combine_all --TE 11 --add_MM --report
fsl_mrs --ppmlim .3 4.1 --metab_groups combine_all --TE 11 --report
......
fMRS Analysis
=============
FSL-MRS includes the :code:`fmrs_stats` script to:
1. form contrasts and combine correlated peaks at the first-level of GLM analysis,
2. perform higher-level group analysis, and,
3. form contrasts on the higher-level.
The higher-level analysis uses the *FLAMEO* tool packaged in FSL (which is also used for higher-level FSL FEAT analysis).
To understand the use of higher-level GLM analysis please see the `FSL documentation <https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/GLM/CreatingDesignMatricesByHand>`_ and `FSL course <https://open.win.ox.ac.uk/pages/fslcourse/website/online_materials.html>`_, specifically the `FMRI2 E2 video <https://www.youtube.com/watch?v=-nf9Hcthnm8>`_.
Using fmrs_stats
----------------
On the command line :code:`fmrs_stats` can be called as shown in the example below. This example carries out all the steps described above. Steps, either forming first-level contrasts, or higher-level contrasts, can be omitted. This documentation will take you through this example, which performs a paired t-test on two groups of fMRS acquisitions acquired from the same subjects. This example is taken from the fMRS demo available from the FSL-MRS team.
.. code-block::
fmrs_stats\
--data results_list\
--output group_stats\
--fl-contrasts fl_contrasts.json\
--combine NAA NAAG\
--combine Cr PCr\
--combine PCh GPC\
--combine Glu Gln\
--hl-design design.mat\
--hl-contrasts design.con\
--hl-contrast-names "STIM>CTRL" "CTRL>STIM"\
--hl-covariance cov_split.mat\
--overwrite
This example:
1. Forms a first-level contrast based on the contents of the :code:`fl_contrasts.json` file,
2. Sums (at the first-level) the NAA peaks, the creatine peaks, the choline peaks, and glutamine and glutamate,
3. Outputs the modified first level results to a new :code:`group_stats` result directory,
4. Then using the supplied design matrix (:code:`design.mat`) and contrasts matrix (:code:`design.con`), uses FLAMEO to perform the higher-level analysis, and,
5. The group level GLM statistics are then output to the :code:`group_stats` result directory.
To achieve this the user must provide a number of input files to the script.
Inputs to fmrs_stats
~~~~~~~~~~~~~~~~~~~~
:code:`--data results_list`
A list of directories containing first-level results created using fsl_dynmrs. These can be listed directly on the command-line or as a list in a text file (with a directory on each separate line). e.g. for three subjects
.. code-block::
sub0_stim\
sub1_stim\
sub2_stim
sub0_ctrl\
sub1_ctrl\
sub2_ctrl
:code:`--fl-contrasts fl_contrasts.json`
A JSON formatted file describing contrasts formed at the first level by linearly combining existing parameters.
Here we will combine two GLM betas (which correspond to blocks of activation) to give a mean activation contrast. We assign a name and to take the mean rather than the sum we pass the scales :code:`[0.5, 0.5]`.
.. code-block::
[
{
"name": "mean_activation",
"betas": ["beta0", "beta1"],
"scale": [0.5, 0.5]
}
]
Multiple contrasts can be listed and created.
:code:`--combine NAA NAAG`
The :code:`--combine` option sums the betas of the peaks listed after the command. In this example betas from NAA and NAAG will be combined. This command can be repeated for multiple combinations. The option works in concert with the :code:`--fl-contrasts` option, taking all parameter covariances into account.
:code:`--hl-design design.mat`
Pass the higher-level design matrix formatted as a `VEST <MRSpectroscopyStorage>`_ formatted file. This is created by forming a simple text file containing the design matrix for a three subject, two-case paired t-test. This is the equivalent input to the :code:`flameo --dm,--designfile` option.
.. code-block::
1 1 0 0
1 0 1 0
1 0 0 1
-1 1 0 0
-1 0 1 0
-1 0 0 1
Subsequently this can be converted to the VEST format by running the packaged :code:`Text2Vest` tool.
.. code-block::
Text2Vest design.txt design.mat
:code:`--hl-contrasts design.con`
As for :code:`--hl-design` but for the contrast matrix. I.e. equivalent to the :code:`flameo --tc,--tcf,--tcontrastsfile` option.
.. code-block::
1 0 0 0
-1 0 0 0
This must also be formatted as a VEST file.
.. code-block::
Text2Vest contrast.txt design.con
:code:`--hl-contrast-names "STIM>CTRL" "CTRL>STIM"`
A name for each defined higher-level contrast (each row) can be defined. Here we name the two contrasts of the paired t-test.
:code:`--hl-covariance cov_split.mat`
For groups with different variances, this file can be used to assign to different covariance groups. Equivalent to the :code:`flameo --cs,--csf,--covsplitfile` option.
Defaults to a single group for all first-level results.
This must also be formatted as a VEST file.
.. code-block::
Text2Vest cov_split.txt cov_split.mat
\ No newline at end of file
......@@ -27,6 +27,8 @@ If this is your first experience with FSL-MRS, get started with the :ref:`Quick
simulation
basis_tools
visualisation
dynamic
fmrs
constants
troubleshooting
changelog
......@@ -13,7 +13,7 @@ For an in depth discussion of the effects of MM basis spectra choice on fitting
Synthetic MM
~~~~~~~~~~~~
Syntheic MM basis spectra may be added using the :code:`--add_MM` flag with :code:`fsl_mrs` or :code:`fsl_mrsi`. In the interactive environment the same can be achieved by calling the method :code:`add_MM_peaks` of :code:`fsl_mrs.core.MRS`.
Synthetic MM basis spectra can be added to a basis set using :code:`basis_tools add_set --add_MM basis_in basis_out`. In the interactive environment the same can be achieved by calling the method :code:`add_default_MM_peaks` in a basis object (of type :code:`fsl_mrs.core.Basis`).
By default this option will add the following basis spectra (in separate metabolite groups) to the basis sets.
......@@ -27,7 +27,9 @@ By default this option will add the following basis spectra (in separate metabol
MM17, 1.7, 2, 10/20
MM21, "2.08, 2.25, 1.95, 3.0", "1.33, 0.22, 0.33, 0.4", 10/20
Additional peaks may be added int he interactive environment by calling :code:`add_MM_peaks` with optional arguments to override the defaults.
Additional peaks may be added in using :code:`basis_tools add_set --gamma ...`, or in the interactive environment by calling :code:`basis.add_MM_peaks`.
Note that when fitting using the synthetic macromolecular peaks the :code:`--metab_groups` option should be used to assign each synthetic MM peak to its own group. E.g., :code:`--metab_groups MM09 MM12 MM14 MM17 MM21`
References
~~~~~~~~~~
......
......@@ -5,12 +5,13 @@ 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:
There are five 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)
4. FSLeyes (highly interactive)
5. SVS results dashboard (interactive)
1. Quick glance
---------------
......@@ -96,3 +97,30 @@ Now to make the power-spectrum display nicely, we need to change the x-axis scal
.. image:: data/fsleyes.png
:width: 700
5. SVS results dashboard
------------------------
**Warning: experimental / new feature**
The results from multiple single voxel (SVS) fits can be viewed on a single webpage by using the `fsl_mrs_summarise` command. For example:
.. code-block::
fsl_mrs_summarise results_dir/
Where :code:`results_dir/` contains sub-directories of results generated by the :code:`fsl_mrs` command.
.. image:: data/fsl_mrs_summarise_0.png
:width: 700
This generates an interactive `Dash` app that displays metabolite concentrations, uncertainties, and QC parameters (SNR and linewidths). Sumamry statistics are given in table form below.
By selecting one of the plotted datasets, the data + fit is displayed lower in the page.
.. image:: data/fsl_mrs_summarise_1.png
:width: 700
.. image:: data/fsl_mrs_summarise_2.png
:width: 700
The single dataset + fit is displayed next to the mean (±1SD) data and fit.
\ No newline at end of file
This diff is collapsed.
%% Cell type:markdown id: tags:
# Example of MRSI fitting on the command line
This notebook demos the process of fitting an MRSI scan using the command line scripts included in FSL-MRS.
### Contents:
- [1. Reconstruction, Processing and Data Conversion](#1.-Reconstruction,-processing-and-data-conversion)
- [2. Segmentation](#2.-Tissue-segmentation)
- [3. Fitting](#3.-Fitting)
- [4. Visualisation of fit](#4.-Visualisation-of-fit)
Will Clarke
June 2020
University of Oxford
%% Cell type:markdown id: tags:
## 1. Reconstruction, processing and data conversion
MRSI reconstruction (from k-space data) can be highly specialised depending on the sequence. For example reconstruction of non-cartesian trajectories (e.g. spirals or concentric-rings) requires regridding or use of the NUFFT. Due to the specialised nature of MRSI reconstruction FSL-MRS does not contain tools for this step.
Simmilarly post-processing of MRSI data is commonly done as part of the reconstruction process. Though many of the processing tools in FSL-MRS can be run on MRSI data they have not been created with MRSI in mind.
This example therefore assumes that you are able to provide reconstructed and processed data ready for fitting. Data can be converted to NIfTI from the Siemens DICOM format using spec2nii. The authors of FSL-MRS and spec2nii are happy to add supported formats if example data and interpretation is provided.
%% Cell type:markdown id: tags:
## 2. Tissue segmentation
Tissue segmentation is required to have meaningful scaling of water referenced metabolite concentrations. mrsi_segment will produce three files, corresponding to the GM, WM and CSF FAST tissue segmentations registered to the MRSI volume.
Run tissue segmentation on the packaged T1 data and mask using the MRSI data file. Here we provide a (partial) .anat file produced by [fsl_anat](https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/fsl_anat) to speed up execution.
This step requires an installation of FSL compatible with fslpy.
%% Cell type:code id: tags:
``` python
#%%capture
%sx mkdir -p MRSI
%sx mrsi_segment -o MRSI -a example_data/example_mrsi/T1.anat example_data/example_mrsi/mrsi.nii.gz
```
%% Cell type:markdown id: tags:
## 3. Fitting
The below is a call to the main MRSI wrapper script. Note the use of the `--add_MM` flag as this metabolite basis does not contain a macromolecule basis. Also note that the mrsi dataset provided is accompagnied by a JSON sidecar file which contains some useful information such as the echo time, the central frequency, and the dwell time.
The below is a call to the main MRSI wrapper script. Note that the basis set used here contains FSL-MRS default MM, for these to work properly we must assign them to individual metabolite groups. This is done by providing the `--metab_groups MM09 MM12 MM14 MM17 MM21` argument. To see how we created the basis set have a look at `example_usage/Example basis spectra conversion.ipynb`.
The script will by default run in parallel on the available CPU cores. Depending on hardware this should take a few minutes.
%% Cell type:code id: tags:
``` python
%sx fsl_mrsi --data example_data/example_mrsi/mrsi.nii.gz \
--basis example_data/example_mrsi/3T_slaser_32vespa_1250.BASIS \
--basis example_data/example_mrsi/3T_slaser_32vespa_1250_noTMS_defaultMM \
--output MRSI/example_mrsi_fit \
--mask example_data/example_mrsi/mask.nii.gz \
--h2o example_data/example_mrsi/wref.nii.gz \
--tissue_frac MRSI/mrsi_seg_wm.nii.gz MRSI/mrsi_seg_gm.nii.gz MRSI/mrsi_seg_csf.nii.gz \
--add_MM \
--baseline_order 2 \
--metab_groups MM09 MM12 MM14 MM17 MM21\
--combine PCho GPC --combine Cr PCr --combine NAA NAAG --combine Glu Gln --combine Glc Tau \
--ignore Gly Gly_1 HG \
--overwrite
--ignore Gly \
--overwrite \
--report
```
%% Cell type:markdown id: tags:
## 4. Visualisation of fit
Now take a look at the outputs. A PNG of the fit to the average of all voxels is provided for a quick sanity check. The folders contain the following:
- concs : concentration for each metabolite or combined metabolites (subfolders contain different types of referencing)
- fit : the model prediction FID, the residual FID, and the baseline (also in the time domain).
- qc : QC parameters split per metabolite
- uncertainties : the std of the fit per metabolite
%% Cell type:code id: tags:
``` python
%sx ls -l MRSI/example_mrsi_fit
```
%% Cell type:markdown id: tags:
Now run the command below in a terminal in order to load the data in FSLeyes. You will need to install the NIfTI-MRS plugin for FSLeyes. Instructions for installation are available [online](https://open.win.ox.ac.uk/pages/wclarke/fsleyes-plugin-mrs/install.html).
Then follow the the instructions [here](https://open.win.ox.ac.uk/pages/wclarke/fsleyes-plugin-mrs/mrsi_results.html) to set it up in such a way that you can explore each voxel's individual fit.
To get started, after installing the plugin, run the following command:
```
fsleyes -smrs example_data/example_mrsi/T1.anat/T1.nii.gz example_data/example_mrsi/mrsi.nii.gz
```
%% Cell type:code id: tags:
``` python
%sx fsleyes -smrs example_data/example_mrsi/T1.anat/T1.nii.gz example_data/example_mrsi/mrsi.nii.gz
```
......