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 ranking for AI-generated models, pose refinement, and interface mechanics.

What tcren does#

  • Assess a modelled complex – assess: is the pose real, is it a binder, and which part of the structure says so? Five read-outs of one frozen object, every one defined for a single structure (tcren.score, see Assessing a modelled complex).

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

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

  • Interface descriptors – features: one flat per-structure table of 164 catalogued descriptors in six families, four of them computed by default (see Interface feature reference).

  • The fit-free predecessor tier – recognize: Q (interface geometry), T (footprint shape) and their composition with the contact energy, S (see A kit for AI-generated TCR–pMHC structures). None of them is fitted, and each is defined for a single structure.

  • 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), and --repack to place every side chain in the χ rotamer DOPE prefers.

  • Surface topology – surface: the pMHC face a TCR meets before it binds, as a height field over the groove with hydropathy and charge painted on, plus the scalars that make “featureless” a number (relief, peak_to_valley, frac_above_ridge) and a map distance that clusters epitopes; --side tcr rasters the receptor underside in the same frame, and surface_complementarity scores shape, charge and hydropathy agreement between the two faces (tcren.topology.surface).

  • Backbone dynamics – tcren.peptide_stability(): flexible-backbone Metropolis Monte Carlo of the peptide’s φ/ψ against DOPE, reporting how far the peptide wanders rather than a better pose – whether its own side chains hold the TCR-facing conformation, which a contact potential scoring a single handed-in pose cannot see (tcren.mechanics.dynamics).

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

  • Contact-map Potts model – potts fit / score / contacts: a Boltzmann distribution over the contact map itself, whose sites are the residue pairs that could have contacted. Gives a structure’s map an energy (neg_energy, the term S reads), a partition function and a likelihood, and every residue pair a contact probability (tcren.potts, see Contact-map Potts model).

  • 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.energetics.mutation.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#