Add epiTCR / epiTCR-BH pMHC:TCR binding predictor wrapper

[iskandr]

Wrap epiTCR (and its with-MHC variant epiTCR-BH) as an mhctools pMHC:TCR binding predictor (pMHC_TCR_binding).

Upstream: https://github.com/ddiem-ri-4D/epiTCR — a Random-Forest TCR–epitope binding predictor.

Pretrained weights: shipped in-repo — models/rdforestWithoutMHCModel.pickle.zip (~8.5 MB) and models/rdforestWithMHCModel.pickle.zip (~9 MB). No retraining needed.

Framework / deps: scikit-learn 1.1 (RandomForest). Very light — but sklearn pickles are version-sensitive, so pin scikit-learn==1.1 for loading.

License: CC-BY-NC — non-commercial. Fine for a wrapper, but weights shouldn't be redistributed for commercial use; favor the "user brings their own clone" pattern.

Inputs / output:

• epiTCR (--chain ce): CDR3β + epitope → binding probability (mhc_dependence="none").
• epiTCR-BH (--chain cem): CDR3β + epitope + MHC → binding probability (mhc_dependence="single_allele"). Needs an HLA→pseudo-sequence step (same idea as netMHCpan pseudo-seqs).

Ease: Easy (epiTCR) to easy-moderate (epiTCR-BH, due to the HLA pseudo-seq preprocessing). Pure sklearn, one-line predict.py.

Suggested wrapping approach: in-process via joblib/pickle load (sklearn is already effectively available), or subprocess. Expose both the with- and without-MHC configs; epiTCR-BH is one of the few benchmark methods that actually consumes an MHC allele.

---

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.