T1Prep: Instructions file for Claude Code

CLAUDE.md – T1Prep Project

For full contributor documentation see Agents.md.

Sub-Agent Routing Rules

• Use sub-agents freely: delegate self-contained work (exploration, research, porting or reviewing separate modules, long validation runs) to sub-agents, and run independent ones in parallel.
• Dependencies: a task that needs another task's output waits for it.
• Reviews: security, performance and style checks are independent and may run in parallel; merge their findings before changing code.
• No shared state: parallel agents never edit the same files or share a build directory -- give each its own files (or a git worktree) and its own build/scratch directory.

Background Execution Rules

Run in background automatically:

• Web research and documentation lookups
• Codebase exploration and analysis
• Security audits and performance profiling
• Any task where results aren't immediately needed
• Research or analysis tasks (not file modifications)
• Results aren't blocking your current work

Overview

T1Prep is a Python-based pipeline for preprocessing and segmenting T1-weighted MRI data (bias-field correction, segmentation, lesion detection, cortical surface reconstruction, CAT12 integration). Code lives in src/, helper/dev scripts in scripts/, Flask web UI in src/t1prep/webui/.

Entry points are installed into the environment's bin/ (the canonical way to run T1Prep): T1Prep (bash orchestrator), PyCAT (symlink to T1Prep; same CLI, PyCAT startup banner), t1prep-ui, t1prep-run (Python single-subject), CAT_SurfView, CAT_VolView, CAT_PlotHistogram, t1prep-make-apps, t1prep-download-models, t1prep-bbreg. The scripts/ folder is a source-tree/dev fallback and should not be put on PATH.

Key Commands

# CLI (from <venv>/bin on PATH; or ./scripts/T1Prep in a source checkout)
T1Prep --help
T1Prep --out-dir /tmp/out file.nii.gz

# Python API
from t1prep import run_t1prep

# Web UI
t1prep-ui --port 5050

# Sanity check
python -m compileall src

# Tests
pytest

# Voxel-wise volume differences to the first image (cat_stat_diff via CAT_VolCalc)
CAT_VolDiff [--rel] [--glob] tp1.nii.gz tp2.nii.gz

# Recalibrate the QA rating bounds from a processed BrainWeb Phantom set
python scripts/qa_calibrate.py /path/to/BWP/report

# Networks (src/t1prep/nn): backend per run, export (re)trained weights as safetensors
T1Prep --nn-backend tinygrad ...          # default torch (nn_backend in the defaults file, T1PREP_NN_BACKEND); tinygrad: pip install 'T1Prep[tinygrad]'
python -m t1prep.nn.convert model.pth --out-dir DIR

# Histogram of volumes, surfaces or text data (CAT12's cat_plot_histogram.m)
CAT_PlotHistogram [--dist kernel|gaussian_kde|none|normal|...] [--mean] [--ridgeline] [--save PREFIX] file...

# Longitudinal: rigid realignment, then the low-dimensional ageing deformation
./scripts/process_longitudinal.sh --long-model ageing tp1.nii.gz tp2.nii.gz
./scripts/warp_longitudinal.sh --inputs tp1.nii.gz tp2.nii.gz --out-dir DIR
./scripts/modulate_longitudinal.sh --mri-dirs D1 D2 --names tp1 tp2 --out-dir DIR

# Score the spherical registration against the Mindboggle-101 manual labels
python evaluation/tools/eval_mindboggle.py project --mindboggle DIR... --t1prep DIR --work DIR
python evaluation/tools/eval_mindboggle.py dice --work DIR --protocol both

# Accuracy against the simulated phantom (manual, ~15 min): run, then check the pins
make phantom                     # = eval_phantom.py run + check in /tmp/T1Prep_phantom
make phantom-check PHANTOM_DIR=DIR
make phantom-pin                 # re-pin after an intended change (two devices, ~30 min)
make phantom-wmh                 # WMH over the 14 simulations in evaluation/data/phantom (~1 h)
python evaluation/tools/fit_wmh_calibration.py fit --work DIR  # refit WMH_CALIBRATION (after dump)