Add tutorial for sct_compute_compression in documentation

[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 PR adresses #4158. It adds a tutorial for sct_compute_compression

It includes:

1. Before starting
2. Theory section
3. Generating input files
4. sct_compute_compression usage

Linked issues

Resolves #4158

Data

Links are not working yet for the data, so here are the zip files:

data_compression.zip
data_normalizing-morphometrics-compression.zip

TODO

• Add data to docs repository
• Find another compression image to use as an example
• Add images in the tutorial data
• Add zip with input files if they want to skip

[valosekj]

Thanks for the updates, @sandrinebedard! The tutorial is excellent! I left only a few very minor suggestions.

[sandrinebedard]

@joshuacwnewton is there a way here: https://spinalcordtoolbox--4162.org.readthedocs.build/user_section/tutorials/shape-analysis.html to only have the Cross-sectional area (CSA) in the TOC and not the other CSA (since they are now in the same page?

[joshuacwnewton]

Yes, of course!

When we include a page in the TOC, like this:

spinalcordtoolbox/documentation/source/user_section/tutorials/shape-analysis.rst

Line 16 in 4ab64c6

shape-analysis/cross-sectional-area

It will include links to all top-level headers in the file. And, in this case, the CSA page has multiple top-level headers (####):

spinalcordtoolbox/documentation/source/user_section/tutorials/shape-analysis/cross-sectional-area.rst

Lines 3 to 10 in 4ab64c6

	Cross-sectional area (CSA)
	######################################################
	This section demonstrates how to compute spinal cord cross-sectional area.
	CSA (Averaged across vertebral levels)
	######################################

So, it is just a matter of bumping the lower headers down to the next level by using a symbol other than #.

[joshuacwnewton]

Hmm. Since the "Shape metrics" section has been reorganized, I realize the structure is a bit strange?

Shape analysis
-- Before starting
-- CSA
-- Other shape metrics
-- Verifying correctness
-- Compression
  -- Before starting
  -- [...]

There's kind of... two nested "before starting" pages? (It's like the first set of pages are individual pages, while "Compression" is a whole extra sub-tutorial.) Which could get a little confusing...

So, I'm wondering if a structure like this could be better:

Shape analysis
-- 1. Computing CSA, area, and other shape metrics
  -- Before starting
  -- CSA
  -- Other shape metrics
  -- Verifying correctness
-- 2. Compression
  -- Before starting
  -- [...]

That way, "Before starting" applies to each of the 2 different sub-tutorials (1. basic sct_process_segmentation usage 2. using sct_process_segmentation for compression analysis).

[joshuacwnewton]

This is the same structure that the "Registration" section has -- one "main page" divided into separate self-contained sub-tutorials.

[valosekj]

So, I'm wondering if a structure like this could be better:

Shape analysis
-- 1. Computing CSA, area, and other shape metrics
  -- Before starting
  -- CSA
  -- Other shape metrics
  -- Verifying correctness
-- 2. Compression
  -- Before starting
  -- [...]

Makes sense to me!

[sandrinebedard]

Makes sense to me too!

[joshuacwnewton]

Great! I'll make this change, check over any remaining outstanding feedback (i.e. the open comments from Julien at the start of the PR), and then merge this PR. :)

[joshuacwnewton]

Done in da38c92!

I think we're good to merge now. :)