Add new CLI script to predict compression probability

[valosekj]

Checklist

GitHub

• I've given this PR a concise, self-descriptive, and meaningful title
• I've linked relevant issues in the PR body
• I've applied the relevant labels to this PR
• I've applied a release milestone (major, minor, patch) in line with Semantic Versioning guidelines
• I've assigned a reviewer

PR contents

• I've consulted SCT's internal developer documentation to ensure my contribution is in line with any relevant design decisions
• I've added relevant tests for my contribution
• I've updated the relevant documentation for my changes, including argparse descriptions, docstrings, and ReadTheDocs tutorial pages

Description

This PR adds a script to predict compression probability in a spinal cord MRI image using spinal cord shape metrics. The script requires spinal cord segmentation (used to compute the shape metrics) and disc labels.

Briefly, the script computes shape metrics for 3 axial slices at intervertebral disc levels C3/C4 to C6/7 (3 slices are used to compensate for potential disc label shift in the superior-inferior (S-I) axis; details: #4760 (comment) and 90cbfa6). Then, it predicts compression probability for each of these axial slices using a logistic regression model. The compression probability is printed to CLI and saved to a CSV file; see the next section for examples. More details in: https://pubmed.ncbi.nlm.nih.gov/35371944/. Particularly, equation 4.

How to test this PR

# Download the script
cd $SCT_DIR
git fetch
git checkout jv/add_sct_detect_compression

# Activate SCT python
cd $SCT_DIR
source ./python/etc/profile.d/conda.sh
conda activate venv_sct

# Run the script
python $SCT_DIR/spinalcordtoolbox/scripts/sct_detect_compression.py -s T2w_seg.nii.gz -discfile T2w_discs.nii.gz

Testing on a few spine-generic subjects with mild compression

sub-tokyoIngenia02

cd ~/data/data.neuro.polymtl.ca/data-multi-subject/derivatives/labels/sub-tokyoIngenia02/anat
python $SCT_DIR/spinalcordtoolbox/scripts/sct_detect_compression.py -s sub-tokyoIngenia02_space-other_T2w_label-SC_seg.nii.gz -discfile sub-tokyoIngenia02_T2w_label-discs_dlabel.nii.gz
...
Results saved to: ~/data/data.neuro.polymtl.ca/data-multi-subject/derivatives/labels/sub-tokyoIngenia02/anat/sub-tokyoIngenia02_space-other_T2w_label-SC_seg_compression_results.csv
Disc C3/C4, compression probability: no
Disc C4/C5, compression probability: yes
Disc C5/C6, compression probability: yes
Disc C6/C7, compression probability: yes

Output CSV:

sub-ucl05

cd ~/data/data.neuro.polymtl.ca/data-multi-subject/derivatives/labels/sub-ucl05/anat
python $SCT_DIR/spinalcordtoolbox/scripts/sct_detect_compression.py -s sub-ucl05_space-other_T2w_label-SC_seg.nii.gz -discfile sub-ucl05_T2w_label-discs_dlabel.nii.gz
...
Results saved to: ~/data/data.neuro.polymtl.ca/data-multi-subject/derivatives/labels/sub-ucl05/anat/sub-ucl05_space-other_T2w_label-SC_seg_compression_results.csv
Disc C3/C4, compression probability: no
Disc C4/C5, compression probability: no
Disc C5/C6, compression probability: yes
Disc C6/C7, compression probability: possible

Output CSV:

sub-vuiisAchieva01

cd  ~/data/data.neuro.polymtl.ca/data-multi-subject/derivatives/labels/sub-vuiisAchieva01/anat
python $SCT_DIR/spinalcordtoolbox/scripts/sct_detect_compression.py -s sub-vuiisAchieva01_space-other_T2w_label-SC_seg.nii.gz -discfile sub-vuiisAchieva01_T2w_label-discs_dlabel.nii.gz
...
Results saved to: ~/data/data.neuro.polymtl.ca/data-multi-subject/derivatives/labels/sub-vuiisAchieva01/anat/sub-vuiisAchieva01_space-other_T2w_label-SC_seg_compression_results.csv
Disc C3/C4, compression probability: yes
Disc C4/C5, compression probability: no
Disc C5/C6, compression probability: no
Disc C6/C7, compression probability: no

Output CSV:

Note

Note that the predictive model was trained using axial T2star images from a private dataset. The example spine-generic images shown above are T2w 0.8mm iso. I used these images because they are open-access to verify that the script works properly.
(I did not choose spine-generic T2star images as they cover only C2-C5, while the model detects compression also at discs C5/6 and C6/7).

Linked issues

Follow-up of: 32153ad

[sandrinebedard]

I tested on 2 subjects from stanford:
Works well I think!

sub-NSDCM001

csv result:

C3/C4:

C4/C5:

C5/C6:

C6/C7

sub-NSDCM002

CSV file:

C3/C4

C4/C5:

C5/C6:

C6/C7:

[valosekj]

Just writing it here not to forget: currently, the function outputs a separate CSV file for each subject. However, we might consider the append option, similarly as done by sct_process_segmetnation. In other words, compression probabilities across subjects would be aggregated into a single CSV.
If we decide on that, we would need to add Timestamp, SCT Version, Filename columns to this script to distinguish files across subjects (as done by sct_process_segmetnation):

[joshuacwnewton]

This PR is really close to being merged! Great work again, thank you. ♥️

[joshuacwnewton]

Once the reference formatting nitpick is complete, I think this is good to go!