Analysis pipeline

This repository includes a collection of scripts to analyse BIDS-structured MRI data and output the following metrics for each contrast:

  • T1: Spinal cord CSA averaged between C2 and C3.
  • T2: Spinal cord CSA averaged between C2 and C3.
  • T2s: Gray matter CSA averaged between C3 and C4.
  • DWI: FA in WM averaged between C2 and C5.
  • MTS: MTR in WM averaged between C2 and C5. Uses flip-1_mt-on_MTS and flip-1_mt-off_MTS.
  • MTS: MTSat & T1 map in WM averaged between C2 and C5. Uses flip-1_mt-on_MTS, flip-1_mt-off_MTS and flip-2_mt-off_MTS.

Dependencies

MANDATORY:

  • For processing: SCT 5.0.1.
  • For generating figures: Python >= 3.7

OPTIONAL:

  • FSLeyes for correcting segmentations.

Getting started

Download (or git clone) this repository:

git clone https://github.com/spine-generic/spine-generic.git

Install Python dependencies:

Note

If you prefer to preserve your default Python’s libraries, you could first create a virtual environment, and then run the commands below.

cd spine-generic
pip install -e .

Create a folder where results will be generated (feel free to modify the destination).

mkdir ~/spineGeneric_results

Launch processing:

sct_run_batch -jobs -1 -path-data <PATH_DATA> -path-output ~/spineGeneric_results/ -script process_data.sh

Note

<PATH_DATA> points to a BIDS-compatible dataset. E.g., you could use one of the dataset listed in Multi-center data

Quality Control

After running the analysis, check your Quality Control (QC) report by opening the file ~/spineGeneric_results/qc/index.html. Use the “Search” feature of the QC report to quickly jump to segmentations or labeling results.

Segmentation and vertebral labeling

If you spot segmentation or labeling issues, manually fix them using the procedure described below. Also see the video tutorial below.

  • Create a .yml file that lists the data awating manual correction. You can create this file using any text editor (vim, nano, atom, etc.).
  • In the QC report, enter the string “deepseg” to only display segmentation results or the string “vertebrae” to only display vertebral labeling.
  • Review all spinal cord and gray matter segmentations and vertebral labeling. Use the keyboard shortcuts up/down arrow to switch between subjects and the left arrow to toggle overlay.
  • If you spot major issues with the segmentation (e.g. noticeable leaking or under-segmentation that extends over several slices) or wrong labeling, add the image name into the yml file as in the example below:
FILES_SEG:
- sub-amu01_T1w_RPI_r.nii.gz
- sub-amu01_T2w_RPI_r.nii.gz
- sub-cardiff02_dwi_moco_dwi_mean.nii.gz
FILES_GMSEG:
- sub-amu01_T2star_rms.nii.gz
FILES_LABEL:
- sub-amu01_T1w_RPI_r.nii.gz
- sub-amu02_T1w_RPI_r.nii.gz

Some explanations about this yml file:

  • FILES_SEG: Images associated with spinal cord segmentation
  • FILES_GMSEG: Images associated with gray matter segmentation
  • FILES_LABEL: Images associated with vertebral labeling

Hint

For the interest of time, you don’t need to fix all slices of the segmentation but only the ones listed in the “Relevant levels” column of the table below.

Segmentation Associated image Relevant levels Used for
sub-XX_T1w_RPI_r_seg.nii.gz sub-XX_T1w_RPI_r.nii.gz C2-C3 CSA
sub-XX_T2w_RPI_r_seg.nii.gz sub-XX_T2w_RPI_r.nii.gz C2-C3 CSA
sub-XX_T2star_rms_gmseg.nii.gz sub-XX_T2star_rms.nii.gz C3-C4 CSA
sub-XX_flip-2_mt-off_MTS_seg.nii.gz sub-XX_flip-2_mt-off_MTS.nii.gz C2-C5 Template registration
sub-XX_dwi_concat_crop_moco_dwi_mean_seg.nii.gz sub-XX_dwi_concat_crop_moco_dwi_mean.nii.gz C2-C5 Template registration
  • After you finished the QC, run sg_manual_correction as in the example below:
sg_manual_correction -config files.yml -path-in ~/spineGeneric_results/results/data -path-out <PATH_DATA>

This script will loop through all the files that need correction (as per the .yml file that you created earlier), and open an interactive window for you to either correct the segmentation, or perform manual labels. Each manually-corrected label is saved under the derivatives/labels/ folder at the root of <PATH_DATA>, according to the BIDS convention. The manually-corrected label files have the suffix -manual.

Your name will be asked at the beginning, and will be recorded in the .json files that accompany the corrected labels.

Upload the manually-corrected files

A QC report of all the manual corrections will be created locally and archived as a zip file. To update the database with the manual corrections, follow this procedure:

  • Commit and push the manually-corrected files, which should be placed in the appropriate folders under derivatives/labels/
  • Create a pull request
  • In the pull request body, briefly explain the purpose of these changes, and upload the zipped QC report so the admin team can easily review the proposed changes.
  • If the team accepts the pull request, a new release of the dataset will be created and the zipped QC report will be uploaded as a release object.

Note

In case processing is ran on a remote cluster, it it convenient to generate a package of the files that need correction to be able to only copy these files locally, instead of copying the ~20GB of total processed files. If you are in this situation, use the script package_for_correction.

Re-run the analysis

After you have corrected all the necessary segmentations/labels, you can re-run the analysis (the sct_run_batch command above). If a manually-corrected file exists, it will be used instead of re-creating a new one automatically.

Warning

If you re-run the analysis, make sure to output results in another folder (flag -path-output), otherwise the previous analysis will be overwritten.

Generate figures

Generate figures based on the output csv files using sg_generate_figures.py script. Run this script in /results folder (folder containing csv files) or specify this folder using -path-results flag. The flag -exclude points to a yml file containing the subjects to be excluded from the statistics. To generate html that contrains interactive figures, add the flag -output-html :

sg_generate_figure -path-results ~/spineGeneric_results/results -exclude subject_to_exclude.yml

To generate a mosaic of images, run:

# Sagittal views of 3D T1w data
sg_create_mosaic -i *T1w_RPI_r_flatten.nii.gz -ifolder ~/project/results_multi_20200907/data_processed/ -p sag -col 20 -row 13 -o fig_mosaic_T1w.png
# Axial views of GRE-T1w data
sg_create_mosaic -i *flip-2_mt-off_MTS.nii.gz -ifolder ~/spineGeneric_results/data_processed -s _seg -p ax -col 20 -row 13 -o fig_mosaic_GRE-T1w.png

Results

Cord CSA from T1w

Cord CSA from T2w

CSA agreement between T1w and T2w data

CSA agreement between T1w and T2w data per vendor

Gray matter CSA

Magnetization Transfer Ratio

Magnetization transfer saturation

T1

Fractional Anisotropy

Mean diffusivity

Radial diffusivity