Add new CLI script to compute normalized metric ratios (MSCC, etc.) for compressed levels

[sandrinebedard]

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 issue is related to #3733. It computes normalized metrics ratio (MSCC and others) using a reference dataset of healthy subject in the PAM50 anatomical space. It calls sct_process_segmentation to generate the spinal cord morphometrics perslice in the native space and in the PAM50 anatomical dimensions (if -normalize 1) to compute the metric ratio.

It relies on 3 inputs:

• A label file identifying compression sites.
• Spinal cord segmentation
• Vertebral labels

How to test

1. Prepare the development environment by running:

   cd $SCT_DIR
   git checkout sb/3733-bring-metrics-to-pam50-add_mscc 
   git pull
   ./install_sct

2. Download the reference dataset of healthy controls to $SCT_DIR/data/ by running:

   sct_download_data -d PAM50_normalized_metrics
   

3. Generate the 3 necessary input files from this subject file: sub-twh018_T2w.nii.gz

   1. Compression labels (sub-twh018_T2w_compression_labels.nii.gz)
   2. Spinal cord segmentation
   3. Vertebral labels

   # NB: These steps approximate what a tutorial would look like for using this function.
   
   # Identify compression sites using labels
   # NB: These steps are a workaround since -create-viewer can't create multiple labels with the same value 
   #     See also: https://github.com/spinalcordtoolbox/spinalcordtoolbox/issues/3984
   sct_label_utils -create-viewer 1 -i sub-twh018_T2w.nii.gz -o labels1.nii.gz
   sct_label_utils -create-viewer 1 -i sub-twh018_T2w.nii.gz -o labels2.nii.gz
   sct_label_utils -create-viewer 1 -i sub-twh018_T2w.nii.gz -o labels3.nii.gz
   sct_maths -i labels1.nii.gz -add labels2.nii.gz labels3.nii.gz -o sub-twh018_T2w_compression_labels.nii.gz
   
   # Generate spinal cord segmentation
   sct_deepseg_sc -i sub-twh018_T2w.nii.gz -c t2
   # NB: Some manual corrections were performed on the segmentation afterwards,
   #     due to the presence of spinal cord compression.
   
   # Get verterbral labeling
   sct_label_vertebrae -i sub-twh018_T2w.nii.gz -s sub-twh018_T2w_seg.nii.gz -c t2
   

   (Alternatively, you can just download the 3 generated files directly here :
   sub-twh018_T2w_testing_data.zip

4. Run the following example commands:
   Compute ratio of (diameter ap):

   sct_compute_compression -i sub-twh018_T2w_seg.nii.gz -l sub-twh018_T2w_compression_labels.nii.gz -vertfile sub-twh018_T2w_seg_labeled.nii.gz -normalize 1 -o test_mscc.csv
   

   Compute ratio of area (CSA):

   sct_compute_compression -i sub-twh018_T2w_seg.nii.gz -l sub-twh018_T2w_compression_labels.nii.gz  -vertfile sub-twh018_T2w_seg_labeled.nii.gz -metric area -normalize 1 -o test_csa.csv
   

   Test specifying sex and age range

   sct_compute_compression -i sub-twh018_T2w_seg.nii.gz -l sub-twh018_T2w_compression_labels.nii.gz  -vertfile sub-twh018_T2w_seg_labeled.nii.gz  -normalize 1 -o test_mscc_age_sex.csv -sex F -age 35 60
   

   Test without normalization

   sct_compute_compression -i sub-twh018_T2w_seg.nii.gz -l sub-twh018_T2w_compression_labels.nii.gz  -vertfile sub-twh018_T2w_seg_labeled.nii.gz  -normalize 0 -o test_mscc_no_norm.csv
   

What is left

• Remove default value for normalize
• Adapt for multiples labeled slices for one compression
• Add in documentation & tutorial

Linked issues

Fixes #3733.

[joshuacwnewton]

Thank you so much @sandrinebedard and @valosekj for this massive effort! ♥️

[valosekj]

@joshuacwnewton thank you for your detailed review and help! 💯