BARSTOOL Quantify Metabolites - dwong263/MAGIQ GitHub Wiki
This tab allows you to produce a *.csv
file containing the estimated metabolite concentrations in mM. It combines information from the fitted prior knowledge templates (*.out
files), information from the GM, WM, and CSF segmented brains (*_std_brain_seg.nii.gz
files), information about the acquisition (header of the *.rda
files) and metabolite-specific information (*.qinfo
files) and calculates metabolite concentrations as detailed here.
Before you begin, ensure that you have selected a working directory. The Working Directory is the directory that contains all of the files required by BARSTOOL to calculate amplitudes and absolute metabolite concentrations.
Note that BARSTOOL auto-selects the spectroscopy, image, and partial volume segmentation files based on the name of the water-suppressed output (*.out
) files. Thus, there is a naming convention you must follow.
Spectroscopy (*.out
, *.rda
) files should be named according to the following rules:
- The files corresponding to the water-unsuppressed acquisition should have the
_uns
suffix. - The files corresponding to the water-suppressed acquisition should have the
_sup
suffix. - The file names have three fields (not including the suffix) separated by the underscore
_
character. The first field represents the participant ID. The second field represents the visit ID (often this is a date). The third field represents the brain region in which the spectroscopy voxel was placed. Do not use spaces, underscores, or other special characters in these fields.
Following these rules results in the following naming convention:
-
ID_VISIT_<region description>_sup.rda
/.out
-
ID_VISIT_<region description>_uns.rda
/.out
Images (*.nii.gx
) should be named according to the following rules:
- The file names have two fields and a suffix separated by the underscore
_
character. The first field represents the participant ID. The second field represents the visit ID (often this is a date). Do not use spaces, underscores, or other special characters in these fields. - The suffixes tells BARSTOOL what kind of image it is. Use the following suffixes:
Suffix | Image |
---|---|
No suffix | Original head anatomical image |
_std.nii.gz |
Original head anatomical image re-oriented to standard space (i.e. result after running fslreorient2std
|
_std_brain.nii.gz |
Skull-stripped anatomical image |
_std_brain_seg.nii.gz |
As described in BARSTOOL Brain Segmentation, this is a binary segmentation with the CSF, GM, and WM masks contained in one image. In this image file, image voxels of intensity 1, 2, and 3 correspond to voxels identified as CSF, GM, and WM, respectively. This is the result after running FSL fast
|
Following these rules results in the following required images:
Filename | Image |
---|---|
ID_VISIT.nii.gz |
Original head anatomical image |
ID_VISIT_std.nii.gz |
Original head anatomical image |
ID_VISIT_std_brain.nii.gz |
Skull-stripped anatomical image |
ID_VISIT_std_brain_seg.nii.gz |
Partial volume (GM, WM, CSF) segmentation |
Suppose your Working Directory is called data/results/
and you have 3 participants called A001, A002, and A003 you'd like to batch process using BARSTOOL. Within data/results/
you should have the following files:
data
βββ results
β βββ A001_20170517_std_brain.nii.gz
β βββ A001_20170517_std_brain_seg.nii.gz
β βββ A001_20170517_lthippo_sup.dat
β βββ A001_20170517_lthippo_sup.out
β βββ A001_20170517_lthippo_sup.rda
β βββ A001_20170517_lthippo_uns.dat
β βββ A001_20170517_lthippo_uns.out
β βββ A001_20170517_lthippo_uns.rda
β βββ A001_20170517_std_brain.nii.gz
β β
β βββ A002_20170517_std_brain_seg.nii.gz
β βββ A002_20170517_lthippo_sup.dat
β βββ A002_20170517_lthippo_sup.out
β βββ A002_20170517_lthippo_sup.rda
β βββ A002_20170517_lthippo_uns.dat
β βββ A002_20170517_lthippo_uns.out
β βββ A002_20170517_lthippo_uns.rda
β β
β βββ A003_20170517_std_brain.nii.gz
β βββ A003_20170517_std_brain_seg.nii.gz
β βββ A003_20170517_lthippo_sup.dat
β βββ A003_20170517_lthippo_sup.out
β βββ A003_20170517_lthippo_sup.rda
β βββ A003_20170517_lthippo_uns.dat
β βββ A003_20170517_lthippo_uns.out
β βββ A003_20170517_lthippo_uns.rda
β
Ensure that you have defined the various parameters required for absolute metabolite quantification and that you have loaded them into BARSTOOL. Briefly, these parameters include the following:
- The number of 1H-MRS-visible protons in each metabolite
- The T1 and T2 relaxation rates in gray matter (GM) and white matter (WM) for each metabolite
- The T1 and T2 relaxation rates of water in gray matter (GM), white matter (WM), and cerebrospinal fluid (CSF)
- The experimental parameters: Repetition time (TR) and echo time (TE)
- The relative proton densities in GM, WM, and CSF
Use the Set Parameters Tab to do this.
Click the Load Suppressed Output Files to select the output files you want to analyze. You may select multiple files and you don't need to select all of the output files in the Working Directory.
Once the files are selected, the Save File Name textbox will populate with your selected Working Directory and a dummy file name (____.csv
). Replace ____.csv
with any name you want. This file will contain a table of the estimated metabolite concentrations in mM for each .out
file you have selected.
There is also an option to select the scanner type. Currently, you can only select the Siemens option. There are plans to support spectroscopy acquisitions from non-Siemens scanners in the future. Because BARSTOOL was developed as a in-house tool for the Centre of Functional and Metabolic Mapping at Robarts Research Institute, where only Siemens scanners are used for human acquisitions, BARSTOOL only supports Siemens scanners for now. Selecting the Siemens option results in BARSTOOL searching for *.rda
files.
If you are working with rodent data using a Bruker or Varian small animal scanner, please use the rodent version of BARSTOOL (BARSTOOL-RV) instead.
Click the Run Quantification button to begin calculations. You can keep track of the progress by checking the output in the command prompt / console.
After the quantification process is complete, several files are created.
This is an image generated by BARSTOOL which shows the spectroscopy voxel position within the brain, the amount of GM, WM, and CSF within the spectroscopy voxel, and a summary of the estimated metabolite levels.
This is an image generated by BARSTOOL representing the spectroscopy voxel as a three-dimensional mask. Because, this image is spatially aligned with ID_VISIT_<region description>_std_brain.nii.gz
, you can overlay ID_VISIT_<region description>_voxel_overlay.nii.gz
on top of ID_VISIT_<region description>_std_brain.nii.gz
in fsleyes
and visualize the placement of the spectroscopy voxel.
This is the file generated by BARSTOOL that contains a table of the estimated metabolite concentrations in mM for each .out
file that has been selected. This file can be opened in Microsoft Excel facilitating easy review and analysis. The information within this file is organized into several columns:
Column | Description |
---|---|
ID | This is the name of the .out file from which the metabolite concentrations were estimated. |
GM | This is the proportion of the spectroscopy voxel that was determined to be gray matter. |
WM | This is the proportion of the spectroscopy voxel that was determined to be white matter. |
CSF | This is the proportion of the spectroscopy voxel that was determined to be cerebrospinal fluid. |
N_AVG_SUP | This is the number of averages used to acquire the water-suppressed data. |
N_AVG_UNS | This is the number of averages used to acquire the water-unsuppressed data. |
SCALE_SUP | This is the overall scaling factor applied to the water-suppressed data by the scanner during acquisition and by FITMAN during the conversion process. |
SCALE_UNS | This is the overall scaling factor applied to the water-unsuppressed data by the scanner during acquisition and by FITMAN during the conversion process. |
SCANNER | This is the scanner type. |
Columns with names of the metabolites (e.g. naa, glu, gln, etc.) | These columns contain the estimated concentration of the metabolites in mM. |
Columns with names of the metabolites followed by the _CRLB suffix (e.g. naa_CRLB, glu_CRLB, gln_CRLB, etc.) |
These columns contain the CramΓ©r-RΓ‘o lower bounds (CRLBs) associated with the fit of each metabolite model to the prior knowledge template. Read more about CramΓ©r-RΓ‘o lower bounds here. |