tcren — rank and inspect TCR–pMHC models

tcren ranks candidate αβ TCR:peptide–MHC structures and exposes the evidence behind the ranking: generator confidence, structural contact energy, interface geometry and contact topology. Start with a cohort of separately modelled candidates, or use the toolkit to inspect one structure or score peptides on a fixed template.

The scores are dimensionless structural readouts. They are not binding free energies, calibrated binding probabilities or affinity estimates. For receptor ranking, keep ipTM primary and inspect the structural components alongside it; the combination is not an established universal improvement over ipTM.

Install

pip install tcren
tcren build-mhc-ref

Binary wheels contain five native extensions. The runtime dependency arda-mapper annotates TCR chains and fetches its reference/search backend on first use. The MHC allele reference is built from IMGT on demand. See the installation guide for reference data, supported environments and first-run behavior.

For development, use the repository's isolated environment:

bash setup.sh
source .venv/bin/activate

Start with one ranking task

tcren screen -s models.tar.gz -o scores.tsv
# Optional table with unique complex.id and iptm columns:
tcren screen -s models.tar.gz --confidence confidence.tsv -o scores.tsv

A cohort holds one side fixed:

Automatic detection reads the annotated peptide and CDR3 pair. Keep one MHC background and verify experimental identities before joining labels. A mixed set or a set where nothing varies is refused. Missing ipTM is reported; tcren reads it from metadata or the confidence table and does not calculate generator confidence.

The structural reference truncates side chains to alanine in three dimensions, retains backbone and Cβ atoms, and rebuilds contacts. It is not a virtual identity substitution on a fixed contact map. The selected side follows the ranking task.

Read the evidence and the score

screen reports raw components, standardized contributions, missingness, cohort flags and a provenance sidecar containing the frozen-reference identity.

• Confidence: the generator's iptm.
• Energy: the structural alanine difference on the TCR:peptide interface.
• Geometry: height-field Pearson complementarity, sc_shape.
• Topology: CDR:pMHC graph cycle fraction, g_cyclo_frac; carried for TCR ranking.

TCR ranking uses S = (6 * ipTM + T) / 7, where T = g_cyclo_frac. Both inputs and the default score lie in [0,1]; this is not a binding probability. Energy and geometry remain separate readouts. Frozen standardized components remain diagnostic columns. Epitope ranking retains weighted Stouffer with confidence and energy weighted equally. Nothing is fitted or normalized against the query cohort. Legacy custom references retain their Stouffer rule.

Models with zero TCR:peptide contacts remain in output with a discard reason and no score. They do not count toward the default floor of 30 models with an interface. Smaller cohorts report components alone. Flags report by default. --on-flag explicitly selects report, structure, geometry, withhold or reverse; responses cannot restore unavailable scores. Reversal is not recommended as a correction for modelling failures.

The screening guide defines every component, its units, the combination equations, missingness and output fields. The inspection guide explains how to read those outputs. Keep MHC class, epitope and template coverage explicit when making comparisons. High peptide-ranking accuracy alone does not establish receptor specificity across epitopes.

Use the toolkit for a particular quantity

Fixed-template threading and separately modelled candidates are distinct protocols. features retains historical fixed-map dPhi columns; use the explicit structural scoring/export routes above for the current alanine reference. The full API reference documents library calls, experimental contact layers and supported historical reproduction APIs.

Historical recognize, assess and fitted Potts readouts retain their dependencies and reproduction contracts; they are not the current screen. The integral/GLM commands were withdrawn. See reference dependencies and SOURCES for parameter provenance and resource identities.

Development and verification

./setup.sh --tests
.venv/bin/ruff check src tests
source .venv/bin/activate
make -C docs html SPHINXOPTS=-W

Use .venv/bin/python -m pytest -m 'not slow' for the non-slow suite; scientific benchmarks are separate from software checks. Rebuild the editable install after native changes. Scientific campaigns, old results and publication figures are maintained with the benchmark and manuscript repositories. CHANGELOG.md records software changes. The API skill owns API guidance.