mhcmatch 0.1.0__py3-none-any.whl

mhcmatch/__init__.py

@@ -0,0 +1,44 @@
+"""mhcmatch: peptide-MHC presentation, cross-reactivity, and motif tools on the seqtree substrate.
+
+- :class:`Store` -- MHC restriction / presentation prediction, protein scanning, anchor/TCR-facing
+  decomposition, from a reference epitope panel (isalgo/pmhc_data).
+- :mod:`search` -- large-scale similarity search (TCR-facing recognition vs same-MHC presentation)
+  and neoantigen molecular mimicry (:func:`search.find_mimics`).
+- :class:`Proteome` -- near-exact source-peptide lookup (neoantigen -> parent protein).
+- :class:`Pseudoseq` -- pseudosequence allele similarity & cross-allele diffusion (rare-allele rescue).
+- :func:`logo.motif` -- per-allele motif logos + length distributions.
+
+Theory: ``appendix/mhcmatch.tex``. Roadmap: ``ROADMAP.md``.
+"""
+from importlib.metadata import PackageNotFoundError, version as _version
+
+from . import logo, search
+from .diffusion import AnchorModel
+from .proteome import Proteome, SourceHit
+from .pseudoseq import (Pseudoseq, learn_anchor_weights, load_pseudo, normalize_allele,
+                        resolve_allele)
+from .store import Decomposition, Restriction, Store, anchor_indices, infer_class
+
+__all__ = [
+    "Store",
+    "Restriction",
+    "Decomposition",
+    "infer_class",
+    "anchor_indices",
+    "search",
+    "AnchorModel",
+    "Proteome",
+    "SourceHit",
+    "Pseudoseq",
+    "learn_anchor_weights",
+    "load_pseudo",
+    "normalize_allele",
+    "resolve_allele",
+    "logo",
+    "__version__",
+]
+
+try:
+    __version__ = _version("mhcmatch")
+except PackageNotFoundError:  # running from a source tree without an install
+    __version__ = "0.1.0"

mhcmatch/cli.py

@@ -0,0 +1,148 @@
+"""Command-line interface for mhcmatch: ``mhcmatch <command> ...``.
+
+Commands: ``decompose`` (no data needed), ``restriction``, ``scan``, ``logo`` (need a pmhc_data
+table via ``--pmhc`` or ``$MHCMATCH_PMHC``), and ``source`` (needs a proteome FASTA).
+"""
+from __future__ import annotations
+
+import argparse
+import os
+
+from . import Proteome, Store
+
+
+def _add_store_opts(p):
+    p.add_argument("--pmhc", help="pmhc_data TSV(.gz); else $MHCMATCH_PMHC/pmhc_<tier>.tsv.gz")
+    p.add_argument("--tier", default="full", choices=("full", "shortlist"))
+    p.add_argument("--species", default="human", choices=("human", "mouse"))
+
+
+def _store(a):
+    return Store.from_pmhc(a.pmhc, tier=a.tier, species=a.species)
+
+
+def _read_seq(arg):
+    """A raw sequence, or the concatenated sequences of a FASTA file path."""
+    if os.path.exists(arg):
+        from .proteome import read_fasta
+        seqs = read_fasta(arg)
+        if seqs:
+            return "".join(seqs.values())
+    return arg.strip()
+
+
+def cmd_decompose(a):
+    d = Store().decompose(a.peptide, cls=a.cls)
+    print(f"peptide       {d.peptide}")
+    print(f"anchors       {','.join(str(i + 1) for i in d.anchors)}")
+    print(f"tcr_facing    {d.tcr_facing}")
+    print(f"presentation  {d.presentation}")
+
+
+def _resolve_panel_allele(store, name, cls):
+    """Map a user-typed allele to a panel allele (exact, else prefix on punctuation-stripped name)."""
+    pool = (cls,) if cls else ("mhc1", "mhc2")
+    panel = {al for c in pool for al in store.alleles(c)}
+    if name in panel:
+        return name
+    key = name.replace("*", "").replace(":", "")
+    hits = sorted(a for a in panel if a.replace("*", "").replace(":", "").startswith(key))
+    if hits:
+        print(f"# resolved '{name}' -> '{hits[0]}'")
+        return hits[0]
+    print(f"# allele '{name}' not found in panel")
+    return name
+
+
+def cmd_restriction(a):
+    store = _store(a)
+    allele = _resolve_panel_allele(store, a.allele, a.cls) if a.allele else None
+    res = store.restriction(a.peptide, cls=a.cls, alleles=[allele] if allele else "all",
+                            top=a.top, diffuse=a.diffuse)
+    if not res:
+        print("no presenting allele (no presentation-signature neighbours)")
+        return
+    print(f"{'allele':<18}{'vote':>7}{'enr':>7}" + ("{:>8}".format("score") if a.diffuse else "")
+          + f"{'binder':>8}")
+    for r in res:
+        line = f"{r.allele:<18}{r.vote:>7.2f}{r.enrichment:>7.1f}"
+        if a.diffuse:
+            line += f"{(r.anchor_score or 0.0):>8.2f}"
+        print(line + f"{'yes' if r.binder else 'no':>8}")
+
+
+def cmd_scan(a):
+    hits = _store(a).scan_protein(_read_seq(a.protein), cls=a.cls or "mhc1",
+                                  alleles=[a.allele] if a.allele else "all", top=a.top,
+                                  correction=a.correction)
+    label = f" ({a.correction} FWER/FDR)" if a.correction else ""
+    print(f"# {len(hits)} presented window(s){label}")
+    for pos, pep, binders in hits:
+        print(f"{pos:>5}  {pep:<14}  {','.join(b.allele for b in binders)}")
+
+
+def cmd_source(a):
+    hits = Proteome.from_fasta(a.proteome).find_source(a.peptide, max_subs=a.max_subs)
+    if not hits:
+        print("# no source within max_subs")
+        return
+    for h in hits:
+        muts = ",".join(f"{q}{i + 1}{r}" for i, q, r in h.mutations) or "exact"
+        print(f"{h.protein}\tpos {h.position}\tsubs {h.n_subs}\t{h.ref_peptide}\t{muts}")
+
+
+def cmd_logo(a):
+    from . import logo
+    m = logo.motif(_store(a), a.allele, a.cls or "mhc1")
+    print(f"# {a.allele}  width={m['width']}  n={m['n']}  lengths={dict(sorted(m['length_hist'].items()))}")
+    for i, (bits, col) in enumerate(zip(m["bits"], m["pwm"]), 1):
+        top = sorted(col.items(), key=lambda x: -x[1])[:3]
+        print(f"  pos {i:>2}  {bits:4.2f} bits  " + " ".join(f"{aa}:{p:.2f}" for aa, p in top))
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="mhcmatch", description="peptide-MHC presentation tools")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    d = sub.add_parser("decompose", help="split a peptide into anchor / TCR-facing parts (X masks)")
+    d.add_argument("peptide")
+    d.add_argument("--cls", choices=("mhc1", "mhc2"))
+    d.set_defaults(fn=cmd_decompose)
+
+    r = sub.add_parser("restriction", help="rank presenting alleles for a peptide")
+    r.add_argument("peptide")
+    r.add_argument("--allele", help="restrict to a single allele")
+    r.add_argument("--cls", choices=("mhc1", "mhc2"))
+    r.add_argument("--diffuse", action="store_true", help="rare-allele-aware (diffusion-shrunk anchors)")
+    r.add_argument("--top", type=int, default=10)
+    _add_store_opts(r)
+    r.set_defaults(fn=cmd_restriction)
+
+    s = sub.add_parser("scan", help="find presented peptides in a protein (sequence or FASTA path)")
+    s.add_argument("protein")
+    s.add_argument("--allele")
+    s.add_argument("--cls", choices=("mhc1", "mhc2"))
+    s.add_argument("--top", type=int, default=3)
+    s.add_argument("--correction", choices=("bonferroni", "bh"),
+                   help="multiple-testing control over windows x alleles (FWER / BH-FDR)")
+    _add_store_opts(s)
+    s.set_defaults(fn=cmd_scan)
+
+    so = sub.add_parser("source", help="find the self peptide a neoantigen derives from")
+    so.add_argument("peptide")
+    so.add_argument("--proteome", required=True, help="reference proteome FASTA(.gz)")
+    so.add_argument("--max-subs", type=int, default=1)
+    so.set_defaults(fn=cmd_source)
+
+    lg = sub.add_parser("logo", help="motif logo (information content) + length distribution")
+    lg.add_argument("allele")
+    lg.add_argument("--cls", choices=("mhc1", "mhc2"))
+    _add_store_opts(lg)
+    lg.set_defaults(fn=cmd_logo)
+
+    a = ap.parse_args(argv)
+    a.fn(a)
+
+
+if __name__ == "__main__":
+    main()

mhcmatch/data/PROVENANCE.md

@@ -0,0 +1,34 @@
+# Vendored data provenance
+
+## `mhci_pseudo.fa` / `mhcii_pseudo.fa`
+
+NetMHCpan-style **34-residue MHC pseudosequences** — the polymorphic groove positions that contact
+the peptide (class I: α1/α2 of the MHC heavy chain; class II: α1 of the α-chain + β1 of the
+β-chain). Header format `>ALLELE|n=<count>`; `X` marks an ambiguous/unresolved position.
+
+- **MHC-I:** 4143 alleles (human HLA-A/B/C, mouse H-2, and other species).
+- **MHC-II:** 2209 alleles (human HLA-DR/DQ/DP, mouse H-2 I-A/I-E, others).
+
+Copied verbatim from the sibling `antigenomics/tcren` repository
+(`tcren-ms/src/tcren/data/{mhci,mhcii}_pseudo.fa`, built by its `scripts/build_pseudo_fasta.py`),
+which derives them from the NetMHCpan pseudosequence definition. Used by `mhcmatch.pseudoseq` as the
+allele-similarity alphabet for the cross-allele diffusion model (see `appendix/mhcmatch.tex` §4).
+
+These files are static reference data and small (~340 KB total), so they are vendored rather than
+fetched. Re-sync from `tcren` if the pseudosequence definition is updated upstream.
+
+## `structural_pockets_mhc1.tsv` / `structural_pockets_mhc2.tsv`
+
+Per-anchor **structural pocket weights**: for each peptide anchor (MHC-I P1/P2/P3/PΩ-1/PΩ; MHC-II
+P1/P4/P6/P9), the frequency with which each of the 34 groove pseudosequence positions makes a
+heavy-atom contact (<5 Å) with that anchor residue, measured over pMHC crystal structures. Used as a
+data-independent alternative to the learned-MI groove weights via `AnchorModel(weights="structural")`.
+
+Measured by `bench/structural_pockets.py` from the **Canonical2026** TCR:pMHC structure set
+(`antigenomics/tcren`, 372 usable structures): the 34-mer pseudosequence is threaded onto each groove
+with tcren's C++ fitting aligner (`tcren._align`; no mmseqs/arda). Class per structure is assigned by
+best pseudosequence fit (MHC-I single chain vs MHC-II α1+β1 chain-pair), giving **279 MHC-I** and
+**93 MHC-II** structures. Regenerate with:
+
+    conda run -n tcren-nb python bench/structural_pockets.py \
+        --structures ../tcren-ms/data/Canonical2026 --out src/mhcmatch/data