preprocess-imaging git:20260802.db8f868A

Immutable. This exact content is served forever at /api/v1/blob/df11b628031f7713.

---
name: preprocess-imaging
description: >
  Design or audit the data-preparation stage of a medical-imaging model — DICOM/NIfTI intake,
  resampling and intensity normalisation, and the augmentation plan — so the pipeline is leakage-safe
  before model-scaffold builds the training repo. Emits a declarative preprocessing manifest and a
  deterministic data-stage leakage gate that catches the leaks a split table cannot see: a
  dataset-level normaliser fit on non-train data, any data-fitted transform run before the split, and
  the same patient's slices crossing splits. Integrates MONAI / TorchIO transforms; it does not
  reimplement them, and it never runs preprocessing on real patient data.
triggers: preprocess imaging, preprocessing, data pipeline, DICOM, NIfTI, resample, spacing, intensity normalization, intensity normalisation, windowing, HU window, z-score, histogram matching, augmentation, augmentation plan, TorchIO, MONAI transforms, data leakage, normalization leakage, preprocessing manifest, fit on train, per-image normalization, patient-level split, slice-level leakage, imaging data prep
tools: Read, Write, Edit, Bash, Grep, Glob
model: inherit
---

# Preprocess-Imaging Skill

## Purpose

This skill designs and audits the **data-preparation stage** of a medical-imaging model — the stage
*before* a training repo is built — and proves it is **leakage-safe by construction**. Data leakage
enters one step earlier than the split table can see: a normaliser fit on the whole dataset, a
data-fitted transform run before the split exists, or a patient whose slices land in more than one
partition. Each silently inflates every downstream metric (Kapoor & Narayanan, *Patterns* 2023;
Varoquaux & Cheplygina, *npj Digit Med* 2022; CLAIM 2024 data items).

It is the **missing first link** in the lane: **preprocess-imaging (prepare + audit)** →
`/model-scaffold` (build) → `/model-validation` (validate the split) → `/model-evaluation` +
`/analyze-stats` (metrics) → `/write-paper` + `/check-reporting` (publish). It **integrates**
MONAI / TorchIO transforms (referenced in the emitted plan); it does not reimplement them, and it
never executes preprocessing on real patient data.

## When to use
- You have a data manifest (one row per image/slice with a patient/subject ID) and want a
  leakage-safe preprocessing plan + a machine-checkable manifest before scaffolding a model.
- You want to audit an existing preprocessing pipeline for data-stage leakage.

## When NOT to use
- Auditing the train/val/test split table itself → `/model-validation` (split-leakage gate).
- Building the training repo / model code → `/model-scaffold` (it consumes this manifest).
- Choosing the architecture → `/architecture-zoo`.
- Held-out metrics / calibration → `/model-evaluation` then `/analyze-stats`.
- Reimplementing MONAI / TorchIO transforms → out of scope (this skill wires and audits them).

## Workflow

### Phase 1 — Inventory the data and the intended steps
Collect: modality (CT / MR / X-ray / US / path), the data manifest (one row per image/slice with a
`patient_id`), the intended resample spacing, the intensity transform (fixed HU window vs a fitted
z-score / min-max / histogram match), and the augmentation plan. See
[`references/preprocessing_guide.md`](references/preprocessing_guide.md) for modality-aware guidance
(what normalisation is standard per modality, which augmentations preserve vs break physiology).

### Phase 2 — Decide fit scope and order (the leakage-safe rules)
- **Fit dataset-level normalisation on the training split only** — never on all/full/test.
- **Run any data-fitted transform AFTER the split** — before the split there is no train/test
  distinction, so the fit spans partitions.
- **Prefer per-image (per-sample) normalisation** where clinically appropriate: it uses only that
  image's own statistics and is leakage-free even before the split.
- **Keep augmentation train-only** — augmenting val/test folds undisclosed test-time augmentation
  into the reported metric.
- **Split at the patient level**, then map slices to their patient's split (never split slices).

### Phase 3 — Emit the preprocessing manifest
Write a declarative JSON manifest that `model-scaffold` consumes and the gate checks:

```json
{
  "split_seed": 42,
  "transforms": [
    {"name": "hu_window", "type": "clip", "fit_scope": "none", "stage": "before_split"},
    {"name": "train_zscore", "type": "standardize", "fit_scope": "train", "stage": "after_split"},
    {"name": "flip_rotate", "type": "augmentation", "stage": "after_split", "applies_to": ["train"]}
  ],
  "split_assignment": [
    {"patient_id": "P001", "unit_id": "P001_s1", "split": "train"}
  ]
}
```

`fit_scope`: `train` (OK) · `all`/`full`/`dataset`/`test` (leak) · `sample`/`per_image`/`none`/`fixed`
(not data-fitted, leakage-free). `stage`: `before_split` / `after_split`.

**Declare the fit scope of resampling too.** A target spacing you chose in advance is fixed and
never leaks (`fit_scope: fixed`). A target *derived* from the cohort does: nnU-Net sets its target
spacing from a percentile of the dataset fingerprint, so a resample fitted over every case carries
held-out geometry into the training grid exactly as an intensity statistic would. Which one you
have is decided by the fingerprint's scope, not by the word "resample".

### Phase 4 — Gate the manifest (deterministic)
```bash
python3 scripts/check_preprocessing_leakage.py --manifest preprocessing_manifest.json --strict
```

That gate asks whether a transform was fit on the right **scope**. Before an *inference* run on a
cohort the model was not trained on, ask the other question — is that cohort in the intensity
**domain** the trained normaliser assumes?

```bash
python3 scripts/check_normalizer_domain.py \
    --profile eda/<cohort>_profile.json \
    --contract work/nnUNet_results/.../plans.json \
    --splits external_mri --out qc/normalizer_domain.json --strict
```
Verdicts: `PREPROCESS_BEFORE_SPLIT`, `NORMALIZATION_LEAKAGE`, `PATIENT_CROSS_SPLIT` (Major);
`AUGMENTATION_ON_EVAL`, `UNSPECIFIED_FIT_SCOPE`, `MISSING_SEED` (Minor). The verdict is reproduced
by set arithmetic + rule on the manifest, never asserted from prose. A green gate is a precondition
for handing the manifest to `/model-scaffold`.

## Integration
- **Feeds `/model-scaffold`** — the audited manifest is the scaffold's preprocessing input; its
  `split_assignment` is the same patient-level split `/model-validation` later re-verifies.
- **`/self-review`** `model_development` probe audits data-stage leakage in a finished manuscript;
  this skill *produces* the leakage-safe pipeline it looks for.
- **`/check-reporting`** — the manifest documents the CLAIM 2024 / TRIPOD+AI data-preprocessing items.

## Anti-Hallucination

- **Never fabricate image statistics, patient IDs, or split assignments.** Every value in the
  manifest comes from the real data manifest and the researcher's declared pipeline — never invented.
  This skill designs and audits the plan; it does not run preprocessing on real patient data or
  synthesise the images it describes.
- **Never report a preprocessing-audit "pass" without running `check_preprocessing_leakage.py`.** The
  leakage verdict is reproduced deterministically (rule + set arithmetic on the manifest), never
  asserted from prose.
- **Never label a dataset-fitted transform as per-sample to clear the gate.** The manifest's
  `type` / `fit_scope` / `stage` must describe what the code actually does; a mislabelled transform
  hides a real leak the gate would otherwise catch.
- **Integrate, don't reimplement.** Reference MONAI / TorchIO transforms; do not write a new
  normalisation/resampling implementation or claim results for one.

## Reproducible challenge
`scripts/check_normalizer_domain_challenge/` ships a synthetic profile/contract triple: a cohort in
the contract's own domain that must come back **clean** (the false-positive guard), an arbitrary-unit
cohort that must raise a Major, and an unreadable contract that must **refuse** rather than pass.

`scripts/check_preprocessing_leakage_challenge/` ships a synthetic leak/clean manifest pair with a
network-free `verify.sh` wired into the skill's validation commands.