ANTsPy tutorial: screenshots, fixes, one document per tab

[muratmaga]

Updates the ANTsPy tutorial after running the whole workflow as written with the 30 ANTsamples specimens (Slicer 5.12.4, SlicerANTsPy main).

Screenshots. Adds 11, covering every step from loading the data to the Analysis tab.

Fixes to steps that did not work as written:

• Specimen count: 30, not 29.
• Crop Volume reorientation: the landmarks must be hardened under the Reorient_… transform before its Apply, because Apply deletes the transform. The ROI step and the output name (… cropped) are now spelled out.
• Output file names: -forward.h5, -0forwardWarp.nii.gz, -1forwardAffine.mat and the inverse files, with correct file counts and sizes. The Analysis file pattern is forwardWarp.nii.gz; the old 1Warp.nii.gz matched no files.
• Median smoothing: the kernel is given in voxels (0.5–0.7 mm for this data). The old 3–5 mm erased the mask.
• Mask export: a -label suffix, so the file loads as a label map.
• Covariates table: an ID column. The Effect Image and FDR check box come from SlicerANTsPy #41. There is a new section on why the FDR correction matters: with the tutorial's random grouping, 2,283 voxels have uncorrected p < 0.05 and none survive FDR.
• Landmark node names: C57BL6_J__1 and so on.

Structure. The tutorial is split into separate documents, one per tab, in the order the tabs are used. They are listed in a new ANTsPy subsection of the top-level README:

• README.md: ANTsPy-I, data and reference specimen
• Groupwise_rigid.md: ANTsPy-II
• Average.md: ANTsPy-III
• Template.md: ANTsPy-IV
• Groupwise_template.md: ANTsPy-V
• Analysis.md: ANTsPy-VI
• Pairwise.md: ANTsPy-VII
• Troubleshooting.md: ANTsPy-VIII

Merge after the SlicerANTsPy extension that includes #41 is available for Slicer 5.12. Until then, the Analysis tab readers see is the old one.

🤖 Generated with Claude Code

[claude]

Claude finished @muratmaga's task in 3m 30s —— View job

---

Review of PR #58

• Gather context (diff, CLAUDE.md, README)
• Review README.md changes for correctness bugs, broken references, edge cases
• Check new images are referenced correctly
• Post findings

This is a documentation-only PR (no code), so the review focused on internal consistency of the rewritten tutorial: numeric claims, cross-references, and the new TOC/section anchors after the reorg into per-tab sections.

Checked and OK:

• All 14 TOC entries resolve to an actual heading (including the new Pair-wise Tab section and the renumbered Step 3–9 headers).
• The Advanced Topics list is correctly renumbered A–G after topic H was promoted out to its own top-level section.
• All 11 new images under ANTsPy/images/ are referenced from the README with correct relative paths.
• The "30 strains" count and the "8 named + 22 more = 30" sample list are internally consistent.

Findings posted inline:

1. ANTsPy/README.md:866 — The stated kernel-size conversion (3–5 voxels → "0.5-0.7 mm" at 0.141 mm/voxel) doesn't match the arithmetic: 3–5 voxels × 0.141 mm ≈ 0.42–0.71 mm, i.e. ~0.4-0.7 mm, not 0.5-0.7 mm.
2. ANTsPy/README.md:1379 — In Troubleshooting, "See Advanced Topics H" still references the old label even though this PR moved that content into a new top-level Pair-wise Tab section (the link target/anchor was correctly updated, but the visible text wasn't).

Additional observation (not inline, since it's outside this PR's diff hunks): ANTsPy/README.md:1431, in Advanced Topics section B ("Multi-level Covariates"), still shows an example CSV with a specimen header column (specimen,group,sex,age). This PR's main covariates fix (Step 9) now requires the column to be named ID instead. Since this PR is specifically about fixing that exact issue, it'd be worth updating this leftover example too so it doesn't contradict the corrected instructions elsewhere in the same document.

Overall the fixes described in the PR body (crop/reorient order, output filenames, FDR section, mask -label suffix, landmark naming) all check out against the rest of the document. No security or workflow-file changes involved.

[claude]

Claude finished @muratmaga's task in 4m 10s —— View job

---

Reviewing PR #58

• Gather context (diff, CLAUDE.md, README)
• Review changed files for correctness bugs, broken references, edge cases
• Check new images are referenced correctly
• Post findings

Summary

This is a thorough rewrite/split of the ANTsPy tutorial, and the content is internally consistent in most places I checked (30-specimen counts line up across README.md, Average.md's averaging script, and Analysis.md's covariate CSV; the 11 new images all resolve to files that were added; the FDR voxel counts — 875 + 1,408 = 2,283 — check out; cross-doc Previous/Next navigation is correct throughout).

I found 3 issues worth a look, posted as inline comments:

1. ANTsPy/README.md (line 270, re: the ## Summary section, lines 213–266) — leftover content from before the tutorial was split into 8 documents. It still claims "You've completed a full morphometric analysis pipeline" with all 8 steps checked off and lists files/next-steps for the entire series, immediately followed by a new "Next: Part II" link — directly contradicting the "you're done" framing, since Part I only covers obtaining data and preparing the reference specimen.
2. ANTsPy/Groupwise_rigid.md (line 49) — the doc references node names (NZBWF1_J_reoriented for both the volume and its landmarks) without ever instructing how they get into the scene. Per the naming convention the tutorial itself documents in README.md (a landmark node loaded with the same base name as an existing node gets a _1 suffix), the landmarks would actually be named NZBWF1_J_reoriented_1 if reloaded fresh — or the volume would still be NZBWF1_J_ cropped if continuing the README session. Either way, the literal node name shown likely won't match the Data module.
3. ANTsPy/Analysis.md (line 72) — minor arithmetic mismatch: 3–5 voxels × 0.141 mm/voxel = 0.42–0.705 mm, but the text states "0.5-0.7 mm." Worth tightening since this value was specifically called out in the PR description as the fix for a step that previously erased the mask.

[claude]

Claude finished @muratmaga's task in 1m 33s —— View job

---

Review of PR #58 (updated after latest push)

• Gather context (diff, prior review comments, current file state)
• Check whether prior review findings were addressed
• Review changed files for correctness bugs, broken references, edge cases
• Post findings

This PR now splits the ANTsPy tutorial into README.md + 7 per-tab files (Groupwise_rigid.md, Average.md, Template.md, Groupwise_template.md, Analysis.md, Pairwise.md, Troubleshooting.md), each with Previous:/Next: navigation, plus a matching ANTsPy subsection in the top-level README.md.

Previously flagged issues — status:

1. ✅ Fixed: the stale "Advanced Topics H" link text now reads "ANTsPy-VII: Pair-wise tab" (Troubleshooting.md:99), matching the new top-level section it points to.
2. ❌ Still open: the kernel-size mm mismatch (3–5 voxels × 0.141 mm ≈ 0.4–0.7 mm, not "0.5-0.7 mm") — the text just moved unchanged into Analysis.md:72. Posted inline.
3. ❌ Still open: the Multi-level Covariates example CSV in Troubleshooting.md:151 still uses a specimen header, contradicting the ID column now required by the fixed Step 9 workflow in Analysis.md:194. Since Troubleshooting.md is a newly added file in this PR, I've now posted this inline as well (previously it was out-of-hunk in the old single-file README).

Newly checked for this reorg (all OK):

• Every cross-file Previous:/Next: link and the two anchored cross-file links (Troubleshooting.md → Analysis.md#why-the-fdr-correction-matters, Troubleshooting.md → Pairwise.md#using-an-existing-transform-as-the-initial-transform) resolve correctly.
• All 11 images referenced across the split files exist under ANTsPy/images/, and there are no orphaned images.
• The top-level README.md's new ANTsPy-I…VIII list matches the actual files and their H1 headings exactly.
• No leftover same-file #anchor links pointing at headings that migrated to another file during the split.
• Step/section numbering within each file (Step 1–3 in README.md; lettered A–F/A–C/A–D/A–G subsections elsewhere) is sequential with no skips or copy-paste duplicates.
• The commit that moved the "Summary" section out of README.md into Analysis.md (and dropped the now-redundant part list) is consistent — Resources/Citation correctly stayed in README.md, and the workflow summary now sits after the last step of the core Jacobian pipeline.

Both open findings are minor documentation inconsistencies, not functional/security issues.

[claude]

Claude finished @muratmaga's task in 1m 1s —— View job

---

Review of PR #58 (updated after latest push)

• Gather context (diff, prior review findings, current file state)
• Check whether previously flagged issues were addressed
• Review new changes for correctness bugs, broken references, edge cases
• Post findings

This push (975935a) turns README.md into a pure overview page and moves Part I's content to a new Data_and_reference.md.

Previously flagged issues — status:

1. ✅ Fixed: the "Summary" section that contradicted Part I by claiming the whole pipeline was done is gone — README.md is now just an intro + part list + Resources/Citation, with no "you're finished" framing.
2. ✅ Fixed: the Groupwise_rigid.md node-name concern — Data_and_reference.md (lines 179–181) now has an explicit export step saving the reoriented volume/landmarks as ANTsamples/NZBWF1_J_reoriented.nii.gz / .mrk.json, which matches the file names Groupwise_rigid.md selects in the Group-wise tab's file pickers.
3. ❌ Still open: kernel-size arithmetic in Analysis.md:72 — "3-5 voxels ... 0.5-0.7 mm" doesn't match 3-5 × 0.141 mm ≈ 0.42-0.71 mm. Posted inline with a suggested fix (0.4-0.7 mm).
4. ❌ Still open: Troubleshooting.md:151 example CSV still uses a specimen header, contradicting the ID column required by the fixed Step 9 workflow (Analysis.md:194). Posted inline with a suggested fix.

Newly checked (all OK):

• Top-level README.md's ANTsPy links all resolve to the correct files (Data_and_reference.md, Groupwise_rigid.md, ..., Troubleshooting.md).
• ANTsPy/README.md's "Tutorial parts" list matches the actual 8 files, in order, with correct link targets.
• No leftover references to the old single-file structure.

Both remaining findings are minor documentation/arithmetic inconsistencies, not functional or security issues — everything else in this round checks out.

[claude]

Claude finished @muratmaga's task in 1m 19s —— View job

---

Review of PR #58 (updated after latest push)

• Gather context (diff, prior review findings, current file state)
• Check whether previously flagged issues were addressed
• Review new changes for correctness bugs, broken references, edge cases
• Post findings

Previously flagged issues — status:

1. ✅ Fixed: the kernel-size wording in Analysis.md:72 no longer has a mismatched mm range. It now reads "3-5 voxels... rounded to a whole, odd number of voxels: for this data (0.141 mm voxels), 0.5 mm gives a 3-voxel and 0.7 mm a 5-voxel kernel" — checking the arithmetic: 0.5 mm / 0.141 mm ≈ 3.55 → nearest odd = 3; 0.7 mm / 0.141 mm ≈ 4.96 → nearest odd = 5. Both check out.
2. ✅ Fixed: Troubleshooting.md:151's Multi-level Covariates example CSV now uses ID,group,sex,age, matching the ID column required by the fixed Step 9 workflow in Analysis.md:194.
3. ✅ Fixed: the Groupwise_rigid.md node-name concern — Data_and_reference.md:180-181 explicitly saves the reoriented volume/landmarks as NZBWF1_J_reoriented.nii.gz / .mrk.json, matching the node names Groupwise_rigid.md references.
4. ✅ Fixed: the old "you're done" Summary block that contradicted Part I framing has been relocated to the end of Analysis.md (after the core 8-step pipeline completes), where it now sits consistently before the Pair-wise/Troubleshooting appendix sections.

Newly checked for this push (all OK):

• Full navigation chain across all 8 split documents (Data_and_reference.md → Groupwise_rigid.md → Average.md → Template.md → Groupwise_template.md → Analysis.md → Pairwise.md → Troubleshooting.md) — every Previous:/Next: link resolves to the correct adjacent file and matches the order/titles listed in README.md's part list.
• No broken cross-file links or dangling anchors found.

No outstanding correctness, security, or broken-reference issues remain. All previously identified documentation inconsistencies have been resolved in this push.