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 segmentationFILES_GMSEG
: Images associated with gray matter segmentationFILES_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 |
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