Commit 231523b6 authored by William Clarke's avatar William Clarke
Browse files

Doc updates for NIfTI-MRS.

parent d45eedcc
......@@ -5,6 +5,7 @@ This document contains the FSL-MRS release history in reverse chronological orde
- 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.
1.0.6 (Tuesday 12th January 2021)
---------------------------------
......
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

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
......@@ -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>
......
......@@ -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
......@@ -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).
......
......@@ -11,24 +11,24 @@ 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.
......@@ -36,16 +36,16 @@ But note that there are frequently multiple calibration scans for e.g. shimming
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
You can use :code:`mrs_vis` on the command line to view your data at any stage of the process::
mrs_vis my_metab_file_000.nii.gz
mrs_vis my_metab_file.nii.gz
You should see some **noisy** data
: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 +56,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 +74,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 +128,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::
......
This source diff could not be displayed because it is stored in LFS. You can view the blob instead.
......@@ -9,4 +9,4 @@ nibabel
hlsvdpropy
fslpy>=3.0
pillow
spec2nii==0.2.11
spec2nii>=0.3.0
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment