Skip to content

Home

Jump to bottom
Jan Valosek edited this page Feb 2, 2024 · 32 revisions

Introduction

This wiki page collects frequently asked questions and examples of script usage.

What is the config YAML file?

The config YAML file (<CONFIG_FILE>) contains two main pieces of information:

  • The type of correction wanted (i.e. FILES_SEG, FILES_LESION, FILES_LABEL, ...)
  • A list of the images to correct/create new labels

Below is an example YAML 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

Workflow examples

This section shows several correction workflows (segmentation corrections, lesion corrections, ...).

Segmentation masks (SC/GM segmentation masks, MS/SCI lesion masks)

The workflow is the following:

  • Loop across subjects listed in the <CONFIG_FILE> YAML 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>

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

Examples of MS lesion corrections: 1

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, the config YAML 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

The workflow is the following:

  • Loop across subjects listed in the <CONFIG_FILE> YAML 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-img <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 of how to label spinal cord compressions using sagittal and axial images.

The workflow is the following:

  1. Loop across subjects listed in the <CONFIG_FILE> YAML 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. Press 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-img <INPUT_PATH>/data_processed -config <CONFIG_FILE> -path-out <OUTPUT_PATH> -load-other-contrast acq-sagittal_T2w

ℹ️ You can display sagittal and axial images in two separate ortho views: View -> OrthoView and then Settings -> Ortho View 2 -> View settings -> Display space. See the video tutorial here.

Example 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 labeling of SCI lesions

This is an example of how to label SCI lesions using sagittal and axial images.

  1. Loop across subjects listed in the <CONFIG_FILE> YAML file.
  2. Open the sagittal and axial images in FSLeyes.
  3. Display the sagittal and axial images in two separate ortho views: View -> OrthoView and then Settings -> Ortho View 2 -> View settings -> Display space. See the video tutorial here.
  4. Press alt+E (Windows) or option+E (macOS/Linux) to open edit mode. Use fill value 1 and click on the pencil.
  5. Segment the lesion in the sagittal image (i.e., in the left OrthoView with the sagittal plane). You can use the axial plane for additional information.
  6. Save the lesion with the _lesion.nii.gz suffix.
  7. If the subject also has apparent hemorrhage (T2w hypo-intensity), segment the hemorrhage as a new mask, i.e., in the sagittal plane, create a new mask (Edit -> Create mask or cmd+N (macOS/Linux)). Use fill value 1.
  8. Save the hemorrhage with the lesion_hemorrhage.nii.gz suffix.

ℹ️ Be careful about switching between the overlays when segmenting the lesion and hemorrhage.

Example command:

python manual_correction.py -path-img <INPUT_PATH>/<DATASET> -config <CONFIG_FILE> -load-other-contrast acq-axial_T2w

Example of <CONFIG_FILE> file:

SCI lesion segmentation:

FILES_LESION:
  - sub-001_acq-sag_T2w.nii.gz
  - sub-002_acq-sag_T2w.nii.gz
  - sub-003_acq-sag_T2w.nii.gz

Manual spinal cord centerline labeling

Example command:

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

The workflow is the following:

  • Loop across subjects listed in the <CONFIG_FILE> YAML 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

Example of <CONFIG_FILE> file:

Spinal cord centerline extraction:

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

Manual spinal nerve rootlets labeling

The workflow is the following:

  1. Loop across subjects listed in the <CONFIG_FILE> YAML file.
  2. Open the image in FSLeyes.
  3. Locate spinal nerve rootlet number 2 -- in the sagittal plane, find vertebrae C1 and scroll through the sagittal slices to identify where the nerve exits the spinal canal through the intervertebral foramen
  4. Hide the sagittal plane to save space and zoom the axial plane
  5. Press alt+E (Linux/Windows) or option+E (macOS) to open edit mode. Set the Selection size to 2 and the Fill value to 2. Click on the pencil and label the nerve.
  6. Once the nerve rootlet for spinal level number 2 is segmented, identify spinal nerve rootlet number 3 (see Step 3). Then, change the Fill value to 3 and label the nerve.
  7. Repeat Step 6 for each nerve rootlet. Do not forget to change the Fill value for each nerve!
  8. Save and quit.

ℹ️ Note that we segment only the dorsal nerve rootlets.

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-img <INPUT_PATH>/data_processed/ -path-out <OUTPUT_PATH>/<DATASET_NAME> -config <CONFIG_FILE> -add-seg-only
Clone this wiki locally