TCRen — structural evidence for T-cell recognition

TCRen turns TCR–peptide–MHC structures into contact-based scores, receptor rankings and interpretable structural readouts. It brings two approaches into one Python library and command-line toolkit:

• Residue statistical potentials rank candidate epitopes for a fixed TCR and support studies of measured binding affinity, response magnitude and kinetics. Contact energies, structural alanine references and mechanical readouts retain their separate definitions.
• ipTM + Betti fraction + contact enrichment rank candidate receptors against one pMHC, including binder/non-binder and binder/mock comparisons. The default combines generator confidence with global contact organisation and local evidence calibrated against frozen mock structures.

Geometry, surface chemistry, contact attribution, molecular visualization and matched statistics help explain both routes.

Start with your question

Install and rank a receptor cohort

pip install tcren

tcren screen -s models.tar.gz --task tcr \
  --confidence confidence.tsv -o scores.tsv

Bundled source snapshots build the compact two-field MHC protein reference offline. Use tcren build-mhc-ref --all-alleles only for explicit full-vocabulary fine mapping.

Supply separately modelled candidate receptors for one peptide and MHC background. confidence.tsv contains unique complex.id, iptm on [0,1] and plddt on [0,100]; IDs match the structure stems. TCRen reads generator confidence from metadata or this table. Annotation is batched internally, and -t 0 selects the allocated CPU budget by default.

Wheels include five native extensions. ARDA provides TCR annotation and its first-use reference/search setup; the compact MHC reference is built offline from packaged source snapshots. The installation tutorial covers raw structures, input formats and first-run setup.

For peptides threaded onto one fixed template:

tcren score -s template.pdb -c peptides.txt --potential tcren2 -o energies.csv

For separately modelled peptides, use screen --task epitope. Its structural alanine reference truncates peptide side chains in three dimensions and rebuilds contacts before combining the energy difference with ipTM. Fixed-template threading and separately modelled poses are different protocols.

Read the receptor score

S = (1 - 0.41*q - 0.22*(1-q))*ipTM + 0.41*q*B + 0.22*(1-q)*M

For local enrichment, r indexes a tested CDR or peptide residue. Its statistic is c_r = m_r - k_r: physical atom-pair contacts minus distinct partner residues. a_r separately counts distinct contacted atoms. The default includes observed backbone and side-chain heavy atoms; side-chain-only counting is available for separate contact diagnostics. The diagram sketches two contacted side-chain atoms making four contacts to two peptide residues. The three inspection insets reuse public 1AO7 examples.

The weights are shared across a cohort: q = F_ref(mean(plddt)/100), using the frozen five-cohort confidence CDF. Individual ipTM, Betti and enrichment values still vary between models. The weights are nonnegative and sum to one. Mock histograms and compressed whole-control calibration ship with the package; scoring fits no new parameters. Missing active values use flagged frozen training imputation. Read screen_score, component values, weights, missingness and availability reasons together.

Cohort mean remains the default. Models without TCR:peptide contacts receive score 0, no_interface=true, a retained reason and a CLI warning. Never replace this zero with raw ipTM. They do not count towards the default 30-model floor. For one structure, explicitly select a representative confidence context:

tcren screen -s model.pdb --task tcr --confidence confidence.tsv \
  --confidence-context nearest-plddt --min-cohort 1 -o score.tsv

nearest-mean-plddt uses a small same-pMHC set's observed mean. Both alternatives report support and distance to the selected frozen representative. See confidence contexts. Supplied MHC names retain their declared resolution, separately from sequence representatives; exact allele identity is not a term in the default score.

Interpretation. These are structural rankings and measured-endpoint associations. Statistical contact energy is not physical binding free energy; the combined receptor score is development-selected and is not a calibrated binding probability. Representative confidence bins approximate cohort context. Keep matched populations, component readouts and every cohort gain or loss visible. Score definitions and reference dependencies give the full contracts.

Explore an application or reproduce a comparison

The TCRvdb input bundle is supplied separately and is not distributed with the package. Frozen-feature replay and raw-coordinate reproduction are distinct checks. Public structure notebooks document their reference-data prerequisites; PyMOL examples additionally need the PyMOL executable. For scientific comparisons, pin the installed artifact and reference identities, preserve original labels and report exact membership alongside the metrics. SOURCES records the bundled parameter provenance.

Runtime and batching

One public 1AO7 structure (4,848 coordinate records), exporting 143 feature columns on an Apple M3 Max with one compute CPU and existing annotation references, took 7.70 seconds. The matched pre-optimization observation took 8.65 seconds; outputs were byte-identical. Each timing is one unprofiled run. Sampled process-tree RSS was 1.12 GB after the change and can double-count shared pages. Recorded workload and reference hashes make the scope explicit.

Pass a whole cohort in one command. Annotation searches and coarse descriptor workers use separate bounded phases; avoid an outer pool of all-core commands. Reference acquisition/index construction is separate setup work. See performance for CPU budgets, measurement and memory guidance; this single-structure example does not estimate cohort throughput.

Documentation and development

• Learn: installation and first run, worked score notebook.
• Do a task: ranking, inspection, reproduction.
• Look up a definition: score contract, features, API.
• Understand the evidence: reference dependencies, confidence contexts.

./setup.sh --tests
uv pip install -e ".[dev,docs]"
.venv/bin/ruff check src tests
source .venv/bin/activate
make -C docs html SPHINXOPTS=-W

Changelog · API skill · Editable splash source

License

TCRen is distributed under the ISALGO LAB Academic and Non-Commercial Research License, version 1.0.

CPU budgets use threads=0 for automatic parallel work, capped at 16 allocated CPUs. Use 1 for serial work or a positive count to override the automatic cap within the scheduler/container allocation.