Add TEINet pMHC:TCR binding predictor wrapper

[iskandr]

Wrap TEINet as an mhctools pMHC:TCR binding predictor (pMHC_TCR_binding).

Upstream: https://github.com/jiangdada1221/TEINet — transfer-learning (pretrained TCR/epitope encoders) for TCR–epitope binding.

Pretrained weights: the two trained models (large/small) are on Google Drive; the encoder weights are in-repo (~35.8 MB each). Requires a manual Drive download step (scriptable with gdown).

Framework / deps: PyTorch (torch>=1.1) — reasonably modern.

License: GPL-3.0 — copyleft. Do not bundle/redistribute; use the "user brings their own clone" pattern (exactly like mhctools/tulip.py, which wraps GPLv3 TULIP out-of-process without contaminating the Apache-2.0 package).

Inputs / output: CDR3β + epitope → binding score; simple 2-column CSV interface (mhc_dependence="none").

Ease: Easy to run — one-line predict.py over a 2-column CSV — once the Drive weights are fetched.

Suggested wrapping approach: subprocess into the user's TEINet checkout (GPL boundary), auto-gdown the weights in a setup script (as scripts/setup_tulip_env.sh clones TULIP).

Note (unverified): the large/small ↔ large_dset.pth/teinet_data.pth mapping was inferred from training-set size, not stated upstream — confirm before wiring defaults.

---

Surfaced from a survey of TCREpitopeBenchmark for methods with public pretrained weights that run easily for inference.

https://claude.ai/code/session_01LZahFhBSCiehXTESCYQ7wG

[iskandr]

⚠️ Read before investing effort: the generalization ceiling

Every TCR–epitope binding predictor in this backlog — this one included — shares a well-documented limitation: they do only modestly on epitopes seen in training and drop to near-random on unseen/novel epitopes. Independent benchmarks find that no current method reliably generalizes; the "best" scores on unseen data sit around the random floor (e.g. mean AUPRC ~0.52–0.53). A tool can look decent on a test set dominated by common epitopes (GILGFVFTL, NLVPMVATV, …) purely because those TCRs saturate the public databases, then fail on anything new.

References

• Moris et al. 2021, Briefings in Bioinformatics — Current challenges for unseen-epitope TCR interaction prediction (foundational: the unseen-epitope challenge, negative-data bias, imbalanced-epitope distribution)
• Meysman et al. 2023, ImmunoInformatics — Benchmarking solutions to the TCR epitope prediction problem: IMMREP22 workshop report (first public benchmark, 23 models) and the IMMREP23 follow-up
• Nature Methods 2025 — Assessment of computational methods in predicting TCR–epitope binding recognition

Implication for this wrapper: worthwhile for reproducibility, cross-method benchmarking, and the well-characterized "seen-epitope" regime — not as a trustworthy predictor for novel epitopes / neoantigens. When we build it, the wrapper's docstring should state this ceiling so users don't over-trust the output.