Add TEIM (TCR-epitope interaction) predictor wrapper

[iskandr]

Wrap TEIM (TCR-Epitope Interaction Modeling) as an mhctools pMHC:TCR binding predictor (pMHC_TCR_binding).

Upstream: https://github.com/pengxingang/TEIM — sequence- and residue-level TCR–epitope interaction model.

Pretrained weights: shipped in-repo at ckpt/teim_seq.ckpt (~14 MB) for the sequence-level model. No retraining needed.

Framework / deps: PyTorch + PyTorch-Lightning 1.6.4, Python 3.8. A Dockerfile and a ready inference_seq.py are provided.

License: MIT — permissive; weights can be bundled or the "user brings their own clone" pattern used.

Inputs / output: CDR3β + epitope → interaction/binding score. No MHC input (mhc_dependence="none").

Ease: Easy. In-repo checkpoint + a ready-made inference_seq.py; a Dockerfile pins the env. The separate residue-level model needs ANARCI — target the sequence-level (teim_seq) model first and leave residue-level out of scope.

Suggested wrapping approach: in-process (Lightning 1.6 as an optional extra) or subprocess to an isolated env like mhctools/tulip.py.

---

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.