bidsgate 0.1.0__py3-none-any.whl

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/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/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())

bidsgate/inject_atrophy.py

@@ -0,0 +1,89 @@
+"""Shrink the brain by a known factor to create a ground-truth volume change.
+
+A smooth radial contraction about the brain's centroid, uniform inside the
+brain mask and fading to identity over ``falloff_mm`` outside it, is
+applied to the T1w (and FLAIR when present). The brain's volume changes by
+exactly the requested factor inside the uniform region, so any morphometry
+tool's reported total brain volume can be checked against the truth.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+import nibabel as nib
+import numpy as np
+from scipy import ndimage as ndi
+
+from .inject_lesions import _float_header, estimate_brain
+
+
+@dataclass
+class AtrophySpec:
+    volume_factor: float = 0.95  # 0.95 = 5 % brain volume loss
+    falloff_mm: float = 12.0
+    seed: int = 0
+
+
+def _warp(image: np.ndarray, disp: np.ndarray, order: int, cval: float = 0.0) -> np.ndarray:
+    grids = np.indices(image.shape, dtype=np.float32)
+    return ndi.map_coordinates(image, grids + disp, order=order, mode="constant", cval=cval)
+
+
+def displacement(shape: tuple, zooms: tuple, brain: np.ndarray, factor: float, falloff_mm: float) -> np.ndarray:
+    """Sampling displacement (3, X, Y, Z): output(x) = input(x + u(x)).
+
+    Inside the brain the map is a radial scaling by ``factor ** (1/3)`` about
+    the centroid; a shrunk brain samples from farther out, so u points away
+    from the centre. The weight fades to zero over ``falloff_mm`` outside.
+    """
+    lam = factor ** (1.0 / 3.0)
+    c = np.array(ndi.center_of_mass(brain), np.float32)
+    grids = np.indices(shape, dtype=np.float32)
+    d = grids - c[:, None, None, None]
+    dist_out_mm = ndi.distance_transform_edt(~brain, sampling=zooms[:3]).astype(np.float32)
+    w = np.clip(1.0 - dist_out_mm / max(falloff_mm, 1e-3), 0.0, 1.0)
+    w[brain] = 1.0
+    # output(x) = input(c + (x - c) / lam): points inside map outward for lam < 1.
+    # A linear scaling about the centroid is the same map in voxel and in mm space.
+    return d * ((1.0 / lam - 1.0) * w)[None]
+
+
+def inject(t1_path: Path, flair_path: Path | None, out_t1: Path, out_flair: Path | None,
+           out_truth: Path, spec: AtrophySpec, mask_path: Path | None = None) -> dict:
+    """Write the contracted T1w (and FLAIR) and the truth JSON; inputs are checked before anything is written."""
+    t1_img = nib.load(t1_path)
+    t1 = np.asarray(t1_img.dataobj, dtype=np.float32)
+    zooms = t1_img.header.get_zooms()
+    fl_img = fl = None
+    if flair_path is not None and out_flair is not None:
+        fl_img = nib.load(flair_path)
+        if fl_img.shape != t1_img.shape or not np.allclose(fl_img.affine, t1_img.affine, atol=1e-3):
+            raise ValueError(f"FLAIR grid {fl_img.shape} differs from T1w {t1_img.shape} (or the affines differ)")
+        fl = np.asarray(fl_img.dataobj, dtype=np.float32)
+    if mask_path is not None:
+        m_img = nib.load(mask_path)
+        if m_img.shape != t1_img.shape:
+            raise ValueError(f"brain mask grid {m_img.shape} differs from T1w {t1_img.shape}")
+        brain = np.asarray(m_img.dataobj) > 0
+    else:
+        brain = estimate_brain(t1, zooms)
+    disp = displacement(t1.shape, zooms, brain, spec.volume_factor, spec.falloff_mm)
+    nib.save(nib.Nifti1Image(_warp(t1, disp, 1).astype(np.float32), t1_img.affine, _float_header(t1_img)), out_t1)
+    if fl is not None:
+        nib.save(nib.Nifti1Image(_warp(fl, disp, 1).astype(np.float32), fl_img.affine, _float_header(fl_img)), out_flair)
+    voxel_mm3 = float(np.prod(zooms[:3]))
+    brain_after = _warp(brain.astype(np.float32), disp, 1) >= 0.5
+    truth = {
+        "kind": "atrophy", "seed": spec.seed, "volume_factor": spec.volume_factor,
+        "falloff_mm": spec.falloff_mm,
+        "brain_mask": "given" if mask_path is not None else "estimated",
+        "brain_volume_mm3_before": float(brain.sum() * voxel_mm3),
+        "brain_volume_mm3_after_measured": float(brain_after.sum() * voxel_mm3),
+        "voxel_mm": [float(z) for z in zooms[:3]],
+    }
+    with open(out_truth, "w") as fh:
+        json.dump(truth, fh, indent=2)
+    return truth

bidsgate/inject_lesions.py

@@ -0,0 +1,243 @@
+"""Insert synthetic white-matter lesions with a known mask into T1w and FLAIR images.
+
+The lesions are ellipsoids with soft edges, placed inside a white-matter
+estimate derived from the subject's own T1w and FLAIR (bright T1w tissue
+deep inside a morphological brain mask, or inside a mask you supply), given
+FLAIR hyperintensity and T1w hypointensity relative to the median of that
+white-matter estimate. Sizes, count, contrasts and the random seed
+are recorded next to the mask, so the truth is exact and reproducible.
+
+This is a test of software, not a model of pathology: the point is that a
+segmenter's recovery of these lesions is measurable, not that they look
+like any particular disease.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import nibabel as nib
+import numpy as np
+from scipy import ndimage as ndi
+from scipy.special import erf
+
+
+@dataclass
+class LesionSpec:
+    n: int = 12
+    volume_mm3: tuple = (30.0, 80.0, 200.0, 600.0, 1500.0)  # cycled, then shuffled
+    flair_contrast: float = 0.6  # FLAIR gain over the white-matter median at the core
+    t1_contrast: float = -0.2  # T1w change over the white-matter median at the core
+    edge_mm: float = 1.0  # erf edge width, centred on the surface
+    elongation: tuple = (1.0, 2.0)  # axis ratio range
+    seed: int = 0
+    min_gap_mm: float = 6.0  # between lesion surfaces
+    extra: dict = field(default_factory=dict)
+
+
+def _otsu(x: np.ndarray) -> float:
+    hist, edges = np.histogram(x, bins=256)
+    mids = 0.5 * (edges[:-1] + edges[1:])
+    w1 = np.cumsum(hist).astype(float)
+    w2 = w1[-1] - w1
+    hm = np.cumsum(hist * mids)
+    m1 = hm / np.maximum(w1, 1)
+    m2 = (hm[-1] - hm) / np.maximum(w2, 1)
+    var = w1[:-1] * w2[:-1] * (m1[:-1] - m2[:-1]) ** 2
+    return float(mids[var.argmax()])
+
+
+def estimate_brain(t1: np.ndarray, zooms: tuple, erode_mm: float = 8.0,
+                   volume_ml: tuple = (800.0, 2000.0), min_core_ml: float = 100.0) -> np.ndarray:
+    """Brain mask from a whole-head T1w by morphology, no atlas.
+
+    Tissue is what lies above an Otsu threshold of the smoothed image. The
+    brain core is every piece of tissue more than ``erode_mm`` from any
+    non-tissue voxel that is at least ``min_core_ml`` in size: the erosion
+    cuts the thin scalp, the optic nerves and the spinal cord, and the size
+    rule keeps both hemispheres when a deep fissure splits the core but drops
+    muscle and tongue. The core is grown back by the same distance inside
+    tissue and holes (ventricles) are filled. The result must have a
+    plausible brain volume or a ValueError is raised: it is a placement
+    mask, not a segmentation, and a wrong one would put lesions in the neck.
+    """
+    vox = np.array(zooms[:3], dtype=float)
+    sm = ndi.gaussian_filter(t1, sigma=1.0 / vox)
+    if not (sm > 0).any():
+        raise ValueError("empty image")
+    tissue = sm > _otsu(sm.ravel())  # background and bone below, soft tissue above
+    core = ndi.distance_transform_edt(tissue, sampling=vox) > erode_mm
+    lab, n = ndi.label(core)
+    if n == 0:
+        raise ValueError("no tissue thicker than the erosion radius; supply a brain mask")
+    sizes = np.bincount(lab.ravel()) * float(np.prod(vox)) / 1000.0
+    sizes[0] = 0
+    keep = np.flatnonzero(sizes >= min_core_ml)
+    if keep.size == 0:
+        keep = np.array([sizes.argmax()])
+    core = np.isin(lab, keep)
+    brain = tissue & (ndi.distance_transform_edt(~core, sampling=vox) <= erode_mm)
+    brain = ndi.binary_fill_holes(brain)
+    for axis in range(3):  # ventricles open to the outside through narrow channels: fill them slice-wise too
+        brain = np.moveaxis(np.array([ndi.binary_fill_holes(sl) for sl in np.moveaxis(brain, axis, 0)]), 0, axis)
+    ml = brain.sum() * float(np.prod(vox)) / 1000.0
+    if not volume_ml[0] <= ml <= volume_ml[1]:
+        raise ValueError(f"brain estimate is {ml:.0f} ml, outside {volume_ml[0]:.0f}-{volume_ml[1]:.0f} ml; "
+                         "supply a brain mask with --mask")
+    return brain
+
+
+def brain_and_wm(t1: np.ndarray, zooms: tuple, flair: np.ndarray | None = None,
+                 mask: np.ndarray | None = None, depth_mm: float = 6.0) -> tuple[np.ndarray, np.ndarray]:
+    """Brain mask (estimated, or the one given) and a white-matter placement estimate.
+
+    White matter is bright T1w tissue deeper than ``depth_mm`` inside the
+    brain; when a FLAIR is given it must also be within 0.6-1.4 of the FLAIR
+    white-matter median, which excludes CSF and anything outside the FLAIR
+    field of view. Good enough to place lesions in deep tissue; not a
+    segmentation.
+    """
+    vox = np.array(zooms[:3], dtype=float)
+    brain = mask.astype(bool) if mask is not None else estimate_brain(t1, zooms)
+    sm = ndi.gaussian_filter(t1, sigma=1.0 / vox)
+    deep = ndi.distance_transform_edt(brain, sampling=vox) > depth_mm
+    wm_thr = np.percentile(sm[brain], 65)  # T1w: white matter is the bright part of the brain
+    wm = deep & (sm >= wm_thr)
+    if flair is not None:
+        fs = ndi.gaussian_filter(flair, sigma=1.0 / vox)
+        med = float(np.median(fs[wm])) if wm.any() else 0.0
+        wm &= (fs > 0.6 * med) & (fs < 1.4 * med)
+    wm = ndi.binary_opening(wm, iterations=1)
+    if wm.sum() * float(np.prod(vox)) < 20_000:
+        raise ValueError("white-matter estimate under 20 ml; is this a whole-head T1w?")
+    return brain, wm
+
+
+def place_lesions(wm: np.ndarray, depth_mm: np.ndarray, zooms: tuple, spec: LesionSpec,
+                  rng: np.random.Generator) -> list[dict]:
+    """Choose centres inside white matter so that no lesion touches another or leaves the brain.
+
+    ``depth_mm`` is the distance from each voxel to the brain edge; a lesion's
+    centre must be deeper than its longest semi-axis. Two lesions must be at
+    least the sum of their longest semi-axes plus ``min_gap_mm`` apart.
+    """
+    candidates = np.argwhere(wm)
+    if len(candidates) == 0:
+        raise ValueError("no white-matter estimate; is this a T1w image?")
+    vols = [spec.volume_mm3[i % len(spec.volume_mm3)] for i in range(spec.n)]
+    rng.shuffle(vols)
+    chosen: list[dict] = []
+    vox_mm = np.array(zooms[:3], dtype=float)
+    for vol in vols:
+        elong = rng.uniform(*spec.elongation)
+        # ellipsoid semi-axes (mm) with volume vol: 4/3 pi a b c, a = elong * b, b = c
+        b = (3 * vol / (4 * np.pi * elong)) ** (1 / 3)
+        axes = np.array([elong * b, b, b])
+        rng.shuffle(axes)
+        reach = float(axes.max())
+        for _ in range(5000):
+            c = candidates[rng.integers(len(candidates))]
+            if depth_mm[tuple(c)] < reach + 1.0:
+                continue
+            c = c.astype(float)
+            if any(np.linalg.norm((c - np.array(o["centre_vox"])) * vox_mm) < reach + max(o["axes_mm"]) + spec.min_gap_mm
+                   for o in chosen):
+                continue
+            chosen.append({"id": len(chosen) + 1, "centre_vox": c.tolist(), "axes_mm": axes.tolist(),
+                           "volume_mm3_nominal": float(vol)})
+            break
+        else:
+            raise ValueError(f"could only place {len(chosen)} of {spec.n} lesions without overlap; fewer or smaller lesions")
+    return chosen
+
+
+def render(shape: tuple, zooms: tuple, lesions: list[dict], edge_mm: float) -> tuple[np.ndarray, np.ndarray]:
+    """Soft lesion field in [0, 1] and the integer label map.
+
+    The field is 0.5 on the ellipsoid surface and falls off over ``edge_mm``
+    on either side (an erf profile of the signed distance, scaled along the
+    shortest axis), so the label, which is the voxels inside the surface, is
+    exactly what a half-maximum segmenter would recover.
+    """
+    grids = np.indices(shape, dtype=np.float32)
+    field_ = np.zeros(shape, np.float32)
+    labels = np.zeros(shape, np.int16)
+    vox_mm = np.array(zooms[:3], dtype=np.float32)
+    for les in lesions:
+        c = np.array(les["centre_vox"], np.float32)
+        axes = np.array(les["axes_mm"], np.float32)
+        d = (grids - c[:, None, None, None]) * vox_mm[:, None, None, None] / axes[:, None, None, None]
+        r = np.sqrt((d**2).sum(0))  # 1.0 on the ellipsoid surface
+        signed_mm = (r - 1.0) * axes.min()  # negative inside
+        soft = 0.5 * (1.0 - erf(signed_mm / max(edge_mm, 1e-3)))
+        field_ = np.maximum(field_, soft.astype(np.float32))
+        labels[(r <= 1.0) & (labels == 0)] = les["id"]
+    return field_, labels
+
+
+def _float_header(img):
+    hdr = img.header.copy()
+    hdr.set_data_dtype(np.float32)
+    hdr.set_slope_inter(1.0, 0.0)
+    return hdr
+
+
+def inject(t1_path: Path, flair_path: Path | None, out_t1: Path, out_flair: Path | None, out_mask: Path,
+           out_truth: Path, spec: LesionSpec, mask_path: Path | None = None) -> dict:
+    """Write the injected T1w (and FLAIR), the truth label map and the truth JSON.
+
+    Nothing is written until every input has been checked, so a failure
+    leaves no partial subject behind.
+    """
+    rng = np.random.default_rng(spec.seed)
+    t1_img = nib.load(t1_path)
+    t1 = np.asarray(t1_img.dataobj, dtype=np.float32)
+    zooms = t1_img.header.get_zooms()
+    fl_img = fl = None
+    if flair_path is not None and out_flair is not None:
+        fl_img = nib.load(flair_path)
+        if fl_img.shape != t1_img.shape or not np.allclose(fl_img.affine, t1_img.affine, atol=1e-3):
+            raise ValueError(f"FLAIR grid {fl_img.shape} differs from T1w {t1_img.shape} (or the affines differ); "
+                             "inject expects co-registered images on one grid")
+        fl = np.asarray(fl_img.dataobj, dtype=np.float32)
+    mask = None
+    if mask_path is not None:
+        m_img = nib.load(mask_path)
+        if m_img.shape != t1_img.shape:
+            raise ValueError(f"brain mask grid {m_img.shape} differs from T1w {t1_img.shape}")
+        mask = np.asarray(m_img.dataobj) > 0
+    brain, wm = brain_and_wm(t1, zooms, fl, mask)
+    depth = ndi.distance_transform_edt(brain, sampling=zooms[:3])
+    lesions = place_lesions(wm, depth, zooms, spec, rng)
+    field_, labels = render(t1.shape, zooms, lesions, spec.edge_mm)
+    # reference intensity: median of the white-matter estimate over the whole brain
+    wm_ref_t1 = float(np.median(t1[wm]))
+    t1_out = t1 * (1.0 + spec.t1_contrast * field_)
+    nib.save(nib.Nifti1Image(t1_out.astype(np.float32), t1_img.affine, _float_header(t1_img)), out_t1)
+    flair_note = None
+    if fl is not None:
+        wm_ref_fl = float(np.median(fl[wm]))
+        fl_out = fl + spec.flair_contrast * wm_ref_fl * field_
+        nib.save(nib.Nifti1Image(fl_out.astype(np.float32), fl_img.affine, _float_header(fl_img)), out_flair)
+        flair_note = {"wm_reference": wm_ref_fl, "contrast": spec.flair_contrast}
+    nib.save(nib.Nifti1Image(labels, t1_img.affine), out_mask)
+    voxel_mm3 = float(np.prod(zooms[:3]))
+    for les in lesions:
+        les["voxels"] = int((labels == les["id"]).sum())
+        les["volume_mm3"] = les["voxels"] * voxel_mm3  # the label's volume, which is what is scored
+    truth = {
+        "kind": "lesions", "seed": spec.seed, "n": len(lesions), "edge_mm": spec.edge_mm,
+        "edge": "field is 0.5 on the ellipsoid surface, erf falloff over edge_mm; label = inside the surface",
+        "t1": {"wm_reference": wm_ref_t1, "contrast": spec.t1_contrast}, "flair": flair_note,
+        "brain_mask": "given" if mask is not None else "estimated",
+        "brain_volume_mm3": float(brain.sum() * voxel_mm3),
+        "voxel_mm": [float(z) for z in zooms[:3]],
+        "lesions": lesions,
+        "total_volume_mm3": float(sum(les["volume_mm3"] for les in lesions)),
+        "mask_voxels": int((labels > 0).sum()),
+    }
+    with open(out_truth, "w") as fh:
+        json.dump(truth, fh, indent=2)
+    return truth

bidsgate/report.py

@@ -0,0 +1,65 @@
+"""A self-contained HTML scorecard, one file, no scripts, readable in any browser."""
+
+from __future__ import annotations
+
+import html
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+def _pct(x) -> str:
+    try:
+        v = float(x)
+    except (TypeError, ValueError):
+        return "-"
+    return "-" if v != v else f"{100 * v:.0f}%"
+
+
+def _f(x, d=2) -> str:
+    try:
+        v = float(x)
+    except (TypeError, ValueError):
+        return "-"
+    return "-" if v != v else f"{v:.{d}f}"
+
+
+def scorecard_lesions(results: list[dict], pipeline: str, out: Path) -> Path:
+    """``results`` is a list of {"subject": ..., "score": score_lesions(...)}."""
+    rows = []
+    for r in results:
+        s = r["score"]
+        rows.append(f"<tr><td>{html.escape(r['subject'])}</td><td>{_f(s['dice'])}</td><td>{s['detected']}/{s['lesions']} ({_pct(s['sensitivity'])})</td>"
+                    f"<td>{s['false_positive_components']}</td><td>{_f(s['volume_ratio'])}</td>"
+                    + "".join(f"<td>{_pct(v['sensitivity'])} (n={v['n']})</td>" for _, v in sorted(s['by_size'].items()))
+                    + "</tr>")
+    n = len(results)
+    dice = sum(r["score"]["dice"] for r in results) / n if n else float("nan")
+    sens = sum(r["score"]["sensitivity"] for r in results) / n if n else float("nan")
+    fp = sum(r["score"]["false_positive_components"] for r in results)
+    bins = sorted(results[0]["score"]["by_size"].keys()) if results else []
+    doc = f"""<!doctype html><html><head><meta charset="utf-8"><title>bidsgate scorecard: {html.escape(pipeline)}</title>
+<style>body{{font:15px/1.4 system-ui,sans-serif;max-width:960px;margin:2rem auto;padding:0 1rem;color:#222}}
+table{{border-collapse:collapse;width:100%}}td,th{{border-bottom:1px solid #ddd;padding:.4rem .5rem;text-align:left}}
+th{{background:#f4f4f4}}.big{{font-size:2rem;margin:.2rem 0}}.grid{{display:flex;gap:2rem;flex-wrap:wrap}}.note{{color:#555}}</style></head><body>
+<h1>bidsgate scorecard: {html.escape(pipeline)}</h1>
+<p class="note">Synthetic lesions with a known mask were injected into real T1w/FLAIR images; the pipeline was run on the result; this is what it recovered. Generated {datetime.now(timezone.utc).strftime('%Y-%m-%d %H:%M UTC')}. Nothing here is evidence about any disease; it is a test of software.</p>
+<div class="grid"><div><div class="big">{_f(dice)}</div>mean Dice</div><div><div class="big">{_pct(sens)}</div>lesion-wise sensitivity</div><div><div class="big">{fp}</div>false-positive components</div><div><div class="big">{n}</div>subjects</div></div>
+<table><tr><th>subject</th><th>Dice</th><th>detected</th><th>FP comps</th><th>volume ratio</th>{''.join(f'<th>sens {html.escape(b)}</th>' for b in bins)}</tr>{''.join(rows)}</table>
+<p class="note">Sensitivity by injected lesion volume shows the detection floor: the size below which the pipeline stops seeing lesions. Volume ratio is predicted over injected volume; under 1 means the pipeline under-segments what it does find.</p>
+</body></html>"""
+    out.write_text(doc)
+    return out
+
+
+def scorecard_atrophy(results: list[dict], pipeline: str, out: Path) -> Path:
+    rows = "".join(f"<tr><td>{html.escape(r['subject'])}</td><td>{_f(r['score']['injected_change_pct'],1)}%</td><td>{_f(r['score']['measured_change_pct'],1)}%</td><td>{_f(r['score']['recovery'])}</td></tr>" for r in results)
+    n = len(results)
+    rec = sum(r["score"]["recovery"] for r in results) / n if n else float("nan")
+    doc = f"""<!doctype html><html><head><meta charset="utf-8"><title>bidsgate scorecard: {html.escape(pipeline)}</title>
+<style>body{{font:15px/1.4 system-ui,sans-serif;max-width:960px;margin:2rem auto;padding:0 1rem;color:#222}}table{{border-collapse:collapse;width:100%}}td,th{{border-bottom:1px solid #ddd;padding:.4rem .5rem;text-align:left}}th{{background:#f4f4f4}}.big{{font-size:2rem}}.note{{color:#555}}</style></head><body>
+<h1>bidsgate scorecard: {html.escape(pipeline)}</h1>
+<p class="note">A known brain-volume change was injected into real T1w images; the pipeline measured volumes before and after. Recovery 1.0 means it reported exactly the injected change.</p>
+<div class="big">{_f(rec)}</div>mean recovery over {n} subjects
+<table><tr><th>subject</th><th>injected change</th><th>measured change</th><th>recovery</th></tr>{rows}</table></body></html>"""
+    out.write_text(doc)
+    return out

bidsgate/score.py

@@ -0,0 +1,93 @@
+"""Score what a pipeline recovered against the injected truth."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import nibabel as nib
+import numpy as np
+import pandas as pd
+from scipy import ndimage as ndi
+
+SIZE_BINS = [(0, 100), (100, 500), (500, 10**9)]
+
+
+def _bin(vol: float) -> str:
+    for lo, hi in SIZE_BINS:
+        if lo <= vol < hi:
+            return f"{lo}-{hi if hi < 10**9 else 'inf'}mm3"
+    return "?"
+
+
+def score_lesions(truth_json: Path, truth_mask: Path, pred_mask: Path, threshold: float = 0.5,
+                  fp_margin_mm: float = 2.0) -> dict:
+    """Voxel and lesion-wise agreement between a predicted mask and the injected one.
+
+    A predicted mask may be probabilistic; it is thresholded at ``threshold``.
+    A truth lesion counts as detected when any predicted voxel overlaps it.
+    False-positive volume is every predicted voxel farther than ``fp_margin_mm``
+    from any truth lesion, and false-positive components are the connected
+    pieces (18-connectivity) of that residual, so over-segmentation that
+    happens to touch a true lesion is still counted.
+    """
+    with open(truth_json) as fh:
+        truth = json.load(fh)
+    t_img = nib.load(truth_mask)
+    t = np.asarray(t_img.dataobj).astype(np.int32)
+    p_img = nib.load(pred_mask)
+    p = np.asarray(p_img.dataobj, dtype=np.float32)
+    if p.shape != t.shape or not np.allclose(p_img.affine, t_img.affine, atol=1e-3):
+        raise ValueError(f"prediction {p.shape} is not on the truth grid {t.shape} (shape or affine differs); "
+                         "resample it onto the truth image first")
+    pb = p >= threshold
+    tb = t > 0
+    inter = float((pb & tb).sum())
+    dice = 2 * inter / (pb.sum() + tb.sum()) if (pb.sum() + tb.sum()) else float("nan")
+    voxel_mm3 = float(np.prod(t_img.header.get_zooms()[:3]))
+    rows = []
+    for les in truth["lesions"]:
+        sel = t == les["id"]
+        hit = bool(pb[sel].any())
+        rows.append({"id": les["id"], "volume_mm3": les["volume_mm3"], "voxels": int(sel.sum()),
+                     "bin": _bin(les["volume_mm3"]), "detected": hit,
+                     "overlap_fraction": float(pb[sel].mean()) if sel.any() else float("nan")})
+    per = pd.DataFrame(rows)
+    near_truth = ndi.distance_transform_edt(~tb, sampling=t_img.header.get_zooms()[:3]) <= fp_margin_mm
+    residual = pb & ~near_truth
+    _, fp = ndi.label(residual, structure=ndi.generate_binary_structure(3, 2))
+    fp_volume = float(residual.sum() * voxel_mm3)
+    by_bin = per.groupby("bin")["detected"].agg(["count", "mean"]).rename(columns={"count": "n", "mean": "sensitivity"})
+    return {
+        "dice": dice,
+        "sensitivity": float(per["detected"].mean()) if len(per) else float("nan"),
+        "lesions": len(per),
+        "detected": int(per["detected"].sum()),
+        "false_positive_components": int(fp),
+        "false_positive_volume_mm3": fp_volume,
+        "fp_margin_mm": fp_margin_mm,
+        "predicted_volume_mm3": float(pb.sum() * voxel_mm3),
+        "truth_volume_mm3": float(tb.sum() * voxel_mm3),
+        "volume_ratio": float(pb.sum() / tb.sum()) if tb.sum() else float("nan"),
+        "by_size": {k: {"n": int(v["n"]), "sensitivity": float(v["sensitivity"])} for k, v in by_bin.iterrows()},
+        "per_lesion": rows,
+    }
+
+
+def score_atrophy(truth_json: Path, volume_before_mm3: float, volume_after_mm3: float) -> dict:
+    """Compare a tool's reported volumes before and after injection with the injected factor."""
+    with open(truth_json) as fh:
+        truth = json.load(fh)
+    injected = truth["volume_factor"]
+    measured = volume_after_mm3 / volume_before_mm3 if volume_before_mm3 else float("nan")
+    injected_change = (injected - 1) * 100
+    measured_change = (measured - 1) * 100
+    return {
+        "injected_factor": injected,
+        "measured_factor": measured,
+        "injected_change_pct": injected_change,
+        "measured_change_pct": measured_change,
+        "recovery": measured_change / injected_change if injected_change else float("nan"),
+        "volume_before_mm3": volume_before_mm3,
+        "volume_after_mm3": volume_after_mm3,
+    }

bidsgate-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,13 @@
+bidsgate/__init__.py,sha256=SK_XC7inUZFQ2fzaZ-L7WFImNgW1v9o4MqtUngwL2SM,277
+bidsgate/bids.py,sha256=eyg8bKGhOSg5xiuRff_lYlAjUdkONQFDAaFyCRtRQQ4,3069
+bidsgate/cli.py,sha256=pzJda0p7_sII5QRpdD9T6h3pIt88wBBtL5yQzFecwPU,9650
+bidsgate/inject_atrophy.py,sha256=yATkb8D7JOJJpS218GkhOLpbeOk04ARiP92Bf2y7DRc,4131
+bidsgate/inject_lesions.py,sha256=np70Gh1ILtTgbyXb1xvAGVN2fP1OgqivYtavnLUus2w,11806
+bidsgate/report.py,sha256=VIN7K56b1QAdrxVtASwfh1M3AbvteId-5dYRBu1EaFg,4379
+bidsgate/score.py,sha256=8_sgpzaS_-jI6tihMX1zAcW4N-tc3onuYjWKCZRG8R8,4160
+bidsgate-0.1.0.dist-info/licenses/LICENSE,sha256=8lcLWeN_AyQyu7Rc59azPb8rsdho2H380fSv3nnRoII,1070
+bidsgate-0.1.0.dist-info/METADATA,sha256=OoFHYpvGx71xUtZYR_tlRHog_DHzPT5J1BwGl_7_zLs,9251
+bidsgate-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+bidsgate-0.1.0.dist-info/entry_points.txt,sha256=DDJk7x_iZgu5Biy7r2nvvp6EuQ21MdyX_FNuXiZ7wqE,47
+bidsgate-0.1.0.dist-info/top_level.txt,sha256=ucCM7miNa7_wAKvb9c9A5UM_5pJMiYkK1Bgw13Atulg,9
+bidsgate-0.1.0.dist-info/RECORD,,

bidsgate-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

bidsgate-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+bidsgate = bidsgate.cli:main

bidsgate-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+bidsgate