Skip to content
Jan Valosek edited this page Aug 17, 2023 · 33 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

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 in the axial image.

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

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 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

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