bidsgate 0.1.0__tar.gz

bidsgate-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cedric Conday
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bidsgate-0.1.0/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: bidsgate
+Version: 0.1.0
+Summary: Recovery gate for neuroimaging pipelines: inject known lesions or atrophy into real BIDS data, run any BIDS app, score what it recovered.
+Author: Cedric Conday
+License: MIT
+Project-URL: Homepage, https://github.com/CedricConday/bidsgate
+Keywords: BIDS,neuroimaging,validation,synthetic,ground truth,MRI,lesion,atrophy
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Dist: nibabel>=5
+Requires-Dist: pandas>=2
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# bidsgate
+
+**A recovery gate for neuroimaging pipelines.** Inject a known truth into real BIDS data,
+run any BIDS app on the result, and score what it recovered. Every pipeline claims to
+segment lesions or measure atrophy; this is the test that says by how much.
+
+```bash
+pip install bidsgate
+bidsgate inject-lesions /data/bids --out /data/derivatives/bidsgate-lesions
+# run your lesion segmenter on /data/derivatives/bidsgate-lesions
+bidsgate score-lesions --truth /data/derivatives/bidsgate-lesions \
+    --pred "/data/derivatives/mytool/{subject}/{base}_seg.nii.gz" --pipeline mytool
+```
+
+> Nothing in this repository is evidence about any disease. It is a test of software:
+> the injected lesions and volume changes are synthetic, and the only claim made is
+> about what a given pipeline recovered from them.
+
+## Why
+
+There is no public ground truth for most of what neuroimaging pipelines report. Lesion
+segmenters are compared to expert masks that disagree with each other; morphometry tools
+report volumes nobody can check; when a new release shifts the numbers, the changelog
+says "improved" and the user has no way to tell. bidsgate gives every pipeline the same
+question: here is a scan with a known change in it, what did you find?
+
+This generalises the synthetic backtest of [lesiontrack](https://github.com/CedricConday/lesiontrack),
+where injecting known lesion expansions showed a published method recovering a third of
+the injected change and firing on noise. The same discipline applies to any pipeline.
+
+## First result: LST-AI v2 on a healthy control
+
+[LST-AI](https://github.com/CompImg/LST-AI) v2.0.0rc1 (CPU image, fast mode) was run on
+OpenNeuro [ds007908](https://openneuro.org/datasets/ds007908) control sub-9000 after
+twelve lesions (30 to 1500 mm3) were injected into its T1w and FLAIR. Scorecard and JSON
+are in `results/lst-ai-v2/`.
+
+| | |
+|---|---|
+| Lesions detected | 9 of 12 |
+| Dice | 0.75 |
+| Volume ratio (predicted / injected) | 1.15 |
+| Predicted components farther than 2 mm from any injected lesion | 16, totalling 733 mm3 |
+
+What the per-lesion table shows: every lesion in the cerebral white matter was found,
+down to 26 mm3, with overlap fractions of 0.76 to 1.0. The three misses (29, 194 and
+611 mm3) are the three lesions the placement put lowest in the brain, at cerebellum and
+brainstem level, where this subject's own FLAIR is already brightest. Whether that is a
+weakness of the model or a weakness of injecting supratentorial-looking lesions into
+infratentorial tissue is exactly the question the gate raises and a per-region breakdown
+would answer; it is on the list below.
+
+The 16 extra components on a healthy control are not necessarily wrong: a control can
+carry real incidental white-matter hyperintensities, and the gate cannot tell those from
+false positives. It can only say how much the pipeline reported beyond what was injected.
+
+The remaining controls of ds007908 are being run and the table will be extended. Two of
+the eight were refused by the input checks: sub-9005's FLAIR is on a different grid from
+its T1w, and sub-9006's FLAIR shares the grid but not the affine (17 mm apart), so it was
+never co-registered. A shape-only check had accepted it. The gate refusing an input is a
+result too.
+
+## Injections
+
+**Lesions** (`inject-lesions`): ellipsoidal lesions with soft edges, placed inside a
+white-matter estimate, FLAIR-hyperintense and T1w-hypointense relative to the median of
+that estimate (gain 0.6 and −0.2 at the core by default). Sizes cycle through 30, 80,
+200, 600 and 1500 mm3 so that the scorecard shows a detection floor by lesion size. No two
+lesions touch, and every lesion lies deeper inside the brain than its own longest axis.
+
+The brain mask is estimated from the T1w by morphology (tissue above an Otsu threshold,
+eroded by 8 mm to cut scalp, optic nerves and cord, every remaining piece over 100 ml
+grown back inside tissue, ventricles filled) and must land between 800 and 2000 ml or
+the subject is refused. Pass your own mask with `--mask "{subject}_brainmask.nii.gz"`
+if you have a better one. White matter is bright T1w tissue more than 6 mm inside that
+mask whose FLAIR is within 0.6 to 1.4 of the FLAIR white-matter median, which excludes
+CSF and anything outside the FLAIR field of view.
+
+The soft field is 0.5 on the ellipsoid surface and falls off over 1 mm on either side,
+so the truth label (the voxels inside the surface) is exactly what a half-maximum
+segmenter would recover; a perfect segmenter scores Dice 1 and volume ratio 1, not 2.
+The truth is the label map plus a JSON with every lesion's centre, axes, label volume,
+nominal volume and voxel count, the seed, the contrasts and the brain volume.
+
+T1w and FLAIR must share grid and affine; a subject that does not is skipped with a
+message and nothing is written for it. Every image gets its own seed (a hash of its name
+mixed with `--seed`), so `--subject` selection and dataset growth do not change what a
+subject receives, and run or acquisition entities are kept in the derivative names.
+
+**Atrophy** (`inject-atrophy`): a smooth radial contraction of the brain by a known volume
+factor (default 0.95, five percent loss) about its centroid, fading to identity over 12 mm
+outside the brain mask. The same mask estimate and `--mask` option apply. The truth JSON
+records the factor and the brain volume before and after as measured on the mask itself.
+Note that the skull contracts with the brain inside the falloff zone, so a tool that
+normalises to intracranial volume will see less change than was injected; compare raw
+volumes.
+
+Both write a BIDS derivative dataset: `dataset_description.json`, the modified images with
+their sidecars carrying what was done, and the truth files next to them.
+
+## Scoring
+
+`score-lesions` compares a predicted mask (binary or probabilistic, thresholded at 0.5)
+with the truth, which must be on the same grid and affine: Dice, lesion-wise sensitivity
+(a lesion is detected when any predicted voxel overlaps it), sensitivity by size bin, and
+the predicted-over-injected volume ratio. False positives are every predicted voxel
+farther than 2 mm (`--fp-margin`) from any injected lesion, reported as volume and as
+18-connected components, so over-segmentation that happens to touch a true lesion still
+counts. `score-atrophy` takes the volumes your tool reported before and after injection
+and gives recovery: measured change over injected change, 1.0 being exact.
+
+Both write JSON and a single-file HTML scorecard.
+
+## Limits, stated plainly
+
+* Synthetic lesions are not real lesions. They have the contrast and shape the spec
+  says, no more; a pipeline that finds them may still miss real ones, and a pipeline
+  that misses them has a problem it cannot blame on pathology.
+* The white-matter estimate is intensity-based, not a segmentation, and it does not
+  know cerebrum from cerebellum. Lesions land anywhere in deep bright tissue; a
+  per-region breakdown (and a `--region` mask) is the next scoring feature.
+* On real subjects, extra predicted components may be genuine findings. The gate
+  reports them; it cannot judge them.
+* Atrophy is global and radial. Regional atrophy needs a region mask; that is the next
+  injector.
+* Activation injection for fMRI is not built yet.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest -q
+```
+
+The tests build a head-shaped phantom (brain, skull gap, scalp) and check that the brain
+estimate excludes the scalp, keeps both hemispheres across a fissure and fills
+ventricles; that a slab of tissue with no plausible brain volume is refused; that injected
+lesions have the recorded volumes and contrasts, sit entirely in white matter and never
+touch; that the half-maximum set of the added contrast is the label; that a perfect
+prediction scores Dice 1, a slab through a lesion counts as a false positive and a
+shifted affine is refused; that atrophy shrinks the brain by the requested factor; that
+run entities survive into derivative names with distinct seeds; that a subject with a
+mismatched FLAIR leaves no partial output; and that the CLI runs end to end.
+
+`scripts/` holds the LST-AI runner used for the result above (`run_lst_ai.sh`, detached
+Docker container per subject; `overnight_demo.sh` for the whole cohort).
+
+MIT. Written by Cedric Conday with Claude (Anthropic) as coding partner.

bidsgate-0.1.0/README.md

@@ -0,0 +1,148 @@
+# bidsgate
+
+**A recovery gate for neuroimaging pipelines.** Inject a known truth into real BIDS data,
+run any BIDS app on the result, and score what it recovered. Every pipeline claims to
+segment lesions or measure atrophy; this is the test that says by how much.
+
+```bash
+pip install bidsgate
+bidsgate inject-lesions /data/bids --out /data/derivatives/bidsgate-lesions
+# run your lesion segmenter on /data/derivatives/bidsgate-lesions
+bidsgate score-lesions --truth /data/derivatives/bidsgate-lesions \
+    --pred "/data/derivatives/mytool/{subject}/{base}_seg.nii.gz" --pipeline mytool
+```
+
+> Nothing in this repository is evidence about any disease. It is a test of software:
+> the injected lesions and volume changes are synthetic, and the only claim made is
+> about what a given pipeline recovered from them.
+
+## Why
+
+There is no public ground truth for most of what neuroimaging pipelines report. Lesion
+segmenters are compared to expert masks that disagree with each other; morphometry tools
+report volumes nobody can check; when a new release shifts the numbers, the changelog
+says "improved" and the user has no way to tell. bidsgate gives every pipeline the same
+question: here is a scan with a known change in it, what did you find?
+
+This generalises the synthetic backtest of [lesiontrack](https://github.com/CedricConday/lesiontrack),
+where injecting known lesion expansions showed a published method recovering a third of
+the injected change and firing on noise. The same discipline applies to any pipeline.
+
+## First result: LST-AI v2 on a healthy control
+
+[LST-AI](https://github.com/CompImg/LST-AI) v2.0.0rc1 (CPU image, fast mode) was run on
+OpenNeuro [ds007908](https://openneuro.org/datasets/ds007908) control sub-9000 after
+twelve lesions (30 to 1500 mm3) were injected into its T1w and FLAIR. Scorecard and JSON
+are in `results/lst-ai-v2/`.
+
+| | |
+|---|---|
+| Lesions detected | 9 of 12 |
+| Dice | 0.75 |
+| Volume ratio (predicted / injected) | 1.15 |
+| Predicted components farther than 2 mm from any injected lesion | 16, totalling 733 mm3 |
+
+What the per-lesion table shows: every lesion in the cerebral white matter was found,
+down to 26 mm3, with overlap fractions of 0.76 to 1.0. The three misses (29, 194 and
+611 mm3) are the three lesions the placement put lowest in the brain, at cerebellum and
+brainstem level, where this subject's own FLAIR is already brightest. Whether that is a
+weakness of the model or a weakness of injecting supratentorial-looking lesions into
+infratentorial tissue is exactly the question the gate raises and a per-region breakdown
+would answer; it is on the list below.
+
+The 16 extra components on a healthy control are not necessarily wrong: a control can
+carry real incidental white-matter hyperintensities, and the gate cannot tell those from
+false positives. It can only say how much the pipeline reported beyond what was injected.
+
+The remaining controls of ds007908 are being run and the table will be extended. Two of
+the eight were refused by the input checks: sub-9005's FLAIR is on a different grid from
+its T1w, and sub-9006's FLAIR shares the grid but not the affine (17 mm apart), so it was
+never co-registered. A shape-only check had accepted it. The gate refusing an input is a
+result too.
+
+## Injections
+
+**Lesions** (`inject-lesions`): ellipsoidal lesions with soft edges, placed inside a
+white-matter estimate, FLAIR-hyperintense and T1w-hypointense relative to the median of
+that estimate (gain 0.6 and −0.2 at the core by default). Sizes cycle through 30, 80,
+200, 600 and 1500 mm3 so that the scorecard shows a detection floor by lesion size. No two
+lesions touch, and every lesion lies deeper inside the brain than its own longest axis.
+
+The brain mask is estimated from the T1w by morphology (tissue above an Otsu threshold,
+eroded by 8 mm to cut scalp, optic nerves and cord, every remaining piece over 100 ml
+grown back inside tissue, ventricles filled) and must land between 800 and 2000 ml or
+the subject is refused. Pass your own mask with `--mask "{subject}_brainmask.nii.gz"`
+if you have a better one. White matter is bright T1w tissue more than 6 mm inside that
+mask whose FLAIR is within 0.6 to 1.4 of the FLAIR white-matter median, which excludes
+CSF and anything outside the FLAIR field of view.
+
+The soft field is 0.5 on the ellipsoid surface and falls off over 1 mm on either side,
+so the truth label (the voxels inside the surface) is exactly what a half-maximum
+segmenter would recover; a perfect segmenter scores Dice 1 and volume ratio 1, not 2.
+The truth is the label map plus a JSON with every lesion's centre, axes, label volume,
+nominal volume and voxel count, the seed, the contrasts and the brain volume.
+
+T1w and FLAIR must share grid and affine; a subject that does not is skipped with a
+message and nothing is written for it. Every image gets its own seed (a hash of its name
+mixed with `--seed`), so `--subject` selection and dataset growth do not change what a
+subject receives, and run or acquisition entities are kept in the derivative names.
+
+**Atrophy** (`inject-atrophy`): a smooth radial contraction of the brain by a known volume
+factor (default 0.95, five percent loss) about its centroid, fading to identity over 12 mm
+outside the brain mask. The same mask estimate and `--mask` option apply. The truth JSON
+records the factor and the brain volume before and after as measured on the mask itself.
+Note that the skull contracts with the brain inside the falloff zone, so a tool that
+normalises to intracranial volume will see less change than was injected; compare raw
+volumes.
+
+Both write a BIDS derivative dataset: `dataset_description.json`, the modified images with
+their sidecars carrying what was done, and the truth files next to them.
+
+## Scoring
+
+`score-lesions` compares a predicted mask (binary or probabilistic, thresholded at 0.5)
+with the truth, which must be on the same grid and affine: Dice, lesion-wise sensitivity
+(a lesion is detected when any predicted voxel overlaps it), sensitivity by size bin, and
+the predicted-over-injected volume ratio. False positives are every predicted voxel
+farther than 2 mm (`--fp-margin`) from any injected lesion, reported as volume and as
+18-connected components, so over-segmentation that happens to touch a true lesion still
+counts. `score-atrophy` takes the volumes your tool reported before and after injection
+and gives recovery: measured change over injected change, 1.0 being exact.
+
+Both write JSON and a single-file HTML scorecard.
+
+## Limits, stated plainly
+
+* Synthetic lesions are not real lesions. They have the contrast and shape the spec
+  says, no more; a pipeline that finds them may still miss real ones, and a pipeline
+  that misses them has a problem it cannot blame on pathology.
+* The white-matter estimate is intensity-based, not a segmentation, and it does not
+  know cerebrum from cerebellum. Lesions land anywhere in deep bright tissue; a
+  per-region breakdown (and a `--region` mask) is the next scoring feature.
+* On real subjects, extra predicted components may be genuine findings. The gate
+  reports them; it cannot judge them.
+* Atrophy is global and radial. Regional atrophy needs a region mask; that is the next
+  injector.
+* Activation injection for fMRI is not built yet.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest -q
+```
+
+The tests build a head-shaped phantom (brain, skull gap, scalp) and check that the brain
+estimate excludes the scalp, keeps both hemispheres across a fissure and fills
+ventricles; that a slab of tissue with no plausible brain volume is refused; that injected
+lesions have the recorded volumes and contrasts, sit entirely in white matter and never
+touch; that the half-maximum set of the added contrast is the label; that a perfect
+prediction scores Dice 1, a slab through a lesion counts as a false positive and a
+shifted affine is refused; that atrophy shrinks the brain by the requested factor; that
+run entities survive into derivative names with distinct seeds; that a subject with a
+mismatched FLAIR leaves no partial output; and that the CLI runs end to end.
+
+`scripts/` holds the LST-AI runner used for the result above (`run_lst_ai.sh`, detached
+Docker container per subject; `overnight_demo.sh` for the whole cohort).
+
+MIT. Written by Cedric Conday with Claude (Anthropic) as coding partner.

bidsgate-0.1.0/bidsgate/__init__.py

@@ -0,0 +1,8 @@
+"""bidsgate: a recovery gate for neuroimaging pipelines.
+
+Inject a known truth (lesions, atrophy) into real BIDS data, run any BIDS app on
+the result, and score what it recovered. Nothing here is evidence about any
+disease; it is a test of software.
+"""
+
+__version__ = "0.1.0"

bidsgate-0.1.0/bidsgate/bids.py

@@ -0,0 +1,85 @@
+"""Minimal BIDS walking: enough to find anatomical images and write derivatives."""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from . import __version__
+
+ENTITY = re.compile(r"(sub-[A-Za-z0-9]+)(?:_(ses-[A-Za-z0-9]+))?.*_(T1w|FLAIR|T2w)\.nii(\.gz)?$")
+
+
+@dataclass(frozen=True)
+class Anat:
+    subject: str
+    session: str | None
+    suffix: str
+    path: Path
+
+    @property
+    def stem(self) -> str:
+        return self.path.name.split(".")[0]
+
+    @property
+    def base(self) -> str:
+        """The filename with the suffix and extension removed, every entity kept (sub-01_ses-1_run-2)."""
+        return self.stem.removesuffix(f"_{self.suffix}")
+
+
+def find_anat(root: Path, suffix: str = "T1w", subjects: list[str] | None = None) -> list[Anat]:
+    out = []
+    for p in sorted(root.glob("sub-*/**/anat/*.nii*")):
+        m = ENTITY.match(p.name)
+        if not m or m.group(3) != suffix:
+            continue
+        sub, ses = m.group(1), m.group(2)
+        if subjects and sub not in subjects and sub.removeprefix("sub-") not in subjects:
+            continue
+        out.append(Anat(sub, ses, suffix, p))
+    return out
+
+
+def sibling(anat: Anat, suffix: str) -> Path | None:
+    """The same subject/session's image of another suffix, if present."""
+    cand = anat.path.with_name(anat.path.name.replace(f"_{anat.suffix}.", f"_{suffix}."))
+    return cand if cand.exists() else None
+
+
+def derivative_path(out_root: Path, anat: Anat, suffix: str, desc: str | None = None, ext: str = ".nii.gz") -> Path:
+    """Output path that keeps every entity of the source file, so run-1 and run-2 never collide."""
+    d = out_root / anat.subject / (anat.session or "") / "anat"
+    d.mkdir(parents=True, exist_ok=True)
+    name = "_".join([anat.base] + ([f"desc-{desc}"] if desc else []) + [suffix]) + ext
+    return d / name
+
+
+def write_dataset_description(out_root: Path, name: str, source_root: Path, kind: str) -> None:
+    out_root.mkdir(parents=True, exist_ok=True)
+    desc = {
+        "Name": name,
+        "BIDSVersion": "1.9.0",
+        "DatasetType": "derivative",
+        "GeneratedBy": [{"Name": "bidsgate", "Version": __version__, "Description": f"synthetic {kind} injection with known truth"}],
+        "SourceDatasets": [{"URL": str(source_root)}],
+    }
+    with open(out_root / "dataset_description.json", "w") as fh:
+        json.dump(desc, fh, indent=2)
+
+
+def copy_json_sidecar(src_nii: Path, dst_nii: Path, extra: dict) -> None:
+    """Carry the acquisition sidecar over and add what was done."""
+    src = src_nii.with_suffix("").with_suffix(".json") if src_nii.name.endswith(".nii.gz") else src_nii.with_suffix(".json")
+    meta = {}
+    if src.exists():
+        try:
+            with open(src) as fh:
+                meta = json.load(fh)
+        except json.JSONDecodeError:
+            meta = {}
+    meta.update(extra)
+    dst = Path(str(dst_nii).replace(".nii.gz", ".json").replace(".nii", ".json"))
+    with open(dst, "w") as fh:
+        json.dump(meta, fh, indent=2)

bidsgate-0.1.0/bidsgate/cli.py

@@ -0,0 +1,185 @@
+"""bidsgate: inject a known truth into BIDS data, then score what a pipeline recovered."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import zlib
+from pathlib import Path
+
+import pandas as pd
+
+from . import __version__
+from .bids import copy_json_sidecar, derivative_path, find_anat, sibling, write_dataset_description
+from .inject_atrophy import AtrophySpec
+from .inject_atrophy import inject as inject_atrophy
+from .inject_lesions import LesionSpec
+from .inject_lesions import inject as inject_lesions
+from .report import scorecard_atrophy, scorecard_lesions
+from .score import score_atrophy, score_lesions
+
+
+def subject_seed(base: str, seed: int) -> int:
+    """One seed per image, stable under --subject selection and dataset growth."""
+    return zlib.crc32(base.encode()) ^ (seed & 0xFFFFFFFF)
+
+
+def _mask_for(pattern: str | None, anat) -> Path | None:
+    if not pattern:
+        return None
+    p = Path(pattern.format(base=anat.base, subject=anat.subject))
+    if not p.exists():
+        raise SystemExit(f"{anat.base}: brain mask not found at {p}")
+    return p
+
+
+def cmd_inject_lesions(a) -> int:
+    root, out = Path(a.bids), Path(a.out)
+    anats = find_anat(root, "T1w", a.subject)
+    if not anats:
+        raise SystemExit(f"no T1w images under {root}")
+    write_dataset_description(out, "bidsgate lesions", root, "lesion")
+    for anat in anats:
+        flair = sibling(anat, "FLAIR")
+        spec = LesionSpec(n=a.n, seed=subject_seed(anat.base, a.seed), flair_contrast=a.flair_contrast, t1_contrast=a.t1_contrast)
+        out_t1 = derivative_path(out, anat, "T1w")
+        out_fl = derivative_path(out, anat, "FLAIR") if flair else None
+        mask = derivative_path(out, anat, "mask", desc="lesionTruth")
+        truth = derivative_path(out, anat, "truth", desc="lesion", ext=".json")
+        try:
+            t = inject_lesions(anat.path, flair, out_t1, out_fl, mask, truth, spec, _mask_for(a.mask, anat))
+        except ValueError as e:
+            print(f"{anat.base}: skipped: {e}", file=sys.stderr)
+            continue
+        note = {"BidsgateInjection": "lesions", "BidsgateSeed": spec.seed, "BidsgateTruth": truth.name}
+        copy_json_sidecar(anat.path, out_t1, note)
+        if flair and out_fl:
+            copy_json_sidecar(flair, out_fl, note)
+        print(f"{anat.base}: {t['n']} lesions, {t['total_volume_mm3']:.0f} mm3, {'T1w+FLAIR' if flair else 'T1w only'} -> {out_t1.parent}")
+    print(f"derivative dataset written to {out}; run your pipeline on it, then `bidsgate score-lesions`")
+    return 0
+
+
+def cmd_inject_atrophy(a) -> int:
+    root, out = Path(a.bids), Path(a.out)
+    anats = find_anat(root, "T1w", a.subject)
+    if not anats:
+        raise SystemExit(f"no T1w images under {root}")
+    write_dataset_description(out, "bidsgate atrophy", root, "atrophy")
+    for anat in anats:
+        flair = sibling(anat, "FLAIR")
+        out_t1 = derivative_path(out, anat, "T1w")
+        out_fl = derivative_path(out, anat, "FLAIR") if flair else None
+        truth = derivative_path(out, anat, "truth", desc="atrophy", ext=".json")
+        try:
+            t = inject_atrophy(anat.path, flair, out_t1, out_fl, truth, AtrophySpec(volume_factor=a.factor, falloff_mm=a.falloff),
+                               _mask_for(a.mask, anat))
+        except ValueError as e:
+            print(f"{anat.base}: skipped: {e}", file=sys.stderr)
+            continue
+        copy_json_sidecar(anat.path, out_t1, {"BidsgateInjection": "atrophy", "BidsgateVolumeFactor": a.factor, "BidsgateTruth": truth.name})
+        if flair and out_fl:
+            copy_json_sidecar(flair, out_fl, {"BidsgateInjection": "atrophy", "BidsgateVolumeFactor": a.factor})
+        print(f"{anat.base}: brain {t['brain_volume_mm3_before']/1000:.0f} ml -> factor {a.factor} (measured on the mask: {t['brain_volume_mm3_after_measured']/t['brain_volume_mm3_before']:.3f})")
+    print(f"derivative dataset written to {out}; run your morphometry on {root} and on {out}, then `bidsgate score-atrophy`")
+    return 0
+
+
+def cmd_score_lesions(a) -> int:
+    truth_root = Path(a.truth)
+    results = []
+    for truth_json in sorted(truth_root.glob("sub-*/**/anat/*desc-lesion_truth.json")):
+        mask = Path(str(truth_json).replace("desc-lesion_truth.json", "desc-lesionTruth_mask.nii.gz"))
+        base = truth_json.name.replace("_desc-lesion_truth.json", "")
+        pred = Path(a.pred.format(base=base, subject=base.split("_")[0]))
+        if not pred.exists():
+            print(f"{base}: prediction not found at {pred}", file=sys.stderr)
+            continue
+        s = score_lesions(truth_json, mask, pred, a.threshold, a.fp_margin)
+        results.append({"subject": base, "score": s})
+        print(f"{base}: Dice {s['dice']:.2f}  detected {s['detected']}/{s['lesions']}  FP {s['false_positive_components']}  volume ratio {s['volume_ratio']:.2f}")
+    if not results:
+        raise SystemExit("nothing scored")
+    out = Path(a.out)
+    out.mkdir(parents=True, exist_ok=True)
+    with open(out / "scores_lesions.json", "w") as fh:
+        json.dump({"pipeline": a.pipeline, "results": results}, fh, indent=2)
+    page = scorecard_lesions(results, a.pipeline, out / "scorecard_lesions.html")
+    print(f"scorecard: {page}")
+    return 0
+
+
+def cmd_score_atrophy(a) -> int:
+    """Volumes come from the user's tool as a TSV: subject, volume_before_mm3, volume_after_mm3."""
+    truth_root = Path(a.truth)
+    vols = pd.read_csv(a.volumes, sep="\t")
+    results = []
+    for _, row in vols.iterrows():
+        base = str(row["subject"])
+        hits = sorted(truth_root.glob(f"{base.split('_')[0]}/**/anat/{base}_desc-atrophy_truth.json"))
+        if not hits:
+            print(f"{base}: no truth found (the subject column must be the full base, e.g. sub-01_ses-1)", file=sys.stderr)
+            continue
+        if len(hits) > 1:
+            raise SystemExit(f"{base}: {len(hits)} truth files match: " + ", ".join(str(h) for h in hits))
+        s = score_atrophy(hits[0], float(row["volume_before_mm3"]), float(row["volume_after_mm3"]))
+        results.append({"subject": base, "score": s})
+        print(f"{base}: injected {s['injected_change_pct']:+.1f}%  measured {s['measured_change_pct']:+.1f}%  recovery {s['recovery']:.2f}")
+    if not results:
+        raise SystemExit("nothing scored")
+    out = Path(a.out)
+    out.mkdir(parents=True, exist_ok=True)
+    with open(out / "scores_atrophy.json", "w") as fh:
+        json.dump({"pipeline": a.pipeline, "results": results}, fh, indent=2)
+    print(f"scorecard: {scorecard_atrophy(results, a.pipeline, out / 'scorecard_atrophy.html')}")
+    return 0
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(prog="bidsgate", description=__doc__)
+    ap.add_argument("--version", action="version", version=f"bidsgate {__version__}")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    p = sub.add_parser("inject-lesions", help="write a derivative dataset with synthetic lesions and their truth")
+    p.add_argument("bids")
+    p.add_argument("--out", required=True)
+    p.add_argument("--subject", action="append", help="restrict to these subjects (repeatable)")
+    p.add_argument("--n", type=int, default=12, help="lesions per subject")
+    p.add_argument("--seed", type=int, default=0, help="mixed with a hash of each image's name, so every subject gets its own stable seed")
+    p.add_argument("--mask", help="brain-mask path pattern with {subject} or {base}; default is a morphological estimate from the T1w")
+    p.add_argument("--flair-contrast", type=float, default=0.6, help="FLAIR gain over local white matter at the core")
+    p.add_argument("--t1-contrast", type=float, default=-0.2, help="T1w change over local white matter at the core")
+    p.set_defaults(func=cmd_inject_lesions)
+
+    p = sub.add_parser("inject-atrophy", help="write a derivative dataset with a known brain-volume change")
+    p.add_argument("bids")
+    p.add_argument("--out", required=True)
+    p.add_argument("--subject", action="append")
+    p.add_argument("--factor", type=float, default=0.95, help="brain volume factor, 0.95 = 5 %% loss")
+    p.add_argument("--mask", help="brain-mask path pattern with {subject} or {base}; default is a morphological estimate from the T1w")
+    p.add_argument("--falloff", type=float, default=12.0, help="mm over which the deformation fades outside the brain")
+    p.set_defaults(func=cmd_inject_atrophy)
+
+    p = sub.add_parser("score-lesions", help="score predicted lesion masks against the injected truth")
+    p.add_argument("--truth", required=True, help="the inject-lesions output directory")
+    p.add_argument("--pred", required=True, help="path pattern with {base} or {subject}, e.g. derivatives/lst/{subject}/{base}_seg.nii.gz")
+    p.add_argument("--pipeline", required=True, help="name for the scorecard")
+    p.add_argument("--threshold", type=float, default=0.5)
+    p.add_argument("--fp-margin", type=float, default=2.0, help="mm from a truth lesion beyond which predicted voxels count as false positive")
+    p.add_argument("--out", default="bidsgate-scores")
+    p.set_defaults(func=cmd_score_lesions)
+
+    p = sub.add_parser("score-atrophy", help="score a tool's reported volumes against the injected change")
+    p.add_argument("--truth", required=True)
+    p.add_argument("--volumes", required=True, help="TSV: subject, volume_before_mm3, volume_after_mm3")
+    p.add_argument("--pipeline", required=True)
+    p.add_argument("--out", default="bidsgate-scores")
+    p.set_defaults(func=cmd_score_atrophy)
+
+    a = ap.parse_args(argv)
+    return a.func(a)
+
+
+if __name__ == "__main__":
+    sys.exit(main())