vdjmatch 0.0.1__py3-none-any.whl

vdjmatch/__init__.py

@@ -0,0 +1,8 @@
+"""vdjmatch — fast, control-calibrated annotation of TCR antigen specificity.
+
+Built on the ``seqtree`` fuzzy-search core: annotates AIRR clonotypes against VDJdb,
+reporting control-calibrated E-values and enriched antigen labels. See ROADMAP in the
+seqtree repo and the project README for the design.
+"""
+
+__version__ = "0.0.1"

vdjmatch/aggregate/__init__.py

@@ -0,0 +1,4 @@
+"""Epitope-level enrichment aggregation."""
+from .enrichment import epitope_summary, best_call
+
+__all__ = ["epitope_summary", "best_call"]

vdjmatch/aggregate/enrichment.py

@@ -0,0 +1,40 @@
+"""Aggregate per-hit annotations into epitope-level enrichment and per-query best calls."""
+from __future__ import annotations
+
+import polars as pl
+
+
+def epitope_summary(hits: pl.DataFrame) -> pl.DataFrame:
+    """Epitope-level summary: unique matched query clonotypes, reads, and best alignment score,
+    grouped by (epitope, mhc_class, antigen_species). Sorted by unique clonotypes desc."""
+    if hits.height == 0:
+        return pl.DataFrame(schema={"epitope": pl.Utf8, "mhc_class": pl.Utf8,
+                                    "antigen_species": pl.Utf8, "unique": pl.UInt32,
+                                    "reads": pl.Int64, "best_score": pl.Int32})
+    per_q = (hits.group_by("epitope", "mhc_class", "antigen_species", "query_cdr3")
+                 .agg(pl.col("count").first(), pl.col("score").min().alias("best_score")))
+    return (per_q.group_by("epitope", "mhc_class", "antigen_species")
+                 .agg(pl.col("query_cdr3").n_unique().alias("unique"),
+                      pl.col("count").sum().alias("reads"),
+                      pl.col("best_score").min().alias("best_score"))
+                 .sort("unique", descending=True))
+
+
+def best_call(hits: pl.DataFrame, evals: pl.DataFrame | None = None) -> pl.DataFrame:
+    """Per query clonotype, the predicted epitope = most-supported (most DB records, then highest
+    VDJdb confidence, then best alignment). If ``evals`` (query_evalues output) is supplied, attach
+    the query's E / p_enrichment as the annotation confidence."""
+    if hits.height == 0:
+        return hits
+    support = (hits.group_by("query_cdr3", "epitope")
+                   .agg(pl.len().alias("n_records"),
+                        pl.col("vdjdb_score").max().alias("db_score"),
+                        pl.col("score").min().alias("best_score"),
+                        pl.col("mhc_class").first(), pl.col("antigen_species").first()))
+    best = (support.sort(["query_cdr3", "n_records", "db_score", "best_score"],
+                         descending=[False, True, True, False])
+                   .group_by("query_cdr3", maintain_order=True).first())
+    if evals is not None:
+        best = best.join(evals.select("query_cdr3", "E", "p_enrichment", "rule_of_three"),
+                         on="query_cdr3", how="left")
+    return best

vdjmatch/cli/__main__.py

@@ -0,0 +1,79 @@
+"""vdjmatch command-line interface.
+
+Subcommands:
+  update   fetch/cache the latest VDJdb release
+  match    annotate query sample(s) against VDJdb (E-values + ranked hits + epitope summary)
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from .. import db, match
+from ..runner.multisample import annotate_sample
+
+
+def _cmd_update(a: argparse.Namespace) -> int:
+    path = db.fetch_latest(asset=a.asset, pin=a.pin, force=a.force)
+    print(f"VDJdb {a.asset} cached at {path}")
+    return 0
+
+
+def _cmd_match(a: argparse.Namespace) -> int:
+    vdj = db.load(a.vdjdb, asset=a.asset, species=a.species, min_score=a.min_score, pin=a.pin)
+    print(f"VDJdb: {vdj.height:,} records "
+          f"(species={a.species}, min_score={a.min_score})", file=sys.stderr)
+    index = match.VdjdbIndex.build(vdj, species=a.species)
+    print(f"indexed genes: {index.genes}", file=sys.stderr)
+    matrix = match.load_vdjam() if a.matrix == "vdjam" else ""
+    outdir = Path(a.output_prefix).parent
+    outdir.mkdir(parents=True, exist_ok=True)
+    for sample in a.samples:
+        name = Path(sample).name.split(".")[0]
+        print(f"[{name}] annotating ...", file=sys.stderr)
+        res = annotate_sample(index, sample, scope=a.scope, matrix=matrix or None,
+                              species=a.species, with_evalue=not a.no_evalue,
+                              match_v=a.match_v, match_j=a.match_j, align=not a.no_align,
+                              threads=a.threads)
+        for kind, frame in res.items():
+            out = f"{a.output_prefix}.{name}.{kind}.txt"
+            frame.write_csv(out, separator="\t")
+        print(f"[{name}] {res['hits'].height} hit rows, "
+              f"{res['summary'].height} epitopes -> {a.output_prefix}.{name}.*.txt", file=sys.stderr)
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(prog="vdjmatch", description=__doc__)
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    up = sub.add_parser("update", help="fetch/cache the latest VDJdb release")
+    up.add_argument("--asset", default="slim", choices=["slim", "full", "default"])
+    up.add_argument("--pin", default=None, help="pin a release tag")
+    up.add_argument("--force", action="store_true")
+    up.set_defaults(func=_cmd_update)
+
+    m = sub.add_parser("match", help="annotate sample(s) against VDJdb")
+    m.add_argument("samples", nargs="+", help="AIRR rearrangement sample file(s)")
+    m.add_argument("-o", "--output-prefix", default="vdjmatch_out")
+    m.add_argument("--vdjdb", default=None, help="VDJdb table path (default: fetch latest)")
+    m.add_argument("--asset", default="full", choices=["slim", "full", "default"])
+    m.add_argument("--pin", default=None)
+    m.add_argument("--species", default="HomoSapiens")
+    m.add_argument("--scope", default="1,0,0,1", help="s,i,d,t search budget")
+    m.add_argument("--matrix", default="vdjam", choices=["vdjam", "none"])
+    m.add_argument("--min-score", type=int, default=0, help="min VDJdb confidence")
+    m.add_argument("--match-v", action="store_true")
+    m.add_argument("--match-j", action="store_true")
+    m.add_argument("--no-evalue", action="store_true")
+    m.add_argument("--no-align", action="store_true")
+    m.add_argument("--threads", type=int, default=0)
+    m.set_defaults(func=_cmd_match)
+
+    a = p.parse_args(argv)
+    return a.func(a)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

vdjmatch/cluster/__init__.py

@@ -0,0 +1,3 @@
+"""Pairwise sample overlap."""
+from .overlap import overlap, overlap_metrics
+__all__ = ["overlap", "overlap_metrics"]

vdjmatch/cluster/overlap.py

@@ -0,0 +1,36 @@
+"""Pairwise sample overlap via fuzzy CDR3 matching (ports the legacy ``cluster`` routine)."""
+from __future__ import annotations
+
+import polars as pl
+from seqtree import pairwise_batch
+
+from ..match.scope import search_params
+
+
+def overlap(a: list[str], b: list[str] | None = None, scope: str = "1,0,0,1",
+            matrix=None, threads: int = 0) -> pl.DataFrame:
+    """Fuzzy-matching pairs between two CDR3 sets (or within one if ``b`` is None).
+
+    Returns a long frame ``a_idx, a_cdr3, b_idx, b_cdr3, score, n_subs`` of all within-scope
+    pairs. Within-set mode (``b is None``) drops the trivial self-pairs (i == j).
+    """
+    within = b is None
+    bb = a if within else b
+    params = search_params(scope, engine="seqtm", matrix=matrix or "")
+    res = pairwise_batch(a, bb, params, "aa", threads)
+    rows = [(i, a[i], h.ref_id, bb[h.ref_id], h.score, h.n_subs)
+            for i, hl in enumerate(res) for h in hl if not (within and i == h.ref_id)]
+    return pl.DataFrame(rows, orient="row",
+                        schema=["a_idx", "a_cdr3", "b_idx", "b_cdr3", "score", "n_subs"])
+
+
+def overlap_metrics(a: list[str], b: list[str], scope: str = "1,0,0,1",
+                    threads: int = 0) -> dict[str, float]:
+    """Summary overlap metrics between two repertoires: number of matched pairs, and the
+    fraction of each set with at least one fuzzy match in the other."""
+    pairs = overlap(a, b, scope=scope, threads=threads)
+    a_hit = pairs["a_idx"].n_unique() if pairs.height else 0
+    b_hit = pairs["b_idx"].n_unique() if pairs.height else 0
+    return {"pairs": float(pairs.height),
+            "frac_a_matched": a_hit / len(a) if a else 0.0,
+            "frac_b_matched": b_hit / len(b) if b else 0.0}

vdjmatch/db/__init__.py

@@ -0,0 +1,5 @@
+"""VDJdb fetch, cache, and parse."""
+from .vdjdb import fetch_latest, load
+from . import schema
+
+__all__ = ["fetch_latest", "load", "schema"]

vdjmatch/db/cache.py

@@ -0,0 +1,16 @@
+"""Cache directory resolution for downloaded VDJdb releases."""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def cache_dir(override: str | os.PathLike | None = None) -> Path:
+    """Return (and create) the vdjmatch cache directory.
+
+    Order: explicit ``override`` → ``$VDJMATCH_CACHE`` → ``~/.cache/vdjmatch``.
+    """
+    base = override or os.environ.get("VDJMATCH_CACHE") or (Path.home() / ".cache" / "vdjmatch")
+    p = Path(base)
+    p.mkdir(parents=True, exist_ok=True)
+    return p

vdjmatch/db/schema.py

@@ -0,0 +1,50 @@
+"""Canonical VDJdb schema and column normalization.
+
+VDJdb ships dot-named columns (``v.segm``, ``antigen.epitope``, ``mhc.a`` …) in both the
+``full`` and ``slim`` exports. We normalize to snake_case canonical names so the rest of the
+package never special-cases the source format.
+"""
+from __future__ import annotations
+
+import polars as pl
+
+# canonical name -> set of accepted source headers (VDJdb full + slim variants)
+_VDJDB_MAP: dict[str, tuple[str, ...]] = {
+    "complex_id": ("complex.id",),
+    "gene": ("gene",),
+    "cdr3": ("cdr3",),
+    "v": ("v.segm", "v.end", "v"),
+    "j": ("j.segm", "j.start", "j"),
+    "species": ("species",),
+    "mhc_a": ("mhc.a",),
+    "mhc_b": ("mhc.b",),
+    "mhc_class": ("mhc.class",),
+    "epitope": ("antigen.epitope",),
+    "antigen_gene": ("antigen.gene",),
+    "antigen_species": ("antigen.species",),
+    "reference_id": ("reference.id",),
+    "vdjdb_score": ("vdjdb.score",),
+}
+
+# the columns vdjmatch actually uses downstream (others are dropped on load)
+CANONICAL: tuple[str, ...] = tuple(_VDJDB_MAP.keys())
+
+
+def normalize(df: pl.DataFrame) -> pl.DataFrame:
+    """Rename VDJdb source columns to canonical names; keep only recognized columns.
+
+    Missing canonical columns are filled with nulls so downstream code can rely on the
+    schema regardless of whether a ``slim`` or ``full`` export was loaded.
+    """
+    present = set(df.columns)
+    renames = {src: canon for canon, srcs in _VDJDB_MAP.items()
+               for src in srcs if src in present}
+    df = df.rename(renames)
+    have = set(df.columns)
+    out_cols = []
+    for canon in CANONICAL:
+        if canon in have:
+            out_cols.append(pl.col(canon))
+        else:
+            out_cols.append(pl.lit(None).alias(canon))
+    return df.select(out_cols)

vdjmatch/db/vdjdb.py

@@ -0,0 +1,108 @@
+"""Fetch and parse VDJdb releases (github.com/antigenomics/vdjdb-db).
+
+The latest release ships a single ZIP (e.g. ``vdjdb-2026-06-03.zip``) that contains the
+``vdjdb.txt`` / ``vdjdb.slim.txt`` / ``vdjdb_full.txt`` tables. ``fetch_latest`` downloads and
+caches the ZIP by release tag and extracts the requested table; ``load`` parses any VDJdb table
+(downloaded or a local snapshot) into a normalized polars frame.
+"""
+from __future__ import annotations
+
+import io
+import json
+import os
+import urllib.request
+import zipfile
+from pathlib import Path
+
+import polars as pl
+
+from . import schema
+from .cache import cache_dir
+
+_REPO = "antigenomics/vdjdb-db"
+_UA = {"User-Agent": "vdjmatch", "Accept": "application/vnd.github+json"}
+# requested table -> substring matched against ZIP member basenames (most specific first)
+_MEMBER = {"full": "vdjdb_full.txt", "slim": "vdjdb.slim.txt", "default": "vdjdb.txt"}
+
+
+def _release_json(pin: str | None) -> dict:
+    url = (f"https://api.github.com/repos/{_REPO}/releases/tags/{pin}" if pin
+           else f"https://api.github.com/repos/{_REPO}/releases/latest")
+    req = urllib.request.Request(url, headers=_UA)
+    with urllib.request.urlopen(req, timeout=60) as r:  # noqa: S310 (trusted host)
+        return json.load(r)
+
+
+def _zip_asset(rel: dict) -> str:
+    for a in rel.get("assets", []):
+        if a["name"].endswith(".zip"):
+            return a["browser_download_url"]
+    raise RuntimeError(f"no .zip asset in VDJdb release {rel.get('tag_name')!r}")
+
+
+def fetch_latest(asset: str = "slim", cache: str | os.PathLike | None = None,
+                 pin: str | None = None, force: bool = False) -> Path:
+    """Download (and cache) a VDJdb table from the latest release (or ``pin`` tag).
+
+    Args:
+        asset: which table to extract — ``"slim"`` (default), ``"full"``, or ``"default"``.
+        cache: cache directory (default ``~/.cache/vdjmatch`` or ``$VDJMATCH_CACHE``).
+        pin: pin a specific release tag for reproducibility; ``None`` = latest.
+        force: re-download even if cached.
+
+    Returns:
+        Path to the extracted table file, named ``vdjdb-<tag>.<asset>.txt`` in the cache.
+    """
+    cdir = cache_dir(cache)
+    rel = _release_json(pin)
+    tag = rel["tag_name"]
+    out = cdir / f"vdjdb-{tag}.{asset}.txt"
+    if out.exists() and not force:
+        return out
+    zip_path = cdir / f"vdjdb-{tag}.zip"
+    if not zip_path.exists() or force:
+        req = urllib.request.Request(_zip_asset(rel), headers=_UA)
+        with urllib.request.urlopen(req, timeout=300) as r:  # noqa: S310
+            data = r.read()
+        zip_path.write_bytes(data)
+    want = _MEMBER.get(asset, _MEMBER["default"])
+    with zipfile.ZipFile(zip_path) as zf:
+        names = zf.namelist()
+        member = next((n for n in names if Path(n).name == want), None)
+        if member is None:  # fall back to substring match
+            key = want.replace("vdjdb", "").strip("._") or "vdjdb.txt"
+            member = next((n for n in names if key in Path(n).name), None)
+        if member is None:
+            raise RuntimeError(f"{want!r} not found in {zip_path.name}; members={names}")
+        out.write_bytes(zf.read(member))
+    return out
+
+
+def load(source: str | os.PathLike | None = None, *, asset: str = "slim",
+         species: str | None = None, gene: str | None = None, mhc_class: str | None = None,
+         min_score: int = 0, paired_only: bool = False, pin: str | None = None) -> pl.DataFrame:
+    """Parse a VDJdb table into a normalized polars frame (see ``schema.CANONICAL``).
+
+    ``source`` is a path to an existing table (e.g. a local snapshot); if ``None`` the latest
+    release is fetched (``asset``/``pin``). Optional filters: ``species`` (e.g. ``"HomoSapiens"``),
+    ``gene`` (``"TRA"``/``"TRB"``), ``mhc_class`` (``"MHCI"``/``"MHCII"``), ``min_score`` (VDJdb
+    confidence), ``paired_only`` (keep only rows with a non-zero ``complex_id``).
+    """
+    path = Path(source) if source is not None else fetch_latest(asset=asset, pin=pin)
+    df = pl.read_csv(path, separator="\t", quote_char=None, infer_schema_length=0)  # all str
+    df = schema.normalize(df)
+    df = df.with_columns(
+        pl.col("vdjdb_score").cast(pl.Int64, strict=False).fill_null(0),
+        pl.col("complex_id").cast(pl.Int64, strict=False).fill_null(0),
+    )
+    if species is not None:
+        df = df.filter(pl.col("species") == species)
+    if gene is not None:
+        df = df.filter(pl.col("gene") == gene)
+    if mhc_class is not None:
+        df = df.filter(pl.col("mhc_class") == mhc_class)
+    if min_score > 0:
+        df = df.filter(pl.col("vdjdb_score") >= min_score)
+    if paired_only:
+        df = df.filter(pl.col("complex_id") != 0)
+    return df

vdjmatch/evalue/__init__.py

@@ -0,0 +1,5 @@
+"""Control-calibrated E-values (single-chain now; paired later)."""
+from .single import query_evalues
+from .control import background
+
+__all__ = ["query_evalues", "background"]

vdjmatch/evalue/control.py

@@ -0,0 +1,25 @@
+"""Background control repertoires for E-value calibration (thin wrapper over seqtree)."""
+from __future__ import annotations
+
+from seqtree import Index
+from seqtree.control import load_control
+
+# query locus -> seqtree control name (bundled human_trb_aa; others via HuggingFace)
+_CONTROL = {
+    "TRB": "human_trb_aa", "human:TRB": "human_trb_aa",
+    "TRA": "human_tra_aa", "human:TRA": "human_tra_aa",
+    "mouse:TRB": "mouse_trb_aa", "mouse:TRA": "mouse_tra_aa",
+}
+
+
+def background(locus: str = "TRB", species: str = "human", size: int | None = None,
+               cache_dir: str | None = None) -> Index:
+    """Load a deduplicated background repertoire ``Index`` for the given locus/species.
+
+    Bundled: human TRB. Others (human TRA, mouse TRA/TRB) download via ``seqtree[control]``.
+    """
+    key = f"{species.lower()}:{locus}"
+    name = _CONTROL.get(key) or _CONTROL.get(locus)
+    if name is None:
+        raise ValueError(f"no control for locus={locus!r} species={species!r}")
+    return load_control(name, size=size, cache_dir=cache_dir)

vdjmatch/evalue/single.py

@@ -0,0 +1,32 @@
+"""Single-chain control-calibrated E-values (thin polars wrapper over ``seqtree.evalues``).
+
+For each query CDR3 we count neighbours in the target (VDJdb) and in a matched background control
+within the search ball; ``E = (N/M)·n_control`` is the number of VDJdb neighbours expected by the
+generative/background process, and ``p_enrichment`` is the Poisson-tail significance that the query
+has *more* VDJdb neighbours than chance — the hallmark of antigen-driven convergence. Theory:
+seqtree ``appendix/evalue.tex``.
+"""
+from __future__ import annotations
+
+import polars as pl
+from seqtree import Index, SearchParams
+from seqtree.evalue import evalues
+
+
+def query_evalues(target: Index, control: Index, queries: list[str], params: SearchParams,
+                  threads: int = 0, exclude_exact: bool = False) -> pl.DataFrame:
+    """Per-query E-values → polars frame with columns ``query_cdr3, n_target, n_control, E,
+    p_any, p_enrichment, rule_of_three`` (one row per input query, input order preserved).
+
+    ``exclude_exact=True`` punctures distance-0 (self/duplicate) hits on both sides — use when
+    queries may be members of the target/control (e.g. VDJdb-vs-VDJdb verification)."""
+    rows = evalues(target, control, queries, params, threads=threads, exclude_exact=exclude_exact)
+    return pl.DataFrame({
+        "query_cdr3": queries,
+        "n_target": [r["n_target"] for r in rows],
+        "n_control": [r["n_control"] for r in rows],
+        "E": [r["E"] for r in rows],
+        "p_any": [r["p_any"] for r in rows],
+        "p_enrichment": [r["p_enrichment"] for r in rows],
+        "rule_of_three": [r["rule_of_three"] for r in rows],
+    })

vdjmatch/io/__init__.py

@@ -0,0 +1,5 @@
+"""Query repertoire I/O (AIRR rearrangement + paired cell / TCRvdb)."""
+from .airr import read_rearrangement, read_cell, read_tcrvdb
+from . import columns
+
+__all__ = ["read_rearrangement", "read_cell", "read_tcrvdb", "columns"]

vdjmatch/io/airr.py

@@ -0,0 +1,70 @@
+"""Read query repertoires: single-chain (AIRR Rearrangement / VDJtools) and paired (AIRR Cell
+long-form linked by cell/clone id, or TCRvdb wide-form with α/β columns in one row).
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import polars as pl
+
+from . import columns
+
+_SEP = {".csv": ",", ".tsv": "\t", ".txt": "\t"}
+
+
+def _read_table(path: str | os.PathLike) -> pl.DataFrame:
+    p = Path(path)
+    sep = _SEP.get(p.suffix.lower(), "\t")
+    return pl.read_csv(p, separator=sep, quote_char='"', infer_schema_length=0)
+
+
+def read_rearrangement(path: str | os.PathLike, dedup: bool = True,
+                       valid_aa: bool = True) -> pl.DataFrame:
+    """Single-chain query → schema ``cdr3, v, j, locus, count, pair_id``. If ``dedup`` (default),
+    collapse to unique (cdr3, v, j, locus) summing ``count`` (required for E-values)."""
+    df = columns.normalize_query(_read_table(path), valid_aa=valid_aa)
+    if dedup:
+        df = (df.group_by("cdr3", "v", "j", "locus")
+                .agg(pl.col("count").sum(), pl.col("pair_id").first()))
+    return df
+
+
+def read_cell(path: str | os.PathLike, link: str | None = None,
+              valid_aa: bool = True) -> pl.DataFrame:
+    """Paired long-form: one row per chain, α/β linked by ``link`` (default: auto = cell_id /
+    clone_id, resolved to ``pair_id``). Pivots to one row per cell with ``cdr3a/va/ja`` and
+    ``cdr3b/vb/jb`` (locus prefix TRA→a, TRB→b)."""
+    df = columns.normalize_query(_read_table(path), valid_aa=valid_aa)
+    if df["pair_id"].null_count() == df.height:
+        raise ValueError("no cell/clone link column found for paired (cell) input")
+    df = df.with_columns(
+        pl.when(pl.col("locus") == "TRA").then(pl.lit("a"))
+          .when(pl.col("locus") == "TRB").then(pl.lit("b"))
+          .otherwise(pl.col("locus").str.slice(2, 1).str.to_lowercase()).alias("ch"))
+    wide = df.pivot(values=["cdr3", "v", "j"], index="pair_id", on="ch",
+                    aggregate_function="first")
+    rename = {f"{c}_{ch}": f"{c}{ch}" for c in ("cdr3", "v", "j") for ch in ("a", "b")}
+    return wide.rename({k: v for k, v in rename.items() if k in wide.columns})
+
+
+def read_tcrvdb(path: str | os.PathLike, valid_aa: bool = True) -> pl.DataFrame:
+    """TCRvdb wide-form CSV: α/β CDR3s in one row. → ``cdr3a, va, ja, cdr3b, vb, jb,
+    epitope, mhc`` (epitope/mhc kept as ground-truth labels for benchmarking)."""
+    df = _read_table(path)
+    cols = {c.lower(): c for c in df.columns}
+    g = lambda *names: next((cols[n] for n in names if n in cols), None)  # noqa: E731
+    sel = {
+        "cdr3a": g("cdr3_alpha_aa"), "va": g("trav"), "ja": g("traj"),
+        "cdr3b": g("cdr3_beta_aa"), "vb": g("trbv"), "jb": g("trbj"),
+        "epitope": g("epitope_aa", "antigen.epitope", "epitope"),
+        "mhc": g("hla_short", "hla_long", "mhc.a"),
+    }
+    out = df.select([pl.col(src).alias(dst) for dst, src in sel.items() if src is not None])
+    out = out.with_columns(
+        pl.col("cdr3a").str.strip_chars().str.to_uppercase(),
+        pl.col("cdr3b").str.strip_chars().str.to_uppercase())
+    if valid_aa:
+        rx = r"^[ACDEFGHIKLMNPQRSTVWY]+$"
+        out = out.filter(pl.col("cdr3a").str.contains(rx) & pl.col("cdr3b").str.contains(rx))
+    return out

vdjmatch/io/columns.py

@@ -0,0 +1,61 @@
+"""Column alias resolution for query repertoire files.
+
+Accepts AIRR Rearrangement canonical headers and the VDJtools / short forms seen in the wild
+(``v_gene``, ``j_gene``, ``junction_aa``, ``clone_id`` …). Normalizes to the vdjmatch query
+schema: ``cdr3, v, j, locus, count, pair_id``.
+"""
+from __future__ import annotations
+
+import polars as pl
+
+AA = set("ACDEFGHIKLMNPQRSTVWY")
+
+# canonical query column -> accepted source headers (case-insensitive), most specific first
+ALIASES: dict[str, tuple[str, ...]] = {
+    "cdr3": ("cdr3_aa", "junction_aa", "cdr3"),     # note: AIRR `junction`/`cdr3` (nt) excluded by suffix
+    "v": ("v_call", "v_gene", "v.segm", "v"),
+    "j": ("j_call", "j_gene", "j.segm", "j"),
+    "locus": ("locus", "chain"),
+    "count": ("duplicate_count", "reads", "count"),
+    "pair_id": ("cell_id", "clone_id", "complex.id"),
+}
+
+
+def _resolve(df: pl.DataFrame) -> dict[str, str]:
+    lower = {c.lower(): c for c in df.columns}
+    out = {}
+    for canon, srcs in ALIASES.items():
+        for s in srcs:
+            if s in lower:
+                out[canon] = lower[s]
+                break
+    return out
+
+
+def normalize_query(df: pl.DataFrame, valid_aa: bool = True) -> pl.DataFrame:
+    """Rename to the query schema, derive ``locus`` from the V gene when absent, default
+    ``count`` to 1, and (if ``valid_aa``) drop CDR3s containing non-standard amino acids."""
+    found = _resolve(df)
+    if "cdr3" not in found:
+        raise ValueError(f"no CDR3 column found; have {df.columns}")
+    df = df.rename({src: canon for canon, src in found.items()})
+    df = df.with_columns(pl.col("cdr3").str.strip_chars().str.to_uppercase())
+
+    for col in ("v", "j"):
+        if col not in df.columns:
+            df = df.with_columns(pl.lit(None, dtype=pl.Utf8).alias(col))
+    if "locus" not in df.columns:
+        df = df.with_columns(pl.col("v").str.slice(0, 3).alias("locus"))
+    if "count" not in df.columns:
+        df = df.with_columns(pl.lit(1, dtype=pl.Int64).alias("count"))
+    else:
+        df = df.with_columns(pl.col("count").cast(pl.Int64, strict=False).fill_null(1))
+    if "pair_id" not in df.columns:
+        df = df.with_columns(pl.lit(None, dtype=pl.Utf8).alias("pair_id"))
+    else:
+        df = df.with_columns(pl.col("pair_id").cast(pl.Utf8))
+
+    df = df.filter(pl.col("cdr3").is_not_null() & (pl.col("cdr3").str.len_chars() > 0))
+    if valid_aa:
+        df = df.filter(pl.col("cdr3").str.contains(r"^[ACDEFGHIKLMNPQRSTVWY]+$"))
+    return df.select("cdr3", "v", "j", "locus", "count", "pair_id")

vdjmatch/match/__init__.py

@@ -0,0 +1,7 @@
+"""Matching engine, scope parsing, scoring, CIGAR."""
+from .engine import VdjdbIndex
+from .scope import parse_scope, search_params
+from .scoring import load_vdjam
+from . import cigar
+
+__all__ = ["VdjdbIndex", "parse_scope", "search_params", "load_vdjam", "cigar"]

vdjmatch/match/cigar.py

@@ -0,0 +1,35 @@
+"""Convert seqtree alignment ops into CIGAR + a human-readable match line.
+
+``seqtree.Alignment.ops`` is one char per alignment column: ``M`` match, ``S`` substitution,
+``I`` insertion (in query), ``D`` deletion (from query). We emit an extended CIGAR using ``=``
+for matches and ``X`` for substitutions (``I``/``D`` unchanged), and a BLAST-style midline.
+"""
+from __future__ import annotations
+
+_CIGAR = {"M": "=", "S": "X", "I": "I", "D": "D"}
+
+
+def to_cigar(ops: str) -> str:
+    """Run-length-encode ops into extended CIGAR, e.g. ``"5=1X3="``."""
+    if not ops:
+        return ""
+    out, run, prev = [], 0, ops[0]
+    for c in ops:
+        if c == prev:
+            run += 1
+        else:
+            out.append(f"{run}{_CIGAR[prev]}")
+            run, prev = 1, c
+    out.append(f"{run}{_CIGAR[prev]}")
+    return "".join(out)
+
+
+def match_line(ops: str) -> str:
+    """BLAST-style midline: ``|`` under a match, space under a substitution/gap."""
+    return "".join("|" if c == "M" else " " for c in ops)
+
+
+def counts(ops: str) -> dict[str, int]:
+    """Per-op counts: matches, subs, ins, dels."""
+    return {"matches": ops.count("M"), "subs": ops.count("S"),
+            "ins": ops.count("I"), "dels": ops.count("D")}