diff --git a/pairplex/tests/data/golden/expected/consensus.parquet b/pairplex/tests/data/golden/expected/consensus.parquet new file mode 100644 index 0000000..2a5fc79 Binary files /dev/null and b/pairplex/tests/data/golden/expected/consensus.parquet differ diff --git a/pairplex/tests/data/golden/expected/metadata.parquet b/pairplex/tests/data/golden/expected/metadata.parquet new file mode 100644 index 0000000..8d7ae69 Binary files /dev/null and b/pairplex/tests/data/golden/expected/metadata.parquet differ diff --git a/pairplex/tests/data/golden/expected/paired.parquet b/pairplex/tests/data/golden/expected/paired.parquet new file mode 100644 index 0000000..813398b Binary files /dev/null and b/pairplex/tests/data/golden/expected/paired.parquet differ diff --git a/pairplex/tests/data/golden/expected/unpaired.parquet b/pairplex/tests/data/golden/expected/unpaired.parquet new file mode 100644 index 0000000..b685ce6 Binary files /dev/null and b/pairplex/tests/data/golden/expected/unpaired.parquet differ diff --git a/pairplex/tests/data/golden/expected/versions.json b/pairplex/tests/data/golden/expected/versions.json new file mode 100644 index 0000000..38c5992 --- /dev/null +++ b/pairplex/tests/data/golden/expected/versions.json @@ -0,0 +1,11 @@ +{ + "code_commit": "a8b6376cd9e3333aa6d6b1c1415bc6dddc8a0233", + "abstar": "0.9.0", + "run_kwargs": {}, + "rows": { + "metadata": 140, + "consensus": 111, + "unpaired": 111, + "paired": 24 + } +} \ No newline at end of file diff --git a/pairplex/tests/data/golden/input/well000.fastq.gz b/pairplex/tests/data/golden/input/well000.fastq.gz new file mode 100644 index 0000000..dbf7f5e Binary files /dev/null and b/pairplex/tests/data/golden/input/well000.fastq.gz differ diff --git a/pairplex/tests/data/golden/input/well001.fastq.gz b/pairplex/tests/data/golden/input/well001.fastq.gz new file mode 100644 index 0000000..d3845b5 Binary files /dev/null and b/pairplex/tests/data/golden/input/well001.fastq.gz differ diff --git a/pairplex/tests/data/golden/make_golden.py b/pairplex/tests/data/golden/make_golden.py new file mode 100644 index 0000000..a447356 --- /dev/null +++ b/pairplex/tests/data/golden/make_golden.py @@ -0,0 +1,38 @@ +"""Regenerate the golden expected tables. Run ONLY when an output change is intended and reviewed. + + python pairplex/tests/data/golden/make_golden.py # from the repo root + +Records the code commit and the abstar version used. Use legacy mode if the checkout has it, so +the golden tables always describe the reference (pre-v2) behaviour. +""" + +import inspect +import json +import subprocess +import sys +import tempfile +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[4] +sys.path.insert(0, str(ROOT)) + +import pairplex.pairplex as ppx # noqa: E402 +from pairplex.tests.golden import EXPECTED, abstar_version, extract, run_pairplex # noqa: E402 + + +def main(): + kwargs = {"legacy": True} if "legacy" in inspect.signature(ppx.run).parameters else {} + with tempfile.TemporaryDirectory() as tmp: + tables = extract(run_pairplex(Path(tmp), **kwargs)) + EXPECTED.mkdir(parents=True, exist_ok=True) + for name, df in tables.items(): + df.write_parquet(EXPECTED / f"{name}.parquet") + commit = subprocess.run(["git", "-C", str(ROOT), "rev-parse", "HEAD"], capture_output=True, text=True).stdout.strip() + (EXPECTED / "versions.json").write_text(json.dumps( + {"code_commit": commit, "abstar": abstar_version(), "run_kwargs": kwargs, + "rows": {k: v.height for k, v in tables.items()}}, indent=1)) + print({k: v.height for k, v in tables.items()}) + + +if __name__ == "__main__": + main() diff --git a/pairplex/tests/golden.py b/pairplex/tests/golden.py new file mode 100644 index 0000000..7108c60 --- /dev/null +++ b/pairplex/tests/golden.py @@ -0,0 +1,100 @@ +"""Golden-output helpers: run PairPlex on a tiny fixed input and reduce outputs to comparable tables. + +The input (``data/golden/input``) is two simulated wells, each under 1000 reads. That is a single +1000-read chunk per well, so read order into clustering is deterministic. The expected tables +(``data/golden/expected``) were produced by the reference code named in ``versions.json``; +regenerate them only on purpose, with ``make_golden.py``. +""" + +from __future__ import annotations + +import json +import os +import shutil +from importlib import metadata +from pathlib import Path + +import polars as pl + +GOLDEN = Path(__file__).parent / "data" / "golden" +INPUT = GOLDEN / "input" +EXPECTED = GOLDEN / "expected" + +META_COLS = ["name", "reads", "umis", "cluster_fraction", "consensus", "pass_filters"] +UNPAIRED_COLS = ["sequence_id", "sequence", "locus", "productive", "v_gene", "j_gene", "junction", "cdr3_aa"] +PAIRED_COLS = ["name", "sequence_id:0", "sequence_id:1", "locus:0", "locus:1"] +# annotation calls that may legitimately change with the abstar version / germline database +ANNOTATION_CALLS = ["productive", "v_gene", "j_gene", "junction", "cdr3_aa"] + + +def run_pairplex(output_directory: Path, **kwargs) -> Path: + """Run PairPlex on a copy of the golden input with 2 workers; returns the output directory.""" + import pairplex.pairplex as ppx + + work = Path(output_directory) + inp = work / "input" + shutil.copytree(INPUT, inp) + old = os.environ.get("PAIRPLEX_MAX_WORKERS") + os.environ["PAIRPLEX_MAX_WORKERS"] = "2" + try: + ppx.run(str(inp), str(work / "out"), quiet=True, **kwargs) + finally: + if old is None: + os.environ.pop("PAIRPLEX_MAX_WORKERS", None) + else: + os.environ["PAIRPLEX_MAX_WORKERS"] = old + return work / "out" + + +def _well(path: Path) -> str: + return path.name.split(".")[0] + + +def extract(out: Path) -> dict[str, pl.DataFrame]: + """Reduce a PairPlex output directory to order-independent tables.""" + out = Path(out) + meta, cons, unp, par = [], [], [], [] + for f in sorted((out / "metadata").glob("*.csv")): + d = pl.read_csv(f) + if d.height: + meta.append(d.select(META_COLS).with_columns(pl.lit(_well(f)).alias("well"), + pl.col("cluster_fraction").round(6))) + for f in sorted((out / "consensus").glob("*.fasta")): + name = None + for line in f.read_text().splitlines(): + if line.startswith(">"): + name = line[1:].strip() + elif name: + cons.append({"well": _well(f), "name": name, "sequence": line.strip()}) + name = None + for f in sorted((out / "annotated").glob("*_unpaired.parquet")): + d = pl.read_parquet(f) + if d.height: + unp.append(d.select([c for c in UNPAIRED_COLS if c in d.columns]).with_columns(pl.lit(_well(f)).alias("well"))) + for f in sorted((out / "annotated").glob("*_paired.parquet")): + d = pl.read_parquet(f) + if d.height: + par.append(d.select(PAIRED_COLS).with_columns(pl.lit(_well(f)).alias("well"))) + + def cat(frames, keys): + return pl.concat(frames, how="vertical_relaxed").sort(keys) if frames else pl.DataFrame() + + return { + "metadata": cat(meta, ["well", "name"]), + "consensus": pl.DataFrame(cons).sort(["well", "name"]) if cons else pl.DataFrame(), + "unpaired": cat(unp, ["well", "sequence_id"]), + "paired": cat(par, ["well", "name"]), + } + + +def abstar_version() -> str | None: + try: + return metadata.version("abstar") + except metadata.PackageNotFoundError: + return None + + +def load_expected() -> tuple[dict[str, pl.DataFrame], dict]: + tables = {p.stem: pl.read_parquet(p) for p in EXPECTED.glob("*.parquet")} + versions = json.loads((EXPECTED / "versions.json").read_text()) + return tables, versions diff --git a/pairplex/tests/test_golden.py b/pairplex/tests/test_golden.py new file mode 100644 index 0000000..5eba2aa --- /dev/null +++ b/pairplex/tests/test_golden.py @@ -0,0 +1,78 @@ +"""End-to-end golden-output regression tests (real PairPlex run + abstar on a tiny fixed input). + +1. The reference behaviour must not drift: with ``legacy=True`` (or plain ``run()`` before a legacy + flag exists) the outputs must equal the stored golden tables. + * PairPlex's own stages (cluster metadata, consensus sequences) and the pairing decisions + (which contigs pair, their loci) are compared exactly. + * Annotation calls (V/J genes, junction, productive) are compared exactly only when the + installed abstar matches the version that made the golden tables; otherwise that part is + skipped, because germline database updates can legitimately change calls. +2. The default (new) behaviour must run end to end and produce well-formed outputs. + +Regenerate the golden tables only for an intended, reviewed change: +``python pairplex/tests/data/golden/make_golden.py``. +""" + +import inspect + +import polars as pl +import pytest +from polars.testing import assert_frame_equal + +import pairplex.pairplex as ppx +from pairplex.tests.golden import ANNOTATION_CALLS, abstar_version, extract, load_expected, run_pairplex + +HAS_LEGACY = "legacy" in inspect.signature(ppx.run).parameters +PAIR_CONTRACT = ["barcode", "well", "name", "confidence"] + [ + f"{c}:{i}" for i in (0, 1) for c in ("locus", "v_gene", "cdr3_aa", "sequence_id", "sequence")] + + +@pytest.fixture(scope="module") +def reference_tables(tmp_path_factory): + kwargs = {"legacy": True} if HAS_LEGACY else {} + return extract(run_pairplex(tmp_path_factory.mktemp("golden_ref"), **kwargs)) + + +@pytest.fixture(scope="module") +def expected(): + return load_expected() + + +@pytest.mark.parametrize("table", ["metadata", "consensus", "paired"]) +def test_reference_matches_golden(reference_tables, expected, table): + exp, _ = expected + assert_frame_equal(reference_tables[table], exp[table], check_dtypes=False) + + +def test_reference_unpaired_structure_matches_golden(reference_tables, expected): + exp, _ = expected + keep = ["well", "sequence_id", "sequence", "locus"] + assert_frame_equal(reference_tables["unpaired"].select(keep), exp["unpaired"].select(keep), check_dtypes=False) + + +def test_reference_annotation_calls_match_golden(reference_tables, expected): + exp, versions = expected + if abstar_version() != versions["abstar"]: + pytest.skip(f"abstar {abstar_version()} != golden {versions['abstar']}: annotation calls not compared") + cols = ["well", "sequence_id"] + [c for c in ANNOTATION_CALLS if c in exp["unpaired"].columns] + assert_frame_equal(reference_tables["unpaired"].select(cols), exp["unpaired"].select(cols), check_dtypes=False) + + +def test_golden_fixture_is_meaningful(expected): + exp, _ = expected + assert exp["paired"].height >= 10, "fixture should produce pairs" + assert exp["unpaired"].height > exp["paired"].height * 2 + assert exp["metadata"].filter(~pl.col("pass_filters")).height > 0, "fixture should exercise the filters" + + +def test_default_mode_runs_and_is_well_formed(tmp_path): + out = run_pairplex(tmp_path) + t = extract(out) + assert t["metadata"].height > 0 and t["consensus"].height > 0 + assert t["unpaired"].height > 0 + assert t["paired"].height > 0, "default mode produced no pairs on the golden input" + pairs_file = out / "pairs" / "pairs.parquet" + if pairs_file.exists(): # optional final-pairs contract (diagnosis/bench/README.md) + cols = pl.read_parquet(pairs_file).columns + missing = [c for c in PAIR_CONTRACT if c not in cols] + assert not missing, f"pairs/pairs.parquet misses contract columns {missing}"