BARSTOOL Quantify Metabolites - dwong263/MAGIQ GitHub Wiki

Overview

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.

Preparation

Set Working Directory

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.

Naming Convention for Spectroscopy Files

Spectroscopy (*.out, *.rda) files should be named according to the following rules:

  1. The files corresponding to the water-unsuppressed acquisition should have the _uns suffix.
  2. The files corresponding to the water-suppressed acquisition should have the _sup suffix.
  3. 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

Naming Convention for Images

Images (*.nii.gx) should be named according to the following rules:

  1. 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.
  2. 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

Example

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
β”‚

Load Quantification Parameters

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.

Load FITMAN Output (.out) Files

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.

Confirm Save File Name and Scanner Type

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.

Run Quantification Process

Click the Run Quantification button to begin calculations. You can keep track of the progress by checking the output in the command prompt / console.

Results

After the quantification process is complete, several files are created.

ID_VISIT_<region description>_barstool_output.png

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.

ID_VISIT_<region description>_voxel_overlay.nii.gz

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.

*.csv File

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.
⚠️ **GitHub.com Fallback** ⚠️