tcren documentation#

tcren is a Python re-implementation (and extension) of the TCRen method for structure-based prediction of T-cell-receptor recognition of epitopes. From one TCR–peptide–MHC structure (experimental or modelled) it parses and annotates the complex — TCR chains via arda, MHC chains mapped against a curated reference and the groove partitioned — orients it into a canonical frame, computes residue contacts, and scores every candidate epitope with a residue-level statistical potential derived from TCR:pMHC crystal structures.

Where the original TCRen scored only TCR↔peptide contacts, this version scores all three interfaces (TCR↔peptide with TCRen, TCR↔MHC and peptide↔MHC with Miyazawa–Jernigan) for the full binding picture, and adds mutation ΔΔG, binder classification, pose refinement, and interface mechanics.

What tcren does#

  • Score & rank epitopes — score / rank / pipeline: TCRen energy per candidate, a percentile rank against a random background, and the three-interface breakdown + total.

  • Mutation ΔΔG — ddg: alanine scans and neoantigen substitutions on the native contact map (virtual-matrix, no re-docking).

  • Binder classification — binder: binder vs non-binder for AlphaFold/TCRmodel2 models from AF-orthogonal interface geometry.

  • Annotation & contacts — annotate / contacts: TCR CDR/FR, MHC groove helices/floor and peptide markup; multi-layer (5/8/12 Å) contact tables.

  • Canonical orientation — orient / superimpose: one common MHC frame, docking angles, reverse-dock detection.

  • Peptide substitution & refinement — refine: backbone-preserving substitution plus a DOPE-scored Monte-Carlo pose refinement (with CCD/OpenMM/ProMod3/FlexPepDock engines).

  • Potential derivation — derive-potential: re-derive the TCRen potential (classic/AM/LOO, with non-redundancy filtering) from a structure set.

  • QC, mechanics & maps — steric-clash and register checks, an interface spring-network / rupture model, and 2D complementarity maps + 3D pocket/CDR views.

Note

Ranking, not affinity. TCRen ranks peptide/TCR specificity for a given receptor; it is not a binding-affinity model. On the ATLAS SPR benchmark neither the raw contact energy nor its poly-alanine difference (tcren.ddg.reference_delta()) predicts Kd/ΔG/koff/kon (ρ ≤ 0.3 in magnitude). The one affinity-adjacent quantity a static structure predicts is the off-rate koff, via interface mechanics (tcren.mechanics) — not the contact sum.

Contents

Tutorials

Indices#