Add NetTCR-2.2 pMHC:TCR binding predictor (#215)

[iskandr]

Closes #215.

Adds TCR specificity as a new modality to mhctools — predicting whether a paired αβ T-cell receptor recognises a class-I peptide. This is the first predictor whose input is a receptor (six CDR loops) rather than an MHC allele, and the first pMHC:TCR output.

What's new

Ontology / data model

• Kind.pMHC_TCR_binding — new output kind.
• TCR — new input type: a paired αβ receptor given by its six CDR loops (cdr1a…cdr3b) + optional name. NetTCR-style a1…b3 aliases and a stable .identifier.
• Prediction.tcr field + tcr dataframe column (empty for non-TCR predictions, same convention as allele on processing predictors).
• PeptideResult.tcr_binding and .tcrs accessors.

Predictor

• NetTCR — runs NetTCR-2.2's pan cross-validation ensemble (20 TFLite models, ~0.4 MB each) in-process; the reported score is the ensemble mean recognition probability.

from mhctools import NetTCR, TCR

p = NetTCR()   # resolves NETTCR_DIR / ~/NetTCR-2.2
tcr = TCR(cdr1a="NSASQS", cdr2a="VYSSG", cdr3a="VVEGDKVI",
          cdr1b="MGHRA", cdr2b="YSYEKL", cdr3b="ASSHSGYEQF", name="clone1")

p.predict_pairs([("LLWNGPMAV", tcr)])[0].tcr_binding.score   # -> ~0.77
p.predict(["LLWNGPMAV", "GILGFVFTL"], [tcr])                 # peptide × TCR grid

Distribution — no gated download, no conda env

NetTCR ships its weights directly in its git repo (not git-LFS), so the wrapper loads the TFLite models directly and does not need NetTCR's conda/Keras environment. Requirements:

• a cloned NetTCR-2.2 (weights) — resolved from nettcr_path=, NETTCR_DIR, or ~/NetTCR-2.2 / ~/code/NetTCR-2.2;
• a TFLite runtime — pip install mhctools[nettcr] (uses the lightweight ai-edge-litert; tflite-runtime and tensorflow also work via a runtime fallback).

Nothing from NetTCR (which is under an academic software license) is vendored — same "user provides the install" model as the DTU netMHC* tools and BigMHC.

Faithfulness — verified against upstream

The BLOSUM50 encoding (residues → BLOSUM50/5, padding → −1), per-feature padding lengths (pep=12, a1..b3=7/8/22/6/7/23), and name-based input-tensor assignment (serving_default_<feature>:0) reproduce NetTCR-2.2 src/predict.py exactly. Ran NetTCR's own predict.py for a model and matched this wrapper's per-model output to ~1e-7; the ensemble recovers sensible binding signal (cognate LLWNGPMAV pair 0.77 vs mismatch RAKFKQLL 0.001).

Scope

• In: the pan model (the only one that generalises to arbitrary peptides).
• Out: the peptide-specific / pretrained per-peptide models, and any NetTCR training mode. Not wired into the CLI (its allele-based interface doesn't fit a TCR input) — Python API only.

Tests

• tests/test_tcr.py — TCR dataclass (model-free, always runs).
• tests/test_nettcr.py — encoding unit tests that pin the exact BLOSUM50/pad/normalize behaviour (model-free, always run) + integration tests gated on a NetTCR install (skip when absent, mirroring test_bigmhc.py).

Full suite: 462 passed, 9 skipped, 2 xfailed (with NETTCR_DIR set so the model tests execute). Ruff clean. Version bump 3.14.1 → 3.15.0.

https://claude.ai/code/session_01LZahFhBSCiehXTESCYQ7wG