aver-comparator 0.1.0__py3-none-any.whl

aver_comparator/__init__.py

@@ -0,0 +1 @@
+"""Aver hap.py/vcfeval wrapper and metric normalisation (F-31). Arrives in M0."""

aver_comparator/happy.py

@@ -0,0 +1,222 @@
+"""hap.py (vcfeval engine) invocation and output normalisation.
+
+PRD §13.3 (fixed invocation shape), §13.4 (field mapping), ADR-005 (container
+pinned by digest; never pip-installed). F-31: SNV and INDEL metrics restricted
+to the confident-region BED; the raw bundle is retained.
+"""
+
+from __future__ import annotations
+
+import csv
+import io
+import math
+import shlex
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import PurePosixPath
+
+from aver_core.models import BenchmarkMetric
+
+# §13.4 mapping: hap.py column -> Aver field
+FIELD_MAP = {
+    "TRUTH.TOTAL": "truth_total",
+    "TRUTH.TP": "truth_tp",
+    "TRUTH.FN": "truth_fn",
+    "QUERY.TOTAL": "query_total",
+    "QUERY.FP": "query_fp",
+    "METRIC.Recall": "recall",
+    "METRIC.Precision": "precision",
+    "METRIC.F1_Score": "f_measure",
+}
+REQUIRED = {"Type", "Filter", *FIELD_MAP}
+COUNT_FIELDS = {"truth_total", "truth_tp", "truth_fn", "query_total", "query_fp"}
+
+
+class HappyOutputError(ValueError):
+    """summary.csv is missing, malformed or internally inconsistent."""
+
+
+def parse_summary_csv(text: str) -> tuple[BenchmarkMetric, ...]:
+    """Parse hap.py `<prefix>.summary.csv` into canonical metric rows.
+
+    Returns rows for SNP and INDEL, for both PASS and ALL filters, in a fixed
+    order (SNP/PASS, SNP/ALL, INDEL/PASS, INDEL/ALL). Headline metrics use PASS;
+    ALL rows are kept for completeness (§13.4). Every other column is preserved
+    verbatim in `extra`, so nothing hap.py reported is lost.
+    """
+    reader = csv.DictReader(io.StringIO(text))
+    header = set(reader.fieldnames or [])
+    missing = REQUIRED - header
+    if missing:
+        raise HappyOutputError(f"summary.csv lacks columns: {', '.join(sorted(missing))}")
+    rows: dict[tuple[str, str], BenchmarkMetric] = {}
+    for raw in reader:
+        vclass, filt = raw["Type"], raw["Filter"]
+        if vclass not in ("SNP", "INDEL") or filt not in ("PASS", "ALL"):
+            raise HappyOutputError(f"unexpected row Type={vclass!r} Filter={filt!r}")
+        if (vclass, filt) in rows:
+            raise HappyOutputError(f"duplicate row {vclass}/{filt}")
+        values: dict[str, object] = {}
+        for col, field in FIELD_MAP.items():
+            cell = (raw[col] or "").strip()
+            if field in COUNT_FIELDS:
+                if not cell.isdigit():
+                    raise HappyOutputError(f"{vclass}/{filt} {col}={cell!r} is not a count")
+                values[field] = int(cell)
+            else:
+                values[field] = _metric(cell, f"{vclass}/{filt} {col}")
+        if values["truth_tp"] + values["truth_fn"] != values["truth_total"]:  # type: ignore[operator]
+            raise HappyOutputError(f"{vclass}/{filt}: TRUTH.TP + TRUTH.FN != TRUTH.TOTAL")
+        extra = {k: v for k, v in raw.items() if k not in REQUIRED and k is not None and v is not None}
+        rows[(vclass, filt)] = BenchmarkMetric(
+            variant_class=vclass,
+            filter=filt,
+            extra=dict(sorted(extra.items())),
+            **values,  # type: ignore[arg-type]
+        )
+    order = [("SNP", "PASS"), ("SNP", "ALL"), ("INDEL", "PASS"), ("INDEL", "ALL")]
+    absent = [f"{c}/{f}" for c, f in order if (c, f) not in rows]
+    if absent:
+        raise HappyOutputError(f"summary.csv lacks rows: {', '.join(absent)}")
+    return tuple(rows[k] for k in order)
+
+
+def _count(cell: str, where: str) -> int:
+    """hap.py writes some counts as '123.000000' in extended.csv; accept only integral values."""
+    try:
+        v = float(cell)
+    except ValueError as e:
+        raise HappyOutputError(f"{where}={cell!r} is not a count") from e
+    if v < 0 or v != int(v):
+        raise HappyOutputError(f"{where}={cell!r} is not a count")
+    return int(v)
+
+
+EXTENDED_REQUIRED = {"Type", "Subtype", "Subset", "Filter", "Genotype", *FIELD_MAP}
+
+
+def parse_extended_csv(text: str, subsets: Sequence[str]) -> tuple[BenchmarkMetric, ...]:
+    """Per-stratification rows from hap.py `<prefix>.extended.csv` (F-32).
+
+    Keeps the rows for each requested subset aggregated over subtypes and genotypes
+    (`Subtype == Genotype == '*'`), in the order: subset as requested, then SNP/PASS,
+    SNP/ALL, INDEL/PASS, INDEL/ALL. A requested subset with no rows is an error, so a
+    stratification can never silently disappear from a report.
+    """
+    reader = csv.DictReader(io.StringIO(text))
+    missing = EXTENDED_REQUIRED - set(reader.fieldnames or [])
+    if missing:
+        raise HappyOutputError(f"extended.csv lacks columns: {', '.join(sorted(missing))}")
+    wanted = set(subsets)
+    rows: dict[tuple[str, str, str], BenchmarkMetric] = {}
+    for raw in reader:
+        sub = raw["Subset"]
+        if sub not in wanted or raw["Subtype"] != "*" or raw["Genotype"] != "*":
+            continue
+        vclass, filt = raw["Type"], raw["Filter"]
+        if vclass not in ("SNP", "INDEL") or filt not in ("PASS", "ALL"):
+            continue
+        where = f"{sub} {vclass}/{filt}"
+        values: dict[str, object] = {}
+        for col, field in FIELD_MAP.items():
+            cell = (raw[col] or "").strip()
+            values[field] = _count(cell, f"{where} {col}") if field in COUNT_FIELDS else _metric(cell, f"{where} {col}")
+        if values["truth_tp"] + values["truth_fn"] != values["truth_total"]:  # type: ignore[operator]
+            raise HappyOutputError(f"{where}: TRUTH.TP + TRUTH.FN != TRUTH.TOTAL")
+        if (sub, vclass, filt) in rows:
+            raise HappyOutputError(f"duplicate row {where}")
+        keep = ("Subset.Size", "Subset.IS_CONF.Size")
+        rows[(sub, vclass, filt)] = BenchmarkMetric(
+            variant_class=vclass,
+            filter=filt,
+            stratification=sub,
+            extra={k: raw[k] for k in keep if raw.get(k)},
+            **values,  # type: ignore[arg-type]
+        )
+    out = []
+    for sub in subsets:
+        for key in (("SNP", "PASS"), ("SNP", "ALL"), ("INDEL", "PASS"), ("INDEL", "ALL")):
+            if (sub, *key) not in rows:
+                raise HappyOutputError(f"extended.csv lacks {sub} {key[0]}/{key[1]}")
+            out.append(rows[(sub, *key)])
+    return tuple(out)
+
+
+def _metric(cell: str, where: str) -> float | None:
+    if cell == "" or cell.lower() == "nan":
+        return None  # hap.py writes nan when a denominator is zero
+    try:
+        v = float(cell)
+    except ValueError as e:
+        raise HappyOutputError(f"{where}={cell!r} is not a number") from e
+    if not (0.0 <= v <= 1.0) or math.isnan(v):
+        raise HappyOutputError(f"{where}={cell!r} outside [0, 1]")
+    return v
+
+
+def headline(metrics: Sequence[BenchmarkMetric]) -> dict[str, BenchmarkMetric]:
+    """Whole-region PASS rows keyed by variant class: the numbers that are reported.
+
+    Stratified rows (F-32) are never headline numbers.
+    """
+    return {m.variant_class: m for m in metrics if m.filter == "PASS" and m.stratification is None}
+
+
+@dataclass(frozen=True)
+class HappyInvocation:
+    """The §13.3 command, run inside the digest-pinned comparator image.
+
+    Paths are container paths under /data (inputs, read-only) and /out.
+    """
+
+    image: str  # repo@sha256:... (ADR-005)
+    truth_vcf: str
+    query_vcf: str
+    confident_bed: str
+    reference_fasta: str
+    output_prefix: str
+    sdf: str | None = None
+    target_bed: str | None = None
+    stratification_tsv: str | None = None
+    threads: int = 4
+    locations: str | None = None  # e.g. 'chr20'
+
+    def __post_init__(self) -> None:
+        if "@sha256:" not in self.image:
+            raise ValueError("comparator image must be pinned by digest (ADR-005)")
+
+    def happy_args(self) -> list[str]:
+        args = ["/opt/hap.py/bin/hap.py", self.truth_vcf, self.query_vcf]
+        args += ["-f", self.confident_bed, "-r", self.reference_fasta]
+        if self.target_bed:
+            args += ["-T", self.target_bed]
+        if self.locations:
+            args += ["-l", self.locations]
+        args += ["--engine=vcfeval"]
+        if self.sdf:
+            args += ["--engine-vcfeval-template", self.sdf]
+        if self.stratification_tsv:
+            args += ["--stratification", self.stratification_tsv]
+        args += ["--roc", "QUAL", "--threads", str(self.threads), "-o", self.output_prefix]
+        return args
+
+    def command_line(self) -> str:
+        """The exact command recorded on the run (F-30 AC-2)."""
+        return shlex.join(self.happy_args())
+
+    def docker_args(self, data_dir: str, out_dir: str) -> list[str]:
+        for p in (self.truth_vcf, self.query_vcf, self.confident_bed, self.reference_fasta):
+            if not PurePosixPath(p).is_relative_to("/data"):
+                raise ValueError(f"{p} must be under /data")
+        return [
+            "docker",
+            "run",
+            "--rm",
+            "--network=none",
+            "-v",
+            f"{data_dir}:/data:ro",
+            "-v",
+            f"{out_dir}:/out",
+            self.image,
+            *self.happy_args(),
+        ]

aver_comparator/pgx.py

@@ -0,0 +1,125 @@
+"""Pharmacogene diplotype concordance (M8.2, docs/plans/M8-platform-deepening.md).
+
+A laboratory's star-allele calls for one public GeT-RM Coriell sample are
+compared against the published consensus. The comparison is deliberately
+conservative and fully explained:
+
+- a diplotype matches when its '/'-separated alleles are the same set
+  (diplotypes are unordered: *1/*2 equals *2/*1), after whitespace
+  normalisation and case folding — nothing else is interpreted;
+- a consensus value offering alternatives ("x or y") matches when the call
+  matches any alternative;
+- anything the lab calls that the consensus does not characterise is
+  `not_characterized`, and a characterised gene the lab did not call is
+  `not_called` — neither is a match or a mismatch, and both are reported.
+
+Invariant 1: the sample must be a sample in the consensus table (a public
+Coriell line); an unknown sample aborts without echoing the name. Invariant 9
+in spirit: every row carries both strings verbatim, so the judgement is
+checkable by eye.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+
+class PgxSampleError(ValueError):
+    """The named sample is not in the consensus table (never echoed: it could be an identifier)."""
+
+
+class PgxGeneError(ValueError):
+    pass
+
+
+@dataclass(frozen=True)
+class PgxRow:
+    gene: str  # the consensus table's gene name
+    called: str | None  # the laboratory's verbatim call
+    consensus: str | None  # the verbatim consensus value
+    status: str  # match | mismatch | not_characterized | not_called
+
+    def as_dict(self) -> dict[str, str | None]:
+        return {"gene": self.gene, "called": self.called, "consensus": self.consensus, "status": self.status}
+
+
+@dataclass(frozen=True)
+class PgxConcordance:
+    sample: str
+    consensus_set: str
+    rows: tuple[PgxRow, ...]
+
+    @property
+    def counts(self) -> dict[str, int]:
+        out = {"match": 0, "mismatch": 0, "not_characterized": 0, "not_called": 0}
+        for r in self.rows:
+            out[r.status] += 1
+        return out
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "sample": self.sample,
+            "consensus_set": self.consensus_set,
+            "rows": [r.as_dict() for r in self.rows],
+            "counts": self.counts,
+        }
+
+
+def _norm(diplotype: str) -> tuple[str, ...]:
+    parts = [p.strip().lower() for p in " ".join(diplotype.split()).split("/")]
+    return tuple(sorted(p for p in parts if p))
+
+
+def diplotypes_match(called: str, consensus: str) -> bool:
+    alternatives = [a for a in consensus.split(" or ") if a.strip()] or [consensus]
+    return any(_norm(called) == _norm(a) for a in alternatives)
+
+
+def resolve_gene(lab_name: str, genes: tuple[str, ...]) -> str:
+    """The consensus gene for a laboratory's gene name: exact (case-insensitive),
+    else the unique gene whose name starts with `lab_name` + space (long locus
+    headers such as the CYP2C cluster). Ambiguity is an error, never a guess."""
+    wanted = " ".join(lab_name.split()).lower()
+    exact = [g for g in genes if g.lower() == wanted]
+    if exact:
+        return exact[0]
+    prefixed = [g for g in genes if g.lower().startswith(wanted + " ")]
+    if len(prefixed) == 1:
+        return prefixed[0]
+    if prefixed:
+        raise PgxGeneError(f"gene name {lab_name!r} is ambiguous in the consensus table: {', '.join(sorted(prefixed))}")
+    raise PgxGeneError(f"gene {lab_name!r} is not in the consensus table")
+
+
+def concordance(
+    sample: str,
+    calls: Mapping[str, str],
+    *,
+    consensus_set: str,
+    genes: tuple[str, ...],
+    consensus_for_sample: Mapping[str, str],
+) -> PgxConcordance:
+    """Every called gene judged against the consensus, plus every characterised
+    gene the laboratory did not call. `consensus_for_sample` maps the consensus
+    table's gene names to verbatim values for this sample."""
+    if not calls:
+        raise PgxGeneError("no gene calls supplied")
+    rows: list[PgxRow] = []
+    called_genes: set[str] = set()
+    for lab_name in sorted(calls):
+        gene = resolve_gene(lab_name, genes)
+        if gene in called_genes:
+            raise PgxGeneError(f"gene {gene!r} is called more than once")
+        called_genes.add(gene)
+        called = " ".join(str(calls[lab_name]).split())
+        cons = consensus_for_sample.get(gene)
+        if cons is None:
+            rows.append(PgxRow(gene, called, None, "not_characterized"))
+        else:
+            rows.append(PgxRow(gene, called, cons, "match" if diplotypes_match(called, cons) else "mismatch"))
+    for gene in sorted(consensus_for_sample):
+        if gene not in called_genes:
+            rows.append(PgxRow(gene, None, consensus_for_sample[gene], "not_called"))
+    rows.sort(key=lambda r: r.gene)
+    return PgxConcordance(sample=sample, consensus_set=consensus_set, rows=tuple(rows))

aver_comparator/somatic.py

@@ -0,0 +1,173 @@
+"""som.py invocation and output normalisation for somatic truth sets (M7, ADR-014).
+
+som.py ships in the same digest-pinned comparator image as hap.py (ADR-005) and is
+the comparison tool the SEQC2 publications themselves use. It compares a somatic
+query against a truth call set without genotype matching and, by default, counts
+PASS query records only — so rows are recorded with filter="PASS", honestly, and
+there is no ALL split unless a future need adds a second -P run.
+
+The stats.csv layout was verified against the pinned image's real output
+(2026-10-12): an unnamed index column, then type/total.truth/total.query/tp/fp/
+fn/unk/ambi/recall/.../sompyversion/sompycmd, with rows 'SNVs', 'indels' and the
+aggregate 'records'.
+"""
+
+from __future__ import annotations
+
+import csv
+import io
+import math
+import shlex
+from dataclasses import dataclass
+from pathlib import PurePosixPath
+
+from aver_core.models import BenchmarkMetric
+
+TYPE_MAP = {"SNVs": "SNP", "indels": "INDEL", "records": "ALL"}
+COUNTS = {
+    "total.truth": "truth_total",
+    "tp": "truth_tp",
+    "fn": "truth_fn",
+    "total.query": "query_total",
+    "fp": "query_fp",
+}
+RATES = {"recall": "recall", "precision": "precision"}
+REQUIRED = {"type", *COUNTS, *RATES}
+# Kept verbatim in `extra` so nothing som.py reported is lost; sompycmd is excluded
+# (the executed command is recorded on the run itself, F-30 AC-2).
+EXTRA = (
+    "unk",
+    "ambi",
+    "recall_lower",
+    "recall_upper",
+    "precision_lower",
+    "precision_upper",
+    "fp.region.size",
+    "fp.rate",
+    "sompyversion",
+)
+
+
+class SompyOutputError(ValueError):
+    """stats.csv is missing, malformed or internally inconsistent."""
+
+
+def parse_sompy_stats(text: str) -> tuple[BenchmarkMetric, ...]:
+    """Canonical metric rows from som.py `<prefix>.stats.csv`.
+
+    Returns the rows som.py wrote, ordered SNP, INDEL, ALL (filter="PASS";
+    som.py's default comparison counts PASS query records only). Against a
+    per-class truth set som.py omits the other class's row entirely — verified
+    on a real SEQC2 sSNV run 2026-10-13 — so only the aggregate 'records' row
+    is required; the caller decides which class rows it needs. f_measure is
+    computed from recall and precision, since som.py does not report it.
+    """
+    reader = csv.DictReader(io.StringIO(text))
+    header = set(reader.fieldnames or [])
+    missing = REQUIRED - header
+    if missing:
+        raise SompyOutputError(f"stats.csv lacks columns: {', '.join(sorted(missing))}")
+    rows: dict[str, BenchmarkMetric] = {}
+    for raw in reader:
+        kind = (raw.get("type") or "").strip()
+        vclass = TYPE_MAP.get(kind)
+        if vclass is None:
+            continue  # future som.py row kinds are ignored, never guessed at
+        if vclass in rows:
+            raise SompyOutputError(f"duplicate row for {kind}")
+        where = f"{kind}"
+        values: dict[str, object] = {}
+        for col, field in COUNTS.items():
+            values[field] = _count((raw[col] or "").strip(), f"{where} {col}")
+        for col, field in RATES.items():
+            values[field] = _rate((raw[col] or "").strip(), f"{where} {col}")
+        if values["truth_tp"] + values["truth_fn"] != values["truth_total"]:  # type: ignore[operator]
+            raise SompyOutputError(f"{where}: tp + fn != total.truth")
+        r, p = values["recall"], values["precision"]
+        f1 = (2 * r * p / (r + p)) if isinstance(r, float) and isinstance(p, float) and (r + p) > 0 else None  # type: ignore[operator]
+        rows[vclass] = BenchmarkMetric(
+            variant_class=vclass,
+            filter="PASS",
+            f_measure=f1,
+            extra={k: raw[k].strip() for k in EXTRA if raw.get(k, "").strip()},
+            **values,  # type: ignore[arg-type]
+        )
+    if "ALL" not in rows:
+        raise SompyOutputError("stats.csv lacks the aggregate 'records' row")
+    return tuple(rows[c] for c in ("SNP", "INDEL", "ALL") if c in rows)
+
+
+def _count(cell: str, where: str) -> int:
+    try:
+        v = float(cell)
+    except ValueError as e:
+        raise SompyOutputError(f"{where}={cell!r} is not a count") from e
+    if v < 0 or v != int(v):
+        raise SompyOutputError(f"{where}={cell!r} is not a count")
+    return int(v)
+
+
+def _rate(cell: str, where: str) -> float | None:
+    if cell == "" or cell.lower() == "nan":
+        return None  # zero denominator
+    try:
+        v = float(cell)
+    except ValueError as e:
+        raise SompyOutputError(f"{where}={cell!r} is not a number") from e
+    if not (0.0 <= v <= 1.0) or math.isnan(v):
+        raise SompyOutputError(f"{where}={cell!r} outside [0, 1]")
+    return v
+
+
+@dataclass(frozen=True)
+class SompyInvocation:
+    """The som.py command, run inside the digest-pinned comparator image.
+
+    `truth_vcf` is one per-class SEQC2 call set; a somatic comparison runs som.py
+    once per class VCF and keeps that class's row. Paths are container paths under
+    /data (read-only) and /out.
+    """
+
+    image: str  # repo@sha256:... (ADR-005)
+    truth_vcf: str
+    query_vcf: str
+    fp_regions_bed: str  # the high-confidence BED: calls outside it are UNK, not FP
+    reference_fasta: str
+    output_prefix: str
+    target_bed: str | None = None
+    location: str | None = None  # e.g. 'chr20'
+
+    def __post_init__(self) -> None:
+        if "@sha256:" not in self.image:
+            raise ValueError("comparator image must be pinned by digest (ADR-005)")
+
+    def sompy_args(self) -> list[str]:
+        args = ["/opt/hap.py/bin/som.py", self.truth_vcf, self.query_vcf]
+        args += ["-r", self.reference_fasta, "-f", self.fp_regions_bed]
+        if self.target_bed:
+            args += ["-T", self.target_bed]
+        if self.location:
+            args += ["-l", self.location]
+        args += ["-o", self.output_prefix]
+        return args
+
+    def command_line(self) -> str:
+        """The exact command recorded on the run (F-30 AC-2)."""
+        return shlex.join(self.sompy_args())
+
+    def docker_args(self, data_dir: str, out_dir: str) -> list[str]:
+        for p in (self.truth_vcf, self.query_vcf, self.fp_regions_bed, self.reference_fasta):
+            if not PurePosixPath(p).is_relative_to("/data"):
+                raise ValueError(f"{p} must be under /data")
+        return [
+            "docker",
+            "run",
+            "--rm",
+            "--network=none",
+            "-v",
+            f"{data_dir}:/data:ro",
+            "-v",
+            f"{out_dir}:/out",
+            self.image,
+            *self.sompy_args(),
+        ]

aver_comparator/sv.py

@@ -0,0 +1,122 @@
+"""truvari invocation and output normalisation for SV truth sets (M8.3, docs/plans/M8-platform-deepening.md).
+
+truvari is the tool the GIAB SV README itself recommends (with `--passonly
+--includebed <Tier1 bed> -r 2000`); it runs from its own digest-pinned
+container (ADR-005). Its `summary.json` reports base/comp counts, TP/FP/FN
+and precision/recall/F1 directly; rows map onto BenchmarkMetric with
+variant_class='SV' and filter='PASS' (truvari compares PASS records under
+--passonly). Every other summary field is preserved stringified in `extra`.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import shlex
+from dataclasses import dataclass
+from pathlib import PurePosixPath
+
+from aver_core.models import BenchmarkMetric
+
+
+class TruvariOutputError(ValueError):
+    """summary.json is missing, malformed or internally inconsistent."""
+
+
+def parse_truvari_summary(text: str) -> BenchmarkMetric:
+    try:
+        data = json.loads(text)
+    except ValueError as e:
+        raise TruvariOutputError(f"summary.json is not valid JSON: {e}") from e
+    if not isinstance(data, dict):
+        raise TruvariOutputError("summary.json is not an object")
+
+    def count(key: str) -> int:
+        v = data.get(key)
+        if not isinstance(v, (int, float)) or isinstance(v, bool) or v < 0 or v != int(v):
+            raise TruvariOutputError(f"summary.json {key}={v!r} is not a count")
+        return int(v)
+
+    def rate(key: str) -> float | None:
+        v = data.get(key)
+        if v is None:
+            return None
+        if not isinstance(v, (int, float)) or isinstance(v, bool) or math.isnan(v) or not 0.0 <= v <= 1.0:
+            raise TruvariOutputError(f"summary.json {key}={v!r} is not a rate in [0, 1]")
+        return float(v)
+
+    base, tp_base, fn = count("base cnt"), count("TP-base"), count("FN")
+    comp, fp = count("comp cnt"), count("FP")
+    if tp_base + fn != base:
+        raise TruvariOutputError("summary.json: TP-base + FN != base cnt")
+    used = {"base cnt", "TP-base", "FN", "comp cnt", "FP", "precision", "recall", "f1"}
+    extra = {
+        k: json.dumps(v, sort_keys=True) if isinstance(v, (dict, list)) else str(v)
+        for k, v in sorted(data.items())
+        if k not in used
+    }
+    return BenchmarkMetric(
+        variant_class="SV",
+        filter="PASS",
+        truth_total=base,
+        truth_tp=tp_base,
+        truth_fn=fn,
+        query_total=comp,
+        query_fp=fp,
+        recall=rate("recall"),
+        precision=rate("precision"),
+        f_measure=rate("f1"),
+        extra=extra,
+    )
+
+
+@dataclass(frozen=True)
+class TruvariInvocation:
+    """`truvari bench` exactly as the GIAB SV README recommends, in the pinned container.
+
+    Paths are container paths under /data (read-only); truvari creates
+    `/out/<output_name>` itself and refuses to overwrite it.
+    """
+
+    image: str  # repo@sha256:... (ADR-005)
+    truth_vcf: str
+    query_vcf: str
+    include_bed: str
+    output_name: str = "truvari"
+    refdist: int = 2000  # the README's -r 2000
+    sequence_comparison: bool = True  # False adds --pctseq 0 (size/type matching only, per the README)
+
+    def __post_init__(self) -> None:
+        if "@sha256:" not in self.image:
+            raise ValueError("comparator image must be pinned by digest (ADR-005)")
+
+    def truvari_args(self) -> list[str]:
+        args = ["truvari", "bench", "-b", self.truth_vcf, "-c", self.query_vcf]
+        args += ["--includebed", self.include_bed, "--passonly", "-r", str(self.refdist)]
+        # truvari 4 requires chunksize >= refdist (its default chunksize is 1000).
+        args += ["--chunksize", str(max(self.refdist, 1000))]
+        if not self.sequence_comparison:
+            args += ["--pctseq", "0"]
+        args += ["-o", f"/out/{self.output_name}"]
+        return args
+
+    def command_line(self) -> str:
+        """The exact command recorded on the run (F-30 AC-2)."""
+        return shlex.join(self.truvari_args())
+
+    def docker_args(self, data_dir: str, out_dir: str) -> list[str]:
+        for p in (self.truth_vcf, self.query_vcf, self.include_bed):
+            if not PurePosixPath(p).is_relative_to("/data"):
+                raise ValueError(f"{p} must be under /data")
+        return [
+            "docker",
+            "run",
+            "--rm",
+            "--network=none",
+            "-v",
+            f"{data_dir}:/data:ro",
+            "-v",
+            f"{out_dir}:/out",
+            self.image,
+            *self.truvari_args(),
+        ]

aver_comparator-0.1.0.dist-info/METADATA

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: aver-comparator
+Version: 0.1.0
+Summary: Aver hap.py/vcfeval wrapper and metric normalisation (F-31). Arrives in M0.
+License-Expression: Apache-2.0
+Requires-Dist: aver-core
+Requires-Python: >=3.11

aver_comparator-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+aver_comparator/__init__.py,sha256=X_Z7c_j4h1qcfkzF4wTFeloq6oq4jRwPsSLVpG69Io4,82
+aver_comparator/happy.py,sha256=KZW_MWb7pyx7QtX1T76f0Tc3Na8A4Ht_1T2hMAUBYeA,8967
+aver_comparator/pgx.py,sha256=CcsY-FXcA0Z_MR0oGMVuoGf11YiWyQt0JygTJzRbWOE,4885
+aver_comparator/somatic.py,sha256=SBfXVYskHRvGj0qyGy2pVzek300o7v3H9XVP1PH5jnA,6534
+aver_comparator/sv.py,sha256=sRSmsDPOYHmKtNHyUy5hTEv0TfMOD0vTkl-sZYpeQYc,4487
+aver_comparator-0.1.0.dist-info/WHEEL,sha256=7hzKWg-J8I3Buqyw5tBii5z_MmAVsDYXXijd_QAtNZ8,81
+aver_comparator-0.1.0.dist-info/METADATA,sha256=hbT0n_X2VP1CHIqNSX0JdMAUEFlrke78l8-wKBz9ZkA,224
+aver_comparator-0.1.0.dist-info/RECORD,,

aver_comparator-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.12.18
+Root-Is-Purelib: true
+Tag: py3-none-any