Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
11 changes: 11 additions & 0 deletions pairplex/tests/data/golden/expected/versions.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
{
"code_commit": "a8b6376cd9e3333aa6d6b1c1415bc6dddc8a0233",
"abstar": "0.9.0",
"run_kwargs": {},
"rows": {
"metadata": 140,
"consensus": 111,
"unpaired": 111,
"paired": 24
}
}
Binary file added pairplex/tests/data/golden/input/well000.fastq.gz
Binary file not shown.
Binary file not shown.
38 changes: 38 additions & 0 deletions pairplex/tests/data/golden/make_golden.py
Original file line number Diff line number Diff line change
@@ -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()
100 changes: 100 additions & 0 deletions pairplex/tests/golden.py
Original file line number Diff line number Diff line change
@@ -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
78 changes: 78 additions & 0 deletions pairplex/tests/test_golden.py
Original file line number Diff line number Diff line change
@@ -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}"
Loading