Skip to content

GitLab

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

Merge branch 'master' into 'master' 

V1.1.0 NIfTI-MRS

See merge request fsl/fsl_mrs!16
parents 11edbcf4 458c77f3
Pipeline #7862 failed with stages
in 1 minute and 22 seconds
Expand all Hide whitespace changes
Inline Side-by-side
.gitlab-ci.yml
View file @ c6dc31cc
......@@ -49,31 +49,15 @@ stages:
# when and where jobs are executed.
####################################
.only_upstream: &only_upstream
only:
- branches@fsl/fsl_mrs
.only_master: &only_master
only:
- master
.only_releases: &only_releases
only:
- tags@fsl/fsl_mrs
.except_releases: &except_releases
except:
- tags
# ############
# # 1. style
# ############
flake8:
<<: *except_releases
image: python:3.7-slim-buster
stage: style
before_script:
......@@ -81,6 +65,7 @@ flake8:
- pip install flake8
script:
- flake8 fsl_mrs
- flake8 fsl_mrs/scripts/*
allow_failure: true
############
......@@ -88,6 +73,7 @@ flake8:
############
pytest:
<<: *except_releases
image: wtclarke/fsl_mrs_tests:1.0
stage: test
variables:
......@@ -108,10 +94,16 @@ pytest:
############
pages:
<<: *only_master
variables:
GIT_LFS_SKIP_SMUDGE: "1"
GIT_STRATEGY: clone
only:
- master@wclarke/fsl_mrs
- tags@fsl/fsl_mrs
image: python:3.7
stage: doc
script:
- git describe --tag --dirty
- pip install -U sphinx sphinx_rtd_theme
- pip install .
- sphinx-build -b html ./docs/user_docs public
......
CHANGELOG.rst
View file @ c6dc31cc
This document contains the FSL-MRS release history in reverse chronological order.
1.1.0 (Thursday 18th February 2021)
-----------------------------------
- Support for NIfTI-MRS format.
- Preprocessing scripts reoriented around NIfTI-MRS framework
- New script results_to_spectrum for generating full fits in NIfTI-MRS format from fsl_mrs results.
- Documentation and example data updated for move to NIfTI-MRS.
- Added mrs_info command to give quick text summary of NIfTI-MRS file contents.
- Updates to the WIP dynamic fitting module.
1.0.6 (Tuesday 12th January 2021)
---------------------------------
- Internal changes to core MRS class.
......@@ -10,7 +19,7 @@ This document contains the FSL-MRS release history in reverse chronological orde
- Synthetic spectra now use fitting model directly.
- Bug fixes in the fsl_Mrs commandline interface. Thanks to Alex Craig-Craven.
- WIP: Dynamic fitting model and dynamic experiment simulation.
- spec2nii requirement pinned to 0.2.11 during NIFTI-MRS development.
- spec2nii requirement pinned to 0.2.11 during NIfTI-MRS development.
1.0.5 (Friday 9th October 2020)
-------------------------------
......
README.md
View file @ c6dc31cc
......@@ -52,6 +52,8 @@ After installation see the [quick start guide](https://open.win.ox.ac.uk/pages/f
: simulate basis spectra
- **mrs_vis**
: quick visualisation of the spectra or basis spectra
- **mrs_info**
: quick information on NIfTI MRS file
- **svs_segment & mrsi_segment**
: Run tissue segmentation for SVS/MRSI from T1 image.
......
docs/user_docs/conf.py
View file @ c6dc31cc
......@@ -26,6 +26,7 @@ copyright = f'{date.year}, Will Clarke & Saad Jbabdi, University of Oxford, Oxfo
author = 'William Clarke'
# The full version, including alpha/beta/rc tags
print(f'fsl_mrs version: {fsl_mrs.__version__}')
version = fsl_mrs.__version__
release = version
......
docs/user_docs/data/mrs_vis_dir.png
View replaced file @ 11edbcf4 View file @ c6dc31cc
docs/user_docs/data/mrs_vis_dir.png

295 KB | W: | H:

docs/user_docs/data/mrs_vis_dir.png

255 KB | W: | H:

docs/user_docs/data/mrs_vis_dir.png
docs/user_docs/data/mrs_vis_dir.png
docs/user_docs/data/mrs_vis_dir.png
docs/user_docs/data/mrs_vis_dir.png
  • 2-up
  • Swipe
  • Onion skin
docs/user_docs/data/raw_conv.png
View replaced file @ 11edbcf4 View file @ c6dc31cc
docs/user_docs/data/raw_conv.png

120 KB | W: | H:

docs/user_docs/data/raw_conv.png

95.4 KB | W: | H:

docs/user_docs/data/raw_conv.png
docs/user_docs/data/raw_conv.png
docs/user_docs/data/raw_conv.png
docs/user_docs/data/raw_conv.png
  • 2-up
  • Swipe
  • Onion skin
docs/user_docs/data_conversion.rst
View file @ c6dc31cc
......@@ -2,21 +2,23 @@
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 :code:`spec2nii`. Spec2nii currently converts SVS and MRSI data to NIfTI from the following formats.
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-MRS format. To facilitate the conversion of data to this format FSL-MRS is distributed with an additional conversion tool :code:`spec2nii`. Spec2nii currently converts SVS and MRSI data to NIfTI-MRS 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
Philips .SPAR/.SDAT Yes No Yes
GE .7 (pfile) Yes No Yes
UIH DICOM .dcm Yes Yes Yes
LCModel .RAW Yes No No
jMRUI .txt Yes No No
jMRUI .txt Yes No No
jMRUI .mrui 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>`_.
Bruker format conversion is currently under development. 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
---------------
......@@ -44,6 +46,8 @@ Spec2nii can then be run to convert all data from a single ‘evalinfo’ flag.
‘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.
Twix format loop variables (e.g. `Ave` or `ida`) can be assigned to specific NIfTI-MRS dimensions using the :code:`-d{5,6,7}` command line options. NIfTI MRS dimension tags (e.g. `DIM_COIL`) can be specified using the :code:`-t{5,6,7}` command line options.
DICOM
~~~~~
......@@ -51,17 +55,28 @@ Spec2nii can be passed a single file or directory of DICOM files for conversion.
::
spec2nii dicom <file_or_dir>
NIfTI-MRS dimension tags (e.g. `DIM_COIL`) can be specified using the `-t` command line argument.
UIH DICOM
~~~~~~~~~
Conversion for UIH DICOM format SVS and CSI spectroscopy.
::
spec2nii uih DCM_FILE_or_DIR
NIfTI MRS dimension tags (e.g. `DIM_COIL`) can be specified using the `-t` command line argument.
Philips
~~~~~~~
Conversion for Philips SDAT/SPAR files. Orientation information not validated.
Conversion for Philips SDAT/SPAR files.
::
spec2nii philips <SDAT> <SPAR>
GE
~~
Conversion for GE pfiles (.7). Orientation information not validated.
Conversion for GE pfiles (.7).
::
spec2nii GE <file>
......
docs/user_docs/introduction.rst
View file @ c6dc31cc
......@@ -18,4 +18,4 @@ Citing FSL-MRS
--------------
If you use FSL-MRS please cite:
Clarke WT, Stagg CJ, Jbabdi S. FSL-MRS: An end-to-end spectroscopy analysis package. Biorxiv 2020
\ No newline at end of file
Clarke WT, Stagg CJ, Jbabdi S. FSL-MRS: An end-to-end spectroscopy analysis package. MRM https://doi.org/10.1002/mrm.28630
\ No newline at end of file
docs/user_docs/processing.rst
View file @ c6dc31cc
......@@ -4,13 +4,13 @@ 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.
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 [NEAR20]_. 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 a complete overview of pre-processing we recommend [NEAR20]_. In short, the data must be coil combined, processed to remove small frequency drifts and corrupted transients, averaged, corrected for eddy currents, and finally 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.
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.
......@@ -25,10 +25,10 @@ Subcommands
======================= ==============================================================
fsl_mrs_proc operation Description
======================= ==============================================================
coilcombine Combine individual coils of receiver phased array.
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.
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.
......@@ -68,7 +68,7 @@ fsl_mrs_preproc
---------------
:code:`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.
The script requires the user to provide unsuppressed data (--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
......@@ -88,9 +88,9 @@ 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
from fsl_mrs.utils.preproc import nifti_mrs_proc
Reports can be generated using the associated [subcmd]_report functions in the preproc submodules.
Reports and figures can be generated using the :code:`figure` and :code:`report` keyword arguments.
fsl_mrs_proc subcommand specifics
---------------------------------
......@@ -99,7 +99,7 @@ fsl_mrs_proc subcommand specifics
Takes a list of files (:code:`--file`) and runs a weighted SVD [RODG10]_ coil combination on them optionally using a single water reference dataset (:code:`--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 (:code:`--noprewhiten`).
2. average (averaging)
Takes either a single file or list of files (:code:`--file`) and takes the mean across the list of files (:code:`--avgfiles`) or across a certain dimension (:code:`--dim`, indexes from 0).
Takes a file as input (:code:`--file`) and takes the mean across across a certain dimension (:code:`--dim`, either a NIfTI-MRS tag or dim index (5, 6, 7).
3. align (phase-frequency alignment)
Takes a list of files (:code:`--file`) and aligns each FID to the FID nearest to the mean, or to a single passed reference FID (:code:`--reference`). The ppm range can be defined (:code:`--ppm`, default = 0.2->4.2 ppm).
......
docs/user_docs/quick_start.rst
View file @ c6dc31cc
......@@ -11,41 +11,54 @@ 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 + json format. You can do this 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 NIfTI-MRS 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
spec2nii dicom -f my_metab_file 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. 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>`.
This will convert the dicom file (metab.dcm) to a NIfTI file named my_metab_file.nii.gz. 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>`.
A directory of DICOM data can also be converted::
spec2nii dicom -f my_metab_file -j ./dcm_metab_dir/
spec2nii dicom -f my_metab_file ./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, ...`
The output of the above command will also be `my_metab_file.nii.gz` but the converter will append dynamics into higher NIfTI-MRS dimensions (continuing up to the number of DICOM instances in the directory).
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/
spec2nii dicom -f my_wref_file ./dcm_wref_dir/
spec2nii dicom -f my_ecc_file ./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::
You can use :code:`mrs_info` and :code:`mrs_vis` on the command line to view your data at any stage of the process. First mrs_info to see the dimensionality of the data::
mrs_vis my_metab_file_000.nii.gz
mrs_info my_metab_file.nii.gz
You should see some **noisy** data
Read file my_metab_file.nii.gz (/path_to_file).
NIfTI-MRS version 0.2
Data shape (1, 1, 1, 4096, 32, 64)
Dimension tags: ['DIM_COIL', 'DIM_DYN', None]
Spectrometer Frequency: 297.219948 MHz
Dwelltime (Bandwidth): 8.330E-05s (12005 Hz)
Nucleus: 1H
Field Strength: 6.98 T
Then mrs_vis to visualise the data::
mrs_vis my_metab_file.nii.gz
:code:`mrs_vis` will automatically perform coil combination and averaging down to a single spectrum for display purposes only.
.. image:: data/raw_conv.png
:width: 600
You can also see all the converted data in a directory::
You can also quickly view data across one of the NIfTI-MRS higher dimensions (those containing uncombined coils, or averages etc.) In this case we plot all the transients stored in the dimension tagged *DIM_DYN* (i.e. averages)::
mrs_vis ./my_conv_data/
mrs_vis my_metab_file.nii.gz --display_dim DIM_DYN
.. image:: data/mrs_vis_dir.png
:width: 600
......@@ -56,15 +69,15 @@ Have a look at the :ref:`Visualisation <visualisation>` page for more informatio
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.
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 :code:`fsl_mrs_proc` commands to pre-process your raw data. :code:`fsl_mrs_proc` contains routines for many common steps (e.g. coil combination, phase-frequency alignment, residual water removal). E.g.::
Use the :code:`fsl_mrs_proc` commands to pre-process your raw data. :code:`fsl_mrs_proc` contains routines for many common processing steps (e.g. coil combination, phase-frequency alignment, residual water removal). For example::
fsl_mrs_proc coilcombine --file my_metab_file*.nii.gz --reference my_wref_file.nii.gz --output combined -r
fsl_mrs_proc align --file combined*.nii.gz --ppm 1.8 3.5 --output aligned -r
fsl_mrs_proc average --file aligned*.nii.gz --avgfiles --output avg -r
fsl_mrs_proc remove --file avg.nii.gz --output water_removed -r
fsl_mrs_proc phase --file water_removed.nii.gz --output metab -r
fsl_mrs_proc coilcombine --file my_metab_file.nii.gz --reference my_wref_file.nii.gz --output combined -r
fsl_mrs_proc align --file combined.nii.gz --ppm 1.8 3.5 --output aligned -r
fsl_mrs_proc average --file aligned.nii.gz --dim DIM_DYN --output avg -r
fsl_mrs_proc remove --file avg.nii.gz --output water_removed -r
fsl_mrs_proc phase --file water_removed.nii.gz --output metab -r
The -r requests a HTML report to be generated for each stage of the processing. The different HTML reports can be merged using::
......@@ -74,7 +87,7 @@ If your data is unedited single voxel (SVS) try out the prepackaged processing p
::
fsl_mrs_preproc --output processed --data my_metab_file*.nii.gz --reference my_wref_file*.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>`)
......@@ -128,9 +141,9 @@ 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.
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|_.
To access these clone the |fslmrs_gitlab|_ with `Git LFS <https://git-lfs.github.com/>`_ installed.
You will need to have jupyter notebook installed::
......
docs/user_docs/visualisation.rst
View file @ c6dc31cc
......@@ -15,7 +15,7 @@ There are 4 ways of visualising/interacting with MRS data in FSL-MRS:
1. Quick glance
---------------
The first thing one might want to do when given a FID file or simulated spectra is to have a quick look at the FFTs to see if they look like one would expect. FSL-MRS provides a light-weight script (:code:`mrs_vis`) to quickly glance at the MRS or MRSI data. For example, running :code:`mrs_vis` on the provided example SVS data:
The first thing one might want to do when given a FID file or simulated spectra is to have a quick look at the spectra to see if they look like one would expect. To get a sense of the dimensionality and basic status of the data run :code:`mrs_info` for a quick text summary. FSL-MRS then provides a light-weight script (:code:`mrs_vis`) to quickly visualise the MRS or MRSI data. For example, running :code:`mrs_vis` on the provided example SVS data:
::
......@@ -26,7 +26,7 @@ gives the following basic plot:
.. image:: data/mrs_vis_svs.png
:width: 400
Note that the reason :code:`mrs_vis` "knows" how to scale the x-axis is that the relevant information is stored in the JSON sidecar (namely the *dwell time* and the *central frequency*).
Note that the reason :code:`mrs_vis` "knows" how to scale the x-axis is that the relevant information is stored in the NIfTI-MRS MRS header extension (namely the *dwell time* and the *central frequency*).
:code:`mrs_vis` can also visualise a folder of mrs data::
......
example_usage/.gitignore LFS
View file @ c6dc31cc
No preview for this file type
example_usage/Example MRSI fitting.ipynb
View file @ c6dc31cc
......@@ -39,14 +39,10 @@
#%%capture
%sx mkdir -p MRSI
%sx mrsi_segment -o MRSI -a example_data/example_mrsi/T1.anat example_data/example_mrsi/mrsi.nii.gz
```
%%%% Output: execute_result
[]
%% Cell type:markdown id: tags:
## 3. Fitting
The below is a call to the main MRSI wrapper script. Not the use of the :code:`--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.
......@@ -68,14 +64,10 @@
--combine PCho GPC --combine Cr PCr --combine NAA NAAG --combine Glu Gln --combine Glc Tau \
--ignore Gly HG \
--overwrite
```
%%%% Output: execute_result
[]
%% 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:
......@@ -90,20 +82,10 @@
``` python
%sx ls -l MRSI/example_mrsi_fit
```
%%%% Output: execute_result
['total 272',
'drwxr-xr-x 6 saad staff 192 15 Jun 21:45 concs',
'drwxr-xr-x 8 saad staff 256 15 Jun 21:45 fit',
'-rw-r--r-- 1 saad staff 134462 15 Jun 21:43 fit_avg.png',
'-rw-r--r-- 1 saad staff 1388 15 Jun 21:43 options.txt',
'drwxr-xr-x 50 saad staff 1600 15 Jun 21:45 qc',
'drwxr-xr-x 31 saad staff 992 15 Jun 21:45 uncertainties']
%% Cell type:markdown id: tags:
Now run the command below in a terminal in order to load the data in FSLeyes. Follow the instructions [here](https://users.fmrib.ox.ac.uk/~saad/fsl_mrs/html/visualisation.html#fsleyes) to set it up in such a way that you can explore each voxel's individual fit.
```
......@@ -111,7 +93,7 @@
```
%% Cell type:code id: tags:
``` python
%sx fsleyes example_data/example_mrsi/T1.anat/T1.nii.gz example_data/example_mrsi/mrsi.nii.gz MRSI/example_mrsi_fit/fit/fit.nii.gz MRSI/example_mrsi_fit/fit/baseline.nii.gz MRSI/example_mrsi_fit/concs/internal/NAA+NAAG.nii.gz
```
......
example_usage/Example SVS processing - command-line.ipynb
View file @ c6dc31cc
......@@ -20,15 +20,13 @@
%% Cell type:markdown id: tags:
## 1. File conversion using spec2nii
Run spec2nii twix -v to establish the file contents, then using this information run spec2nii twix -e with the appropriate flags to extract the required scans.
Run spec2nii twix -v to establish the file contents, then using this information run spec2nii twix -e with the appropriate flags to extract the required scans. The -q flag suppresses text output.
The -j option causes a JSON side-car file to be generated. The -q flag suppresses text output.
This dataset uses a modified versions of the cmrr spectro package sequences on a siemens scanner. It has three sets of water reference scans. The first is taged as a phase correction, iscollected at the start of the main suppressed water scan and will be used for eddy current correction.
This dataset uses a modified versions of the CMRR spectro package sequences on a Siemens scanner. It has three sets of water reference scans. The first is tagged as a phase correction, ans is collected at the start of the main suppressed water scan and will be used for eddy current correction.
The second is collected in a separate scan with only the RF portion of the water suppression disabled. This is used for coil combination (and could be used for eddy current correction). The third is collected with the OVS and all aspects of the water suppression disabled. It therefore experiences eddy currents unlike all the other scans. It will be used for final concentration scaling.
%% Cell type:code id: tags:
......@@ -42,23 +40,23 @@
From the final lines of the output of the first cell we can see that this "twix" file contains two groups of data.
The first is tagged as "image" and contains 64 repetitions (sets) of 4096 point FIDs collected on 32 channels.
The second has a single FID on each channel.
We now call spec2nii again specifying the group we want to extract each time. spec2nii will generate a NIfTI file for each repetition (set) with a size of 1x1x1x4096x32.
We now call spec2nii again specifying the group we want to extract each time. Each call to spec2nii will generate a NIfTI MRS file with a size of 1x1x1x4096x32xNdyn, where Ndyn is the number of dynamics (repeats).
We repeat this for the water reference scans, extracting just the image data.
%% Cell type:code id: tags:
``` python
%%bash
spec2nii twix -e image -f steam_metab_raw -o data -j -q example_data/meas_MID310_STEAM_metab_FID115673.dat
spec2nii twix -e phasecor -f steam_ecc_raw -o data -j -q example_data/meas_MID310_STEAM_metab_FID115673.dat
spec2nii twix -e image -f steam_metab_raw -o data -q example_data/meas_MID310_STEAM_metab_FID115673.dat
spec2nii twix -e phasecor -f steam_ecc_raw -o data -q example_data/meas_MID310_STEAM_metab_FID115673.dat
spec2nii twix -e image -f steam_wref_comb_raw -o data -j -q example_data/meas_MID311_STEAM_wref1_FID115674.dat
spec2nii twix -e image -f steam_wref_quant_raw -o data -j -q example_data/meas_MID312_STEAM_wref3_FID115675.dat
spec2nii twix -e image -f steam_wref_comb_raw -o data -q example_data/meas_MID311_STEAM_wref1_FID115674.dat
spec2nii twix -e image -f steam_wref_quant_raw -o data -q example_data/meas_MID312_STEAM_wref3_FID115675.dat
```
%% Cell type:code id: tags:
``` python
......@@ -67,15 +65,13 @@
ls data
```
%% Cell type:markdown id: tags:
After conversion we have 64 averages from the suppressed water scan. The "Set" descriptor at the end of the file name arises from the indexing loop used at acquisition time to store the data. This is likely to vary from sequence to sequence, and is the choice of the pulse sequence programmer. Multiple looping indicies might be used for more complex data acquisition strategies.
After conversion we have four files. steam_metab_raw is the the suppressed water data.
We also have one ecc scan, and two "Reps" (another looping index) of each of the water reference scans. In this case both Set and Rep are used to indicate transients that should be averaged toghether.
Notice that each NIfTI file is paired witht a JSON sidecar file which contains useful information for further processing.
We also have one ecc scan, and two water reference scans. The former contains a single dynamic, whilst the latter two contain two dynamics. All have data from 32 uncombined coils.
%% Cell type:markdown id: tags:
## 2. Preprocessing of the data
......@@ -85,11 +81,11 @@
#### Description of steps
1. Take averages of water references used for combination across files
2. Coil combine the metab data, the ecc data and the quantification data using the "comb" data as the reference.
3. Phase and frequency align the data where there are multiple transients.
4. Combine data across those transients (one in each file) by taking the mean.
4. Combine data across those transients by taking the mean.
5. Run eddy current correction using the appropriate reference.
6. In this data an additional FID point is collected before the echo centre. Remove this.
7. Run HLSVD on the data to remove the residual water in the water suppressed data.
6. Phase the data by a single peak as a crude zero-order phase correction.
......@@ -100,25 +96,25 @@
``` python
import os
if not os.path.isdir('fsl_mrs_proc'):
os.mkdir('fsl_mrs_proc')
#1. Combine comb water data across files
%sx fsl_mrs_proc average --file data/steam_wref_comb_raw*.nii.gz --avgfiles --output fsl_mrs_proc --filename steam_wref_comb
#1. Combine water reference data for combination across dynamics
%sx fsl_mrs_proc average --file data/steam_wref_comb_raw.nii.gz --dim DIM_DYN --output fsl_mrs_proc --filename steam_wref_comb
#2. Run coil combination on the three sets of data
%sx fsl_mrs_proc coilcombine --file data/steam_metab_raw*.nii.gz --reference fsl_mrs_proc/steam_wref_comb.nii.gz --output fsl_mrs_proc -r
%sx fsl_mrs_proc coilcombine --file data/steam_wref_quant_raw*.nii.gz --reference fsl_mrs_proc/steam_wref_comb.nii.gz --output fsl_mrs_proc
%sx fsl_mrs_proc coilcombine --file data/steam_metab_raw.nii.gz --reference fsl_mrs_proc/steam_wref_comb.nii.gz --output fsl_mrs_proc -r
%sx fsl_mrs_proc coilcombine --file data/steam_wref_quant_raw.nii.gz --reference fsl_mrs_proc/steam_wref_comb.nii.gz --output fsl_mrs_proc
%sx fsl_mrs_proc coilcombine --file data/steam_ecc_raw.nii.gz --reference fsl_mrs_proc/steam_wref_comb.nii.gz --output fsl_mrs_proc
#3. Align averages of water ref and metab data
%sx fsl_mrs_proc align --file fsl_mrs_proc/steam_metab_raw*.nii.gz --ppm 1.8 3.5 --output fsl_mrs_proc -r --filename steam_metab_align --apod 50
%sx fsl_mrs_proc align --file fsl_mrs_proc/steam_wref_quant_raw*.nii.gz --ppm 4 6 --output fsl_mrs_proc --filename steam_water_align
%sx fsl_mrs_proc align --file fsl_mrs_proc/steam_metab_raw.nii.gz --ppm 1.8 3.5 --output fsl_mrs_proc -r --filename steam_metab_align --apod 50
%sx fsl_mrs_proc align --file fsl_mrs_proc/steam_wref_quant_raw.nii.gz --ppm 4 6 --output fsl_mrs_proc --filename steam_water_align
#3. Combine data across averages
%sx fsl_mrs_proc average --file fsl_mrs_proc/steam_metab_align*.nii.gz --avgfiles --output fsl_mrs_proc -r --filename steam_metab_comb
%sx fsl_mrs_proc average --file fsl_mrs_proc/steam_water_align*.nii.gz --avgfiles --output fsl_mrs_proc --filename steam_wquant_comb
%sx fsl_mrs_proc average --file fsl_mrs_proc/steam_metab_align.nii.gz --dim DIM_DYN --output fsl_mrs_proc -r --filename steam_metab_comb
%sx fsl_mrs_proc average --file fsl_mrs_proc/steam_water_align.nii.gz --dim DIM_DYN --output fsl_mrs_proc --filename steam_wquant_comb
#5. Run the eddy current correction on the data
%sx fsl_mrs_proc ecc --file fsl_mrs_proc/steam_metab_comb.nii.gz --reference fsl_mrs_proc/steam_ecc_raw.nii.gz --output fsl_mrs_proc -r --filename steam_metab_comb_ecc
%sx fsl_mrs_proc ecc --file fsl_mrs_proc/steam_wquant_comb.nii.gz --reference fsl_mrs_proc/steam_wquant_comb.nii.gz --output fsl_mrs_proc --filename steam_wquant_comb_ecc
......@@ -150,22 +146,22 @@
In this section we will preprocess the data using a single preprocessing script which encapsulates all of the commands run above. Some of the commands are optional.
%% Cell type:code id: tags:
``` python
%sx fsl_mrs_preproc --output fsl_mrs_preproc --data data/steam_metab_raw*.nii.gz --reference data/steam_wref_comb_raw*.nii.gz --quant data/steam_wref_quant_raw*.nii.gz --ecc data/steam_ecc_raw.nii.gz --hlsvd --leftshift 1 --t1 example_data/T1_biascorr.nii.gz --overwrite --report
%sx fsl_mrs_preproc --output fsl_mrs_preproc --data data/steam_metab_raw.nii.gz --reference data/steam_wref_comb_raw.nii.gz --quant data/steam_wref_quant_raw.nii.gz --ecc data/steam_ecc_raw.nii.gz --hlsvd --leftshift 1 --t1 example_data/T1.anat/T1_biascorr.nii.gz --overwrite --report
# You can also run this script without independent quant and ecc data (just 1 water reference)
%sx fsl_mrs_preproc --output fsl_mrs_preproc_simple --data data/steam_metab_raw*.nii.gz --reference data/steam_wref_comb_raw*.nii.gz --hlsvd --leftshift 1 --t1 example_data/T1_biascorr.nii.gz --overwrite --report
%sx fsl_mrs_preproc --output fsl_mrs_preproc_simple --data data/steam_metab_raw.nii.gz --reference data/steam_wref_comb_raw.nii.gz --hlsvd --leftshift 1 --t1 example_data/T1.anat/T1_biascorr.nii.gz --overwrite --report
```
%% Cell type:markdown id: tags:
### 3. Run tissue segmentation
Run tissue segmentation on the packaged T1 data and mask using the SVS voxel. 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. If you don't want to run this step the fitting step will run using a pre-packaged tissue segmentation file.
This step requires an installation of FSL compatible with fslpy. If you don't want to run this step the fitting step can be run using a pre-packaged tissue segmentation file (example_data/segmentation.json).
%% Cell type:code id: tags:
``` python
%sx svs_segment -a example_data/T1.anat fsl_mrs_proc/metab.nii.gz
......@@ -180,11 +176,10 @@
``` python
# Quick fit
%sx fsl_mrs --data fsl_mrs_preproc/metab.nii.gz --basis example_data/steam_11ms --output fit_short --metab_groups Mac --overwrite --report --t1 example_data/T1.anat/T1_biascorr.nii.gz --h2o fsl_mrs_preproc/wref.nii.gz --tissue_frac segmentation.json
```
%% Cell type:markdown id: tags:
Or run a full fit with the MCMC method
......
fsl_mrs/__init__.py
View file @ c6dc31cc
......@@ -2,5 +2,5 @@ from ._version import get_versions
__version__ = get_versions()['version']
del get_versions
from fsl_mrs.core import MRS
from fsl_mrs.core import MRSI
\ No newline at end of file
# from fsl_mrs.core import MRS
# from fsl_mrs.core import MRSI
fsl_mrs/core/__init__.py
View file @ c6dc31cc
from fsl_mrs.core.MRS import MRS
from fsl_mrs.core.MRSI import MRSI
from .mrs import MRS
from .mrsi import MRSI
from .nifti_mrs import NIFTI_MRS
from .utility import mrs_from_files, is_nifti_mrs, mrsi_from_files
fsl_mrs/core/MRS.py → fsl_mrs/core/mrs.py
View file @ c6dc31cc
#!/usr/bin/env python
# core.py - main MRS class definition