Merge branch 'enh/v2_dynamic_update' into 'master'

FSL-MRS V2: Basis rework and dynamic fitting release

See merge request fsl/fsl_mrs!56

.gitignore

@@ -19,3 +19,4 @@ example_usage/fsl_mrs_preproc_simple/
 example_usage/fsl_mrs_proc/
 example_usage/report.html
 *.egg-info
+.idea

.gitlab-ci.yml

@@ -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:

CHANGELOG.rst

 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

docs/user_docs/basis_tools.rst

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

docs/user_docs/conf.py

@@ -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

docs/user_docs/dynamic.rst

+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.

docs/user_docs/fitting.rst

@@ -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
 
 
 

docs/user_docs/fmrs.rst

+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

docs/user_docs/index.rst

@@ -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

docs/user_docs/macromolecules.rst

@@ -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
 ~~~~~~~~~~

docs/user_docs/visualisation.rst

@@ -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

example_usage/Example MRSI fitting.ipynb

@@ -61,9 +61,9 @@
    "source": [
     "## 3. Fitting\n",
     "\n",
-    "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.\n",
+    "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`. \n",
     "\n",
-    "The script will by default run in parallel on the available CPU cores. Depending on hardware this should take a few minutes.\n"
+    "The script will by default run in parallel on the available CPU cores. Depending on hardware this should take a few minutes."
    ]
   },
   {
@@ -73,16 +73,17 @@
    "outputs": [],
    "source": [
     "%sx fsl_mrsi --data example_data/example_mrsi/mrsi.nii.gz \\\n",
-    "             --basis example_data/example_mrsi/3T_slaser_32vespa_1250.BASIS \\\n",
+    "             --basis example_data/example_mrsi/3T_slaser_32vespa_1250_noTMS_defaultMM \\\n",
     "             --output MRSI/example_mrsi_fit \\\n",
     "             --mask example_data/example_mrsi/mask.nii.gz \\\n",
     "             --h2o example_data/example_mrsi/wref.nii.gz \\\n",
     "             --tissue_frac MRSI/mrsi_seg_wm.nii.gz MRSI/mrsi_seg_gm.nii.gz MRSI/mrsi_seg_csf.nii.gz \\\n",
-    "             --add_MM \\\n",
     "             --baseline_order 2 \\\n",
+    "             --metab_groups MM09 MM12 MM14 MM17 MM21\\\n",
     "             --combine PCho GPC --combine Cr PCr --combine NAA NAAG --combine Glu Gln --combine Glc Tau \\\n",
-    "             --ignore Gly Gly_1 HG \\\n",
-    "             --overwrite"
+    "             --ignore Gly \\\n",
+    "             --overwrite \\\n",
+    "             --report"
    ]
   },
   {
@@ -135,7 +136,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3.8.12 ('fsl_mrs')",
    "language": "python",
    "name": "python3"
   },
@@ -149,7 +150,12 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.10"
+   "version": "3.8.12"
+  },
+  "vscode": {
+   "interpreter": {
+    "hash": "6c11d37c82810953c5a08a185ec224dab920e965fab2a4fd7bf60d843c04e747"
+   }
   }
  },
  "nbformat": 4,

example_usage/Example basis spectra conversion.ipynb

+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Command-line conversion of LCModel basis set\n",
+    "This notebook demonstrates the conversion of an existing LCModel basis set (`.basis` format).\n",
+    "\n",
+    "In addition to the basic conversion step, three extra steps are performed:\n",
+    "1. Removal of the TMS peak from all spectra\n",
+    "2. Removal of duplicated and unwanted basis spectra\n",
+    "3. Addition of FSL-MRS default MM peaks\n",
+    "\n",
+    "This converted spectrum will subsequently be used to fit the example MRSI data.\n",
+    "\n",
+    "## Step 1 - conversion\n",
+    "We use the `basis_tools` command to convert the basis set. The conversion process preserved the phase/frequency convention fot he LCModel basis set. So to match that expected by FSL-MRS we also reverse it.\n",
+    "    "
+   ]
+  },
+  {