ayar 0.1.0__py3-none-any.whl

ayar/__init__.py

@@ -0,0 +1,28 @@
+"""ayar: assay your spike-sorted finding before you publish.
+
+ayar reads the output of any spike sorter, flags sorting artifacts that can
+manufacture or hide a result (duplicated units, overlap holes, drift-driven rate
+changes), and re-computes *your* finding without the flagged units to tell you
+whether it survives.
+
+    import ayar
+    bundle = ayar.load("kilosort_output/")          # or a .npz bundle
+    report = ayar.scan(bundle, finding=my_analysis)
+    print(report)
+"""
+
+__version__ = "0.1.0"
+
+from .bundle import Bundle, Events  # noqa: E402
+from .config import DEFAULTS, Thresholds  # noqa: E402
+from .flags import Flag, NotChecked, Report, Severity  # noqa: E402
+from .io import from_arrays, from_phy, load  # noqa: E402
+from .scan import scan  # noqa: E402
+from .synth import SynthConfig, make_session  # noqa: E402
+from .validate import validate  # noqa: E402
+
+__all__ = [
+    "Bundle", "Events", "Thresholds", "DEFAULTS", "Flag", "NotChecked", "Report", "Severity",
+    "from_arrays", "from_phy", "load", "scan", "make_session", "SynthConfig", "validate",
+    "__version__",
+]

ayar/audit.py

@@ -0,0 +1,165 @@
+"""The finding audit: does the user's result survive removing the flagged units?
+
+The user's finding is any function ``f(bundle) -> float | dict[str, float]``.
+For each detector that raised flags, ayar removes the implicated units, recomputes
+the finding, and compares the change with *random-drop controls*: the same number
+of unflagged units removed at random. A change is only blamed on the artifact if
+it is larger than what dropping arbitrary units does.
+"""
+
+from __future__ import annotations
+
+import importlib
+import importlib.util
+import math
+import sys
+from pathlib import Path
+from typing import Any, Callable
+
+import numpy as np
+
+from .bundle import Bundle
+from .config import Thresholds
+from .flags import AuditRow, Flag
+
+FindingFn = Callable[[Bundle], Any]
+
+
+def units_to_drop(flag: Flag) -> set[int]:
+    """The units whose removal neutralises a flag.
+
+    Pair flags list the unit to keep first, so the second unit is dropped
+    (for duplicates, the smaller copy). Single-unit flags drop the unit.
+    """
+    if len(flag.units) >= 2:
+        return {int(flag.units[1])}
+    return {int(u) for u in flag.units}
+
+
+def call_finding(fn: FindingFn, bundle: Bundle) -> dict[str, float]:
+    out = fn(bundle)
+    if isinstance(out, dict):
+        items = out.items()
+    else:
+        items = [("value", out)]
+    res: dict[str, float] = {}
+    for k, v in items:
+        try:
+            res[str(k)] = float(v)
+        except (TypeError, ValueError):
+            raise TypeError(
+                f"finding must return a number or a dict of numbers; {k!r} is {type(v).__name__}"
+            ) from None
+    return res
+
+
+def _rel(new: float, base: float) -> float:
+    if not (math.isfinite(new) and math.isfinite(base)):
+        return math.inf
+    return abs(new - base) / max(abs(base), 1e-12)
+
+
+def _flipped(new: float, base: float) -> bool:
+    return base != 0 and new != 0 and math.copysign(1, new) != math.copysign(1, base)
+
+
+def audit(
+    bundle: Bundle,
+    finding: FindingFn,
+    flags: list[Flag],
+    th: Thresholds,
+) -> tuple[dict[str, float], list[AuditRow]]:
+    baseline = call_finding(finding, bundle)
+
+    groups: dict[str, set[int]] = {}
+    for f in flags:
+        groups.setdefault(f.code, set()).update(units_to_drop(f))
+    if len(groups) > 1:
+        groups["ALL_FLAGS"] = set().union(*groups.values())
+
+    flagged_any = set().union(*groups.values()) if groups else set()
+    pool = np.array([int(u) for u in bundle.unit_ids if int(u) not in flagged_any])
+    rng = np.random.default_rng(th.audit_seed)
+
+    rows: list[AuditRow] = []
+    for name, drop in groups.items():
+        k = len(drop)
+        try:
+            value = call_finding(finding, bundle.without(drop))
+        except Exception as e:  # the user's function may not cope with fewer units
+            for key, base in baseline.items():
+                rows.append(AuditRow(key, name, k, base, None, None, None, None, "failed",
+                                     f"finding raised {type(e).__name__}: {e}"))
+            continue
+
+        controls: list[dict[str, float]] = []
+        note = ""
+        if th.audit_controls > 0 and pool.size >= k and k > 0:
+            for _ in range(th.audit_controls):
+                pick = rng.choice(pool, size=k, replace=False)
+                try:
+                    controls.append(call_finding(finding, bundle.without(pick.tolist())))
+                except Exception:
+                    pass
+        elif th.audit_controls > 0:
+            note = f"no random-drop controls: only {pool.size} unflagged units for {k} drops"
+
+        for key, base in baseline.items():
+            new = value.get(key, math.nan)
+            rel = _rel(new, base)
+            ctrl_rel = [_rel(c[key], base) for c in controls if key in c]
+            ctrl_q = float(np.quantile(ctrl_rel, th.audit_control_quantile)) if ctrl_rel else None
+            flip_rate = (
+                float(np.mean([_flipped(c[key], base) for c in controls if key in c]))
+                if ctrl_rel else None
+            )
+            beyond = ctrl_q is None or rel > ctrl_q
+            if _flipped(new, base) and (flip_rate is None or flip_rate < 1 - th.audit_control_quantile):
+                verdict = "flipped"
+            elif rel < th.audit_robust:
+                verdict = "robust"
+            elif not beyond:
+                verdict = "nonspecific"
+            elif rel >= th.audit_sensitive:
+                verdict = "sensitive"
+            else:
+                verdict = "shifted"
+            rows.append(
+                AuditRow(
+                    key=key,
+                    ablation=name,
+                    n_dropped=k,
+                    baseline=base,
+                    value=new,
+                    rel_change=rel,
+                    control_q=ctrl_q,
+                    control_flip_rate=flip_rate,
+                    verdict=verdict,
+                    note=note,
+                )
+            )
+    return baseline, rows
+
+
+def load_finding(spec: str) -> tuple[str, FindingFn]:
+    """Resolve ``path/to/file.py:func`` or ``package.module:func``."""
+    if ":" not in spec:
+        raise ValueError(f"finding must look like file.py:func or module:func, got {spec!r}")
+    target, func = spec.rsplit(":", 1)
+    if target.endswith(".py") or Path(target).exists():
+        path = Path(target).resolve()
+        if not path.exists():
+            raise FileNotFoundError(path)
+        mod_name = f"_ayar_finding_{path.stem}"
+        spec_obj = importlib.util.spec_from_file_location(mod_name, path)
+        if spec_obj is None or spec_obj.loader is None:
+            raise ImportError(f"cannot import {path}")
+        module = importlib.util.module_from_spec(spec_obj)
+        sys.modules[mod_name] = module
+        spec_obj.loader.exec_module(module)
+    else:
+        module = importlib.import_module(target)
+    fn = getattr(module, func, None)
+    if not callable(fn):
+        raise AttributeError(f"{target} has no callable {func!r}")
+    return f"{Path(target).name if target.endswith('.py') else target}:{func}", fn

ayar/bundle.py

@@ -0,0 +1,328 @@
+"""The ayar bundle: the one input contract every detector reads.
+
+A bundle is the output of *any* spike sorter reduced to what ayar needs:
+
+* ``spike_times`` (seconds) and ``spike_clusters`` (unit id per spike): tier 0
+* ``amplitudes`` and/or ``spike_depths`` / ``unit_depths``: tier 1
+* ``events`` (trial times, optional condition labels): needed for confound checks
+
+Bundles are saved as plain ``.npz`` files that numpy can read without ayar.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Iterable, Mapping
+
+import numpy as np
+
+FORMAT_VERSION = 1
+
+
+class Events:
+    """Trial or event times, with an optional condition label per event."""
+
+    def __init__(self, times: Iterable[float], labels: Iterable[Any] | None = None):
+        times = np.asarray(times, dtype=float).ravel()
+        if not np.all(np.isfinite(times)):
+            raise ValueError("event times must be finite")
+        order = np.argsort(times, kind="stable")
+        self.times = times[order]
+        if labels is None:
+            self.labels = None
+        else:
+            labels = np.asarray(labels).ravel()
+            if labels.shape[0] != times.shape[0]:
+                raise ValueError(
+                    f"{labels.shape[0]} event labels for {times.shape[0]} event times"
+                )
+            self.labels = labels[order]
+
+    def __len__(self) -> int:
+        return int(self.times.shape[0])
+
+    @property
+    def label_values(self) -> np.ndarray:
+        if self.labels is None:
+            return np.array([])
+        return np.unique(self.labels)
+
+    def __repr__(self) -> str:
+        n_lab = len(self.label_values)
+        return f"Events(n={len(self)}, labels={n_lab if self.labels is not None else None})"
+
+
+class Bundle:
+    """Sorted spikes plus whatever extra evidence the sorter provides."""
+
+    def __init__(
+        self,
+        spike_times: Iterable[float],
+        spike_clusters: Iterable[int],
+        *,
+        duration: float | None = None,
+        amplitudes: Iterable[float] | None = None,
+        spike_depths: Iterable[float] | None = None,
+        unit_ids: Iterable[int] | None = None,
+        unit_depths: Iterable[float] | Mapping[int, float] | None = None,
+        events: Events | tuple | Mapping | None = None,
+        meta: Mapping[str, Any] | None = None,
+    ):
+        st = np.asarray(spike_times, dtype=float).ravel()
+        sc = np.asarray(spike_clusters).ravel()
+        if st.shape != sc.shape:
+            raise ValueError(f"{st.size} spike times but {sc.size} spike clusters")
+        if not np.all(np.isfinite(st)):
+            raise ValueError("spike times must be finite")
+        if st.size and st.min() < 0:
+            raise ValueError("spike times must be >= 0 (seconds from session start)")
+        sc = sc.astype(np.int64)
+
+        if st.size > 1 and np.any(np.diff(st) < 0):
+            order = np.argsort(st, kind="stable")
+        else:
+            order = np.arange(st.size)  # already sorted: skip the O(n log n) sort
+        self.spike_times = st[order]
+        self.spike_clusters = sc[order]
+        self.amplitudes = self._per_spike(amplitudes, order, "amplitudes")
+        self.spike_depths = self._per_spike(spike_depths, order, "spike_depths")
+
+        if unit_ids is None:
+            self.unit_ids = np.unique(self.spike_clusters)
+        else:
+            self.unit_ids = np.unique(np.asarray(list(unit_ids), dtype=np.int64))
+            missing = np.setdiff1d(np.unique(self.spike_clusters), self.unit_ids)
+            if missing.size:
+                raise ValueError(f"spikes belong to units not in unit_ids: {missing[:10].tolist()}")
+
+        self.unit_depths = self._unit_depths(unit_depths)
+
+        last = float(self.spike_times[-1]) if self.spike_times.size else 0.0
+        if duration is None:
+            duration = last
+        if duration < last:
+            raise ValueError(f"duration {duration} s is shorter than the last spike at {last} s")
+        self.duration = float(duration)
+
+        self.events = self._events(events)
+        self.meta: dict[str, Any] = dict(meta or {})
+        self._index: dict[int, np.ndarray] | None = None
+
+    # ------------------------------------------------------------------ build
+    def _per_spike(self, values, order, name):
+        if values is None:
+            return None
+        v = np.asarray(values, dtype=float).ravel()
+        if v.shape[0] != order.shape[0]:
+            raise ValueError(f"{name} has {v.shape[0]} values for {order.shape[0]} spikes")
+        return v[order]
+
+    def _unit_depths(self, unit_depths):
+        if unit_depths is None:
+            return None
+        if isinstance(unit_depths, Mapping):
+            d = np.array([float(unit_depths.get(int(u), np.nan)) for u in self.unit_ids])
+        else:
+            d = np.asarray(unit_depths, dtype=float).ravel()
+            if d.shape[0] != self.unit_ids.shape[0]:
+                raise ValueError(
+                    f"unit_depths has {d.shape[0]} values for {self.unit_ids.shape[0]} units"
+                )
+        return d
+
+    @staticmethod
+    def _events(events):
+        if events is None or isinstance(events, Events):
+            return events
+        if isinstance(events, Mapping):
+            return Events(events["times"], events.get("labels"))
+        if isinstance(events, tuple):
+            return Events(*events)
+        return Events(events)
+
+    def _build_index(self) -> dict[int, np.ndarray]:
+        order = np.argsort(self.spike_clusters, kind="stable")  # stable keeps time order
+        sorted_c = self.spike_clusters[order]
+        starts = np.searchsorted(sorted_c, self.unit_ids, side="left")
+        ends = np.searchsorted(sorted_c, self.unit_ids, side="right")
+        return {int(u): order[s:e] for u, s, e in zip(self.unit_ids, starts, ends)}
+
+    # ----------------------------------------------------------------- access
+    def spike_indices(self, unit: int) -> np.ndarray:
+        if self._index is None:
+            self._index = self._build_index()
+        try:
+            return self._index[int(unit)]
+        except KeyError:
+            raise KeyError(f"no unit {unit} in bundle") from None
+
+    def train(self, unit: int) -> np.ndarray:
+        """Sorted spike times (s) of one unit."""
+        return self.spike_times[self.spike_indices(unit)]
+
+    def trains(self) -> dict[int, np.ndarray]:
+        return {int(u): self.train(u) for u in self.unit_ids}
+
+    def unit_amplitudes(self, unit: int) -> np.ndarray | None:
+        if self.amplitudes is None:
+            return None
+        return self.amplitudes[self.spike_indices(unit)]
+
+    def unit_spike_depths(self, unit: int) -> np.ndarray | None:
+        if self.spike_depths is None:
+            return None
+        return self.spike_depths[self.spike_indices(unit)]
+
+    def depth(self, unit: int) -> float | None:
+        """Unit depth (µm) from ``unit_depths``, else the median spike depth."""
+        if self.unit_depths is not None:
+            i = int(np.searchsorted(self.unit_ids, int(unit)))
+            v = float(self.unit_depths[i])
+            if np.isfinite(v):
+                return v
+        d = self.unit_spike_depths(unit)
+        if d is not None and d.size:
+            return float(np.median(d))
+        return None
+
+    def rate(self, unit: int) -> float:
+        return len(self.spike_indices(unit)) / self.duration if self.duration > 0 else 0.0
+
+    @property
+    def n_units(self) -> int:
+        return int(self.unit_ids.shape[0])
+
+    @property
+    def n_spikes(self) -> int:
+        return int(self.spike_times.shape[0])
+
+    @property
+    def has_amplitudes(self) -> bool:
+        return self.amplitudes is not None
+
+    @property
+    def has_depths(self) -> bool:
+        return self.unit_depths is not None or self.spike_depths is not None
+
+    @property
+    def tier(self) -> int:
+        """0: spike times only. 1: plus amplitudes or depths."""
+        return 1 if (self.has_amplitudes or self.has_depths) else 0
+
+    # -------------------------------------------------------------- transform
+    def without(self, units: Iterable[int]) -> "Bundle":
+        """A new bundle with the given units removed (used by the finding audit)."""
+        drop = np.asarray(sorted({int(u) for u in units}), dtype=np.int64)
+        keep_unit = ~np.isin(self.unit_ids, drop)
+        if self._index is None:
+            self._index = self._build_index()
+        keep_spk = np.ones(self.n_spikes, dtype=bool)
+        for u in drop:
+            if int(u) in self._index:
+                keep_spk[self._index[int(u)]] = False
+        new_pos = np.cumsum(keep_spk) - 1
+        child_index = {
+            int(u): new_pos[self._index[int(u)]] for u in self.unit_ids[keep_unit]
+        }
+        # internal fast path: the parent is already validated and sorted
+        child = object.__new__(Bundle)
+        child.spike_times = self.spike_times[keep_spk]
+        child.spike_clusters = self.spike_clusters[keep_spk]
+        child.amplitudes = None if self.amplitudes is None else self.amplitudes[keep_spk]
+        child.spike_depths = None if self.spike_depths is None else self.spike_depths[keep_spk]
+        child.unit_ids = self.unit_ids[keep_unit]
+        child.unit_depths = None if self.unit_depths is None else self.unit_depths[keep_unit]
+        child.duration = self.duration
+        child.events = self.events
+        child.meta = self.meta
+        child._index = child_index
+        return child
+
+    def summary(self) -> dict[str, Any]:
+        ev = None
+        if self.events is not None:
+            ev = {
+                "n": len(self.events),
+                "labels": [str(v) for v in self.events.label_values] if self.events.labels is not None else None,
+            }
+        return {
+            "n_units": self.n_units,
+            "n_spikes": self.n_spikes,
+            "duration_s": round(self.duration, 3),
+            "tier": self.tier,
+            "amplitudes": self.has_amplitudes,
+            "depths": self.has_depths,
+            "events": ev,
+            "source": self.meta.get("source"),
+        }
+
+    def __repr__(self) -> str:
+        return (
+            f"Bundle(units={self.n_units}, spikes={self.n_spikes}, "
+            f"duration={self.duration:.1f}s, tier={self.tier})"
+        )
+
+    # --------------------------------------------------------------------- io
+    def save(self, path: str | Path) -> Path:
+        path = Path(path)
+        if path.suffix != ".npz":
+            path = path.with_suffix(".npz")
+        arrays: dict[str, np.ndarray] = {
+            "format_version": np.array(FORMAT_VERSION),
+            "spike_times": self.spike_times,
+            "spike_clusters": self.spike_clusters,
+            "unit_ids": self.unit_ids,
+            "duration": np.array(self.duration),
+            "meta_json": np.array(json.dumps(self.meta, default=_json_default)),
+        }
+        if self.amplitudes is not None:
+            arrays["amplitudes"] = self.amplitudes
+        if self.spike_depths is not None:
+            arrays["spike_depths"] = self.spike_depths
+        if self.unit_depths is not None:
+            arrays["unit_depths"] = self.unit_depths
+        if self.events is not None:
+            arrays["event_times"] = self.events.times
+            if self.events.labels is not None:
+                labels = self.events.labels
+                if labels.dtype == object:
+                    labels = labels.astype(str)
+                arrays["event_labels"] = labels
+        np.savez_compressed(path, **arrays)
+        return path
+
+    @classmethod
+    def load(cls, path: str | Path) -> "Bundle":
+        with np.load(Path(path), allow_pickle=False) as z:
+            version = int(z["format_version"]) if "format_version" in z else 1
+            if version > FORMAT_VERSION:
+                raise ValueError(
+                    f"bundle format {version} is newer than this ayar supports ({FORMAT_VERSION})"
+                )
+            get = lambda k: z[k] if k in z else None  # noqa: E731
+            events = None
+            if "event_times" in z:
+                events = Events(z["event_times"], get("event_labels"))
+            meta = json.loads(str(z["meta_json"])) if "meta_json" in z else {}
+            return cls(
+                z["spike_times"],
+                z["spike_clusters"],
+                duration=float(z["duration"]) if "duration" in z else None,
+                amplitudes=get("amplitudes"),
+                spike_depths=get("spike_depths"),
+                unit_ids=get("unit_ids"),
+                unit_depths=get("unit_depths"),
+                events=events,
+                meta=meta,
+            )
+
+
+def _json_default(o):
+    if isinstance(o, np.integer):
+        return int(o)
+    if isinstance(o, np.floating):
+        return float(o)
+    if isinstance(o, np.ndarray):
+        return o.tolist()
+    raise TypeError(f"not JSON serialisable: {type(o).__name__}")

ayar/cli.py

@@ -0,0 +1,176 @@
+"""Command-line interface: ``ayar synth | scan | validate | info | doctor``."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import platform
+import sys
+from pathlib import Path
+
+from . import __version__
+
+
+def _thresholds(args):
+    from .config import DEFAULTS
+
+    return DEFAULTS.override_strings(args.set or [])
+
+
+def cmd_synth(args) -> int:
+    from .synth import SynthConfig, make_session
+
+    cfg = SynthConfig(n_units=args.units, duration=args.duration, design=args.design)
+    b = make_session(args.seed, cfg)
+    path = b.save(args.out)
+    t = b.meta["truth"]
+    print(f"wrote {path}: {b.n_units} units, {b.n_spikes:,} spikes, {b.duration:g} s, design={args.design}")
+    print(f"planted: " + ", ".join(f"{x['code']} {x['units']}" for x in t))
+    return 0
+
+
+def cmd_scan(args) -> int:
+    from .audit import load_finding
+    from .io import load
+    from .render import format_text
+    from .scan import scan
+
+    try:
+        th = _thresholds(args)
+        kw = {}
+        if args.sample_rate:
+            kw["sample_rate"] = args.sample_rate
+        bundle = load(args.bundle, **kw)
+        if args.events is not None:
+            from .bundle import Events
+            import numpy as np
+
+            with np.load(args.events, allow_pickle=False) as z:
+                bundle.events = Events(z["times"], z["labels"] if "labels" in z else None)
+        finding, name = None, None
+        if args.finding:
+            name, finding = load_finding(args.finding)
+        report = scan(bundle, finding, thresholds=th, detectors=args.only, finding_name=name)
+    except (FileNotFoundError, ValueError, KeyError, TypeError, ImportError, AttributeError) as e:
+        print(f"ayar: error: {e}", file=sys.stderr)
+        return 2
+
+    if args.json:
+        Path(args.json).write_text(report.to_json())
+    if args.format == "json":
+        print(report.to_json())
+    else:
+        print(format_text(report, verbose=args.verbose))
+        if args.json:
+            print(f"report written to {args.json}")
+    return report.exit_code(args.fail_on)
+
+
+def cmd_validate(args) -> int:
+    from .synth import SynthConfig
+    from .validate import validate
+
+    res = validate(range(args.seed, args.seed + args.sessions), SynthConfig(duration=args.duration),
+                   _thresholds(args))
+    if args.format == "json":
+        print(json.dumps(res.to_dict(), indent=2))
+    else:
+        print(res.format_text())
+    ok = res.passed(args.min_sensitivity, args.min_precision)
+    if args.format != "json":
+        print(f"\n  {'PASS' if ok else 'FAIL'} (min sensitivity {args.min_sensitivity}, "
+              f"min precision {args.min_precision}, no control alarms)")
+    return 0 if ok else 1
+
+
+def cmd_info(args) -> int:
+    from .io import load
+
+    b = load(args.bundle)
+    print(json.dumps(b.summary(), indent=2))
+    return 0
+
+
+def cmd_doctor(args) -> int:
+    import numpy
+    import scipy
+
+    print(f"ayar {__version__}")
+    print(f"python {platform.python_version()} ({sys.executable})")
+    print(f"numpy {numpy.__version__}, scipy {scipy.__version__}")
+    for mod in ("spikeinterface", "pynwb", "daftar"):
+        try:
+            m = __import__(mod)
+            print(f"{mod} {getattr(m, '__version__', '?')} (adapter planned)")
+        except ImportError:
+            print(f"{mod}: not installed (optional)")
+    from .examples import condition_contrast
+    from .scan import scan
+    from .synth import make_session
+
+    b = make_session(0)
+    r = scan(b, condition_contrast)
+    planted = {(t["code"], frozenset(t["units"])) for t in b.meta["truth"]}
+    found = {(f.code, frozenset(f.units)) for f in r.flags}
+    ok = planted <= found
+    print(f"self-check: {len(planted & found)}/{len(planted)} planted artifacts found "
+          f"in a 600 s synthetic session -> {'ok' if ok else 'PROBLEM'}")
+    return 0 if ok else 1
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="ayar",
+        description="Assay your spike-sorted finding before you publish.",
+    )
+    p.add_argument("--version", action="version", version=f"ayar {__version__}")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    s = sub.add_parser("scan", help="flag sorting artifacts and audit a finding")
+    s.add_argument("bundle", help="a .npz bundle or a Phy/Kilosort output folder")
+    s.add_argument("--finding", help="your analysis: file.py:func or module:func")
+    s.add_argument("--events", help=".npz with 'times' (s) and optional 'labels' arrays")
+    s.add_argument("--sample-rate", type=float, help="for Phy folders without params.py")
+    s.add_argument("--only", nargs="+", metavar="CODE", help="run only these detectors")
+    s.add_argument("--set", action="append", metavar="NAME=VALUE", help="override a threshold")
+    s.add_argument("--format", choices=["text", "json"], default="text")
+    s.add_argument("--json", metavar="PATH", help="also write the JSON report here")
+    s.add_argument("--fail-on", choices=["error", "warning", "never"], default="error",
+                   help="exit 1 when flags reach this severity (default: error)")
+    s.add_argument("-v", "--verbose", action="store_true", help="explain every flag")
+    s.set_defaults(fn=cmd_scan)
+
+    y = sub.add_parser("synth", help="write a synthetic session with planted artifacts")
+    y.add_argument("out", help="output .npz path")
+    y.add_argument("--seed", type=int, default=0)
+    y.add_argument("--units", type=int, default=40)
+    y.add_argument("--duration", type=float, default=600.0)
+    y.add_argument("--design", choices=["block", "interleaved"], default="block")
+    y.set_defaults(fn=cmd_synth)
+
+    v = sub.add_parser("validate", help="measure detector accuracy on synthetic sessions")
+    v.add_argument("--sessions", type=int, default=5)
+    v.add_argument("--seed", type=int, default=0)
+    v.add_argument("--duration", type=float, default=600.0)
+    v.add_argument("--min-sensitivity", type=float, default=0.8)
+    v.add_argument("--min-precision", type=float, default=0.8)
+    v.add_argument("--set", action="append", metavar="NAME=VALUE")
+    v.add_argument("--format", choices=["text", "json"], default="text")
+    v.set_defaults(fn=cmd_validate)
+
+    i = sub.add_parser("info", help="summarise a bundle")
+    i.add_argument("bundle")
+    i.set_defaults(fn=cmd_info)
+
+    d = sub.add_parser("doctor", help="check the installation")
+    d.set_defaults(fn=cmd_doctor)
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    return args.fn(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())