billy-lyc/neuropilot/ants-skill

ANTs MRI Processing

This skill turns Claude into a competent ANTs operator: picking the right command, the right parameters for the input resolution, and explaining what the outputs are. The biggest wins it provides are (1) avoiding the most common failure modes (memory blow-ups, non-convergence, mask-on-wrong-image, transform-order bugs) and (2) emitting reproducible commands rather than improvising.

First-contact behavior (read this every time the skill triggers)

The very first thing to do when this skill triggers, before answering anything and before reading any other reference, is to present the menu defined in `references/menu.md`. This is a hard rule, not a suggestion.

Workflow:

1. Read `qc/QC.md` now and ask the two QC pre-flight questions before anything else. Store the answers for the rest of the session.
2. Read `references/menu.md` now. It defines the exact 2-level menu structure and the wording to use.
3. Show the Level-1 menu (4 categories, one-line each). Wait for the user to pick.
4. Show the Level-2 sub-menu for whichever category the user picked. Wait for them to pick again. For C, there is a third level (C1a/b/c…) — show it after the user picks C1–C4.
5. After they pick a Level-2 task, explain it in 2–4 sentences before asking for parameters. The explanation covers: what command actually runs, what files come out, and (if relevant) one warning or caveat.
6. Then ask for the required parameters in a single batched question, not one at a time.
7. Then run. Prefer bundled scripts in scripts/; only hand-write antsRegistration for the "Advanced / custom" option.

Edge cases:

• User describes a specific task without picking a letter (e.g. "I want to register my T1 to MNI"): still show the menu, with the matching option suggested as your best guess ("This sounds like B1 — confirm?"). Don't auto-route past the menu.
• User asks a clarifying question instead of picking ("what's the difference between B1 and C1a?"): answer briefly, then re-show the menu.
• User explicitly says "skip the menu" / "just run X": comply, but state assumptions explicitly before running.
• Follow-up within the same conversation ("now do the same for sub02", "also warp my mask"): skip the menu, proceed.
• Question is about ANTs but not a task ("what license is ANTs?", "is antsRegistrationSyNQuick deterministic?"): answer directly, don't show the menu.

The point of the menu is to make the skill safe to use for non-experts and explicit for experts. Don't shortcut around it.

Bundled brain templates

This skill ships with ready-to-use brain templates. When the user is working on brain data and needs a template, proactively tell them these are available before asking them to provide a path. Always offer the choice: use a bundled template, or bring your own.

<skill_dir>/templates/
├── MNI152/                         ← registration target (most common)
│   ├── MNI152_T1_1mm.nii.gz        whole head, 1mm — for whole-head subjects
│   ├── MNI152_T1_1mm_brain.nii.gz  brain-extracted, 1mm — use when subject is skull-stripped
│   ├── MNI152_T1_1mm_brain_mask.nii.gz
│   ├── MNI152_T1_2mm.nii.gz        whole head, 2mm — faster, for fMRI workflows
│   ├── MNI152_T1_2mm_brain.nii.gz
│   └── MNI152_T1_2mm_brain_mask.nii.gz
└── OASIS-30/                       ← brain extraction + cortical thickness
    ├── T_template0.nii.gz           head template (antsBrainExtraction.sh -e)
    ├── T_template0_BrainCerebellum.nii.gz
    ├── T_template0_BrainCerebellumProbabilityMask.nii.gz  (antsBrainExtraction.sh -m)
    ├── T_template0_BrainCerebellumRegistrationMask.nii.gz (antsBrainExtraction.sh -f)
    └── Priors2/priors{1-6}.nii.gz   6-class tissue priors (antsCorticalThickness.sh -p)

Environment variables (set once → scripts pick up defaults automatically):

• ANTS_BRAIN_TEMPLATE_DIR → path to OASIS-30/
• ANTS_MNI_DIR → path to MNI152/

Other common templates (not bundled — see references/templates.md for download instructions):

• MNI152NLin2009cAsym — modern nonlinear MNI, used by fMRIPrep / templateflow. Preferred when your pipeline uses fMRIPrep outputs.
• Colin27 — single-subject high-resolution (1×1×1mm), good for anatomy demonstrations or when you need maximum structural detail in a single-subject study.
• MNI152NLin6Asym — HCP project template, same space as HCP data; use when integrating with HCP parcellations.
• Pediatric MNI (NIH Pediatric Database) — for ages 4.5–18.5; do not use adult templates on children.

The standard preprocessing order

Whenever the user asks "what should I do first", default to this order. Skipping a step is fine if the data already had it done upstream — but never reorder.

1. Denoise (DenoiseImage) — optional but cheap
2. N4 bias field correction (N4BiasFieldCorrection)
3. Brain extraction (antsBrainExtraction.sh) — required before any tissue segmentation or cortical-thickness work
4. Registration (antsRegistrationSyN.sh) — to template / atlas / another subject
5. Apply transforms to derived data (masks, labels, fMRI, DTI) using antsApplyTransforms

For cortical thickness, antsCorticalThickness.sh does steps 2–4 plus segmentation in one shot — see references/pipeline_corticalthickness.md.

Picking convergence / shrink / smoothing parameters

This is the place new users get burned. Rules of thumb:

• Number of resolution levels = log2(min image dim / 32), rounded down, capped at 4. For a typical 1mm 256-cube T1, use 4 levels (8x4x2x1).
• Smoothing sigmas in voxels: one less per level, ending at 0 (e.g. 3x2x1x0vox).
• Iterations: linear stages can use generous iteration counts (1000x500x250x100) because they're cheap; SyN should be lower (100x70x50x20) because each iteration is expensive.
• `SyN[gradStep, updateFieldVar, totalFieldVar]`: defaults SyN[0.1, 3, 0] are sane. Increase gradStep (up to 0.25) for faster convergence on similar images; decrease for noisier or cross-modal cases. totalFieldVar=0 lets the deformation be unrestricted; nonzero values smooth the total field and reduce overfitting at the cost of accuracy.

assets/default_convergence_profiles.json has ready-to-use profiles keyed by voxel size. Reach for it when generating commands.

Variable conventions used in scripts

All bundled scripts standardize on:

• $1 (or first named arg) = fixed image (template / target)
• $2 (or second) = moving image (subject)
• $OUTPREFIX = prefix for outputs; ANTs will produce ${OUTPREFIX}0GenericAffine.mat, ${OUTPREFIX}1Warp.nii.gz, ${OUTPREFIX}1InverseWarp.nii.gz, and ${OUTPREFIX}Warped.nii.gz
• Threads come from $NSLOTS if set (cluster convention) else nproc else 4

Output file cheat sheet

After a typical rigid+affine+SyN run with prefix sub01_to_MNI_, you get:

To go subject → MNI: -t sub01_to_MNI_1Warp.nii.gz -t sub01_to_MNI_0GenericAffine.mat (warp listed first in command line, applied last) To go MNI → subject: -t [sub01_to_MNI_0GenericAffine.mat, 1] -t sub01_to_MNI_1InverseWarp.nii.gz

The order is the most common bug — see references/transform_recipes.md section "Transform order" for the full explanation.

Reproducibility checklist

When the user wants reproducible runs (papers, regulatory submissions):

• Set ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS=1 (multithreading introduces nondeterminism in some metrics)
• Use antsRegistrationSyN.sh -y (forces fixed seed and GC metric on linear stages)
• Pin the ANTs version (antsRegistration --version) and record it
• Use --float 0 (double precision) unless memory is tight

Note that -y trades some affine accuracy for reproducibility — Mattes MI on linear stages is usually more accurate but nondeterministic in ITK's implementation.

ANTsPy equivalents

If the user is in Python, every workflow has an ANTsPy equivalent. Key mapping:

Important ANTsPy gotcha: for deformable-only transform types (SyNOnly, BSplineSyNOnly, time-varying), the default initial transform is identity, not center-of-mass alignment. Pass initial_transform='Identity' explicitly only when you mean it.

Common pitfalls (red-flag triggers)

If you see any of these in the user's setup, stop and address before running anything:

• "Segmentation 11" error → fixed and moving aren't in the same physical space sense; check headers with PrintHeader or fslhd. Don't proceed until aligned to same orientation.
• Memory blowing past 80% → SyN on >1mm³ data with full-precision is the usual culprit. Switch to --float 1, reduce SyN iterations, or use BSplineSyN instead.
• User has a lesion / tumor / resection cavity → the lesion mask must NOT be in the moving image without mitigation. Either flip the registration direction (template as moving, subject as fixed, then invert) or pass the lesion as a cost-function mask via -x on the appropriate image.
• Registering label maps directly → never. Always register the underlying intensity image, then apply the transform to the label map with NearestNeighbor or GenericLabel interpolation.
• Cross-modal with CC metric → wrong; CC assumes intensity correlation. Use MI or Mattes for cross-modal.
• No initial transform on very misaligned images → antsRegistration will start from identity and waste 80% of compute trying to find the brain. Always include --initial-moving-transform [fixed,moving,1] (the 1 means center-of-mass) for first-time pairs.

Files in this skill