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.
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.
The script will by default run in parallel on the available CPU cores. Depending on hardware this should take a few minutes.
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
%sxls-lMRSI/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.
"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.\n",
"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.\n",
"\n",
"The -j option causes a JSON side-car file to be generated. The -q flag suppresses text output.\n",
"\n",
"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.\n",
"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.\n",
"\n",
"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."
]
...
...
@@ -60,7 +58,7 @@
"The first is tagged as \"image\" and contains 64 repetitions (sets) of 4096 point FIDs collected on 32 channels. \n",
"The second has a single FID on each channel.\n",
"\n",
"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. \n",
"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).\n",
" \n",
"We repeat this for the water reference scans, extracting just the image data."
"spec2nii twix -e image -f steam_wref_comb_raw -o data -q example_data/meas_MID311_STEAM_wref1_FID115674.dat\n",
"spec2nii twix -e image -f steam_wref_quant_raw -o data -q example_data/meas_MID312_STEAM_wref3_FID115675.dat"
]
},
{
...
...
@@ -96,11 +94,9 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"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. \n",
"After conversion we have four files. steam_metab_raw is the the suppressed water data. \n",
" \n",
"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.\n",
"\n",
"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."
]
},
{
...
...
@@ -117,7 +113,7 @@
"1. Take averages of water references used for combination across files\n",
"2. Coil combine the metab data, the ecc data and the quantification data using the \"comb\" data as the reference.\n",
"3. Phase and frequency align the data where there are multiple transients.\n",
"4. Combine data across those transients (one in each file) by taking the mean.\n",
"4. Combine data across those transients by taking the mean.\n",
"5. Run eddy current correction using the appropriate reference.\n",
"6. In this data an additional FID point is collected before the echo centre. Remove this.\n",
"7. Run HLSVD on the data to remove the residual water in the water suppressed data.\n",
...
...
@@ -136,21 +132,21 @@
"if not os.path.isdir('fsl_mrs_proc'):\n",
" os.mkdir('fsl_mrs_proc')\n",
"\n",
"#1. Combine comb water data across files\n",
"%sx fsl_mrs_proc average --file data/steam_wref_comb_raw*.nii.gz --avgfiles --output fsl_mrs_proc --filename steam_wref_comb\n",
"#1. Combine water reference data for combination across dynamics\n",
"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.\n",
"\n",
"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)."
-[4. Fitting of the resultant spectrum](#4.-Fit-the-data)
-[5. Display the fitting reports](#5.-Display-the-result)
Will Clarke
June 2020
University of Oxford
%% 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.
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.
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.
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.
After conversion we have four files. steam_metab_raw is the the suppressed water data.
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
### 2.1 Pre-processing using fsl_mrs_proc
In this section we will preprocess the data using individual subcommands of the fsl_mrs_proc script to preprocess step-by-step. This example could be used as a template to construct your own preprocessing script in either python or another batch processing script (e.g. bash).
#### 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.
Note that the "%sx" command is only required in this example notebook and are unecessary on the command line.
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.
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).
