Skip to content

Home

Jump to bottom
Nathan Molinier edited this page Jul 14, 2023 · 33 revisions

Introduction

This repository regroups various functions and scripts that are meant to simplify and help users when correcting MRI BIDS datasets. The types of corrections covered by this script are:

  • Segmentation:
    • Spinal Cord(SC)
    • Gray Matter (GM)
    • Multiple Sclerosis (MS) lesion
    • Spinal Cord Injury (SCI)
  • Labeling:
    • Vertebral
    • Spinal cord compression

Feedback and suggestions for improvement are highly appreciated. Feel free to open an issue to report bugs, propose new features, or ask questions.

What is the config file ??

Several times in this wiki and in the code, mentions about a <CONFIG_FILE> will be made and understanding its objective is essential to understand how the different workflows work.

This <CONFIG_FILE> is a yaml file where two main information are gathered:

  • An information about the type of correction wanted (i.e. FILES_SEG, FILES_LESION, FILES_LABEL...)
  • A list of all the images we want to correct/create new labels

Note: This last information is essential to be able to create label for only specific subjects in a dataset.

Here is an example of a <CONFIG_FILE>:

FILES_SEG:
- sub-001_T1w.nii.gz
- sub-002_T2w.nii.gz
FILES_GMSEG:
- sub-001_T1w.nii.gz
- sub-002_T2w.nii.gz
FILES_LESION:
- sub-001_T1w.nii.gz
- sub-002_T2w.nii.gz
FILES_LABEL:
- sub-001_T1w.nii.gz
- sub-002_T1w.nii.gz
FILES_COMPRESSION:
- sub-001_T1w.nii.gz
- sub-002_T1w.nii.gz
FILES_PMJ:
- sub-001_T1w.nii.gz
- sub-002_T1w.nii.gz
FILES_CENTERLINE:
- sub-001_T1w.nii.gz
- sub-002_T1w.nii.gz

Workflows presentation

In this section, several correction workflows will be introduced. However, even if the different workflows may have specific related features, the same principle steps will need to be applied by the user in each of these.

Note: An assumption is made that the dataset being corrected is BIDS compliant.

  1. Creating a <CONFIG_FILE> with the information about:
  • the type(s) of correction (FILES_SEG, FILES_LABEL...)
  • the names or paths of all the niftii images that will be corrected
  1. Calling the manual_correction.py script
  2. Starting the corrections

How to correct/create segmentations (SC/GM seg, MS/SCI lesions, etc.)

The workflow is the following:

  • Loop across subjects listed in the <CONFIG_FILE> YML file.
  • Correct the segmentation mask using editing tools. Tip: Toggle the lesion overlay on/off to help validate the accuracy of the label.
  • Press Save button to save the manually corrected segmentation mask. Note: The manual_correction.py will automatically save manually-corrected segmentation masks under the derivatives/labels/ folder at the root of OUTPUT_PATH according to the BIDS convention.

Example command:

python manual_correction.py -path-img <INPUT_PATH>/data_processed -config <CONFIG_FILE> -path-out <OUTPUT_PATH>

T

Examples of <CONFIG_FILE> file:

Spinal cord segmentation corrections:

FILES_SEG:
  - sub-001_T1w.nii.gz
  - sub-002_T2w.nii.gz

Gray matter segmentation corrections:

FILES_GMSEG:
  - sub-001_T2star.nii.gz
  - sub-002_T2star.nii.gz

MS lesion corrections:

FILES_LESION:
  - sub-edm005_ses-M0_PSIR.nii.gz
  - sub-edm008_ses-M0_PSIR.nii.gz
  - sub-edm010_ses-M0_PSIR.nii.gz

Spinal cord segmentation corrections across all subjects using the wildcard *:

FILES_SEG:
  - sub-*_ses-M0_T2w.nii.gz

ℹ️ If your input images have been preprocessed (e.g., reoriented to RPI and resampled) and thus contain the suffix _RPI_r, YML file will have the following format. Also, you will have to use the -suffix-files-in _RPI_r flag.

FILES_SEG:
  - sub-*_ses-M0_T2w_RPI_r.nii.gz

ℹ️ Once all corrections are done, you can generate a QC report by adding the flag -qc-only to the command above. Note that SCT is required for generating QC report.

ℹ️ You can load an additional contrast using -load-other-contrast flag.

ℹ️ You can open an additional orthoview in FSLeyes using the --fsleyes-second-orthoview flag.

Video tutorials

Here is a video for correcting manual SC segmentation: Youtube manual

Here are several helpful videos reviewing how to correct manual MS lesion segmentations: 1, 2, 3, 4.

Vertebral labeling corrections

The workflow is the following:

  • Loop across subjects listed in the <CONFIG_FILE> YML file.
  • Correct the vertebral labeling based on the labeling convention.
  • Press Save and Quit button to save the manually corrected vertebral labeling. Note: The manual_correction.py will automatically save manually-corrected vertebral labeling under the derivatives/labels/ folder at the root of OUTPUT_PATH according to the BIDS convention.

Example command:

python manual_correction.py -path-in <INPUT_PATH>/data_processed -config <CONFIG_FILE> -path-out <OUTPUT_PATH>

Example of <CONFIG_FILE> file:

FILES_LABEL:
  - sub-001_T2w.nii.gz
  - sub-002_T2w.nii.gz

ℹ️ You can specify discs to label using -label-disc-list flag. For example, if you want to correct only the disc C2/C3, specify -label-disc-list 3.

Video tutorial

Here is a video for correcting vertebral labeling: Youtube manual

Manual labeling of spinal cord compression

This is an example on how to label spinal cord compressions in the axial image.

The workflow is the following:

  1. Loop across subjects listed in the <CONFIG_FILE> YML file.
  2. Open the axial and sagittal images in FSLeyes.
  3. Look at the clinical data provided with compression information.
  4. Locate the compression in the sagittal view.
  5. In the axial view, toggle to the maximum compressed slice around the compression
  6. Click on alt+E (Windows) or option+E (macOS) to open edit mode. Select size 1 and click on the pencil.
  7. Place the label at the center of the spinal cord of the axial image.
  8. Repeat steps 4 to 8 for the number of compressions.
  9. Save and quit.

Example command:

python manual_correction.py -path-in <INPUT_PATH>/data_processed -config <CONFIG_FILE> -path-out <OUTPUT_PATH> -load-other-contrast acq-sagittal_T2w

Examples of <CONFIG_FILE> file:

Spinal cord compression labeling:

FILES_COMPRESSION:
  - sub-001_acq-axial_T2w.nii.gz
  - sub-002_acq-axial_T2w.nii.gz

Manual spinal cord centerline extraction

Example command:

python manual_correction.py -path-in <INPUT_PATH>/data_processed -config <CONFIG_FILE>

The workflow is the following:

  • Loop across subjects listed in the <CONFIG_FILE> YML file.
  • The script opens a GUI that allows you to select a few points on the SC so as to extract the centerline.
  • Press Save and Quit button to save the manually extracted centerline. Note: The manual_correction.py will automatically save the manually extracted centerline under the derivatives/labels/ folder at the root of OUTPUT_PATH according to the BIDS convention.

ℹ️ Note that two centerline files (.nii.gz and .csv) will be generated

Examples of <CONFIG_FILE> file:

Spinal cord centerline extraction:

FILES_CENTERLINE:
  - sub-001_T1w.nii.gz
  - sub-002_T2w.nii.gz

Adding corrected segmentations to git-annex

After you finish manual corrections, upload the manually-corrected segmentations to git-annex (see internal documentation).

You can use the copy_files_to_derivatives.py script provided within this repository to copy manually corrected labels (segmentations, disc labels, etc.) from your local derivatives/labels folder to the already existing git-annex BIDS dataset's derivatives/labels folder.

Adding automatically generated and manually QC-ed SC segmentations to git-annex

If automatically generated SC segmentations are fine and you just want to add them to git-annex, you can use -add-seg-only option of the manual_correction.py script. Example command:

python manual_correction.py -path-in <INPUT_PATH>/data_processed/ -path-out <OUTPUT_PATH>/<DATASET_NAME> -config <CONFIG_FILE> -add-seg-only
Clone this wiki locally