t2pmhc

t2pmhc: A Structure-Informed Graph Neural Network for Predicting TCR–pMHC Binding

Prerequisites

t2pmhc has three installation routes with different requirements.

Docker (recommended). The only requirement is a working Docker installation. Because the container bundles the full software environment, t2pmhc is platform-independent and produces identical results across operating systems.

PyPI. The quickest way to get the command line tool: pip install t2pmhc on Python 3.11 or newer.

From source with pinned dependencies. Clone the repository and install the exact tool versions from requirements.txt.

Installation

1. Docker

You can pull the image here:

docker pull ghcr.io/qbic-pipelines/t2pmhc:1.1.3

2. PyPI

pip install t2pmhc

This installs the t2pmhc command together with the published default models.

3. From source (exact dependency versions)

• Clone the repository

git clone https://github.com/qbic-pipelines/t2pmhc/

• cd into the repository

• Create a fresh conda env

conda create -n t2pmhc python=3.11

• Install the pinned dependency versions from requirements.txt

pip install -r requirements.txt

• Install t2pmhc locally

pip install -e .

Now you can use t2pmhc anywhere on your machine.

Quickstart

This example lets you verify your installation and see the expected input/output format before running your own analyses. It uses a small set of pre-computed TCRdock structures included in the repository, so you can skip structure prediction and run t2pmhc end-to-end in a few minutes.

Run the following two commands from the root of the repository.

1. Build the graphs from the example structures

t2pmhc create-t2pmhc-graphs \
    --mode t2pmhc-gcn \ 
    --samplesheet example/samplesheet_predict.tsv \ 
    --prediction-mode \ 
    --out example/graphs.pt

2. Predict binding using the published default model

t2pmhc t2pmhc-predict-binding \ 
    --mode t2pmhc-gcn \ 
    --samplesheet example/samplesheet_predict.tsv \ 
    --saved_graphs example/graphs.pt \ 
    --out example/samplesheet_predicted.tsv

The output example/samplesheet_predicted.tsv contains a binder_prob column with the binding probability assigned by t2pmhc.

Usage

Create pdb files

t2pmhc currently supports pdb files created with TCRdock.
To predict TCR-pMHC structures with TCRdock you can use our branch of the nf-core/proteinfold pipeline

TCRDock in nf-core proteinfold

Clone the repository and checkout to the tcrdock branch

1. git clone https://github.com/mapo9/nf-core_proteinfold
2. cd nf-core_proteinfold
3. git checkout tcrdock

See the documentation to create the docker container and run the pipeline.

Minimal samplesheet:

organism,mhc_class,mhc,peptide,va,ja,cdr3a,vb,jb,cdr3b,identifier
human,1,A*02:01:48,RLQSLQTYV,TRAV16*01,TRAJ39*01,CALSGFNNAGNMLTF,TRBV11-2*01,TRBJ2-3*01,CASSLGGAGGADTQYF,a2341ad
human,1,A*02:01:48,YLQPRTFLL,TRAV12-2*01,TRAJ30*01,CAVNRDDKIIF,TRBV7-9*01,TRBJ2-7*01,CASSPDIEQYF,223dse2

Column	Description
organism	'human'.
mhc_class	1
mhc	The MHC allele, e.g. 'A*02:01'
peptide	The peptide sequence.
va	V-alpha gene.
ja	J-alpha gene.
cdr3a	CDR3-alpha sequence, starts with C, ends with the F/W/etc right before the GXG sequence in the J gene.
vb	V-beta gene.
jb	J-beta gene.
cdr3b	CDR3-beta sequence, starts with C, ends with the F/W/etc right before the GXG sequence in the J gene.
identifier	Unique sample identifier.

Create t2pmhc graphs

t2pmhc expects TCRdock output as input for the graph generation step. Minimal samplesheet:

organism	mhc_class	mhc	peptide	va	ja	cdr3a	vb	jb	cdr3b	identifier	model_2_ptm_pae	pmhc_tcr_pae	target_chainseq pdb_file_path
human	1	A*02:01 RLQSLQTYV	TRAV16*01	TRAJ39*01	CALSGFNNAGNMLTF	TRBV11-2*01	TRBJ2-3*01	CASSLGGAGGADTQYF	1sr34	2.43	6.24	CALSGFNNAGNMLTF/RLQSLQTYV/CASSLGGAGGADTQYF  path/to/tcrdock/pdb
human	1	A*02:01	YLQPRTFLL	TRAV12-2*01	TRAJ30*01	CAVNRDDKIIF	TRBV7-9*01	TRBJ2-7*01	CASSPDIEQYF	223dse2	4.5	7.2	YLQPRTFLL/CAVNRDDKIIF/CASSPDIEQYF   path/to/tcrdock/pdb

Column	Description
organism	'human'.
mhc_class	1
mhc	The MHC allele, e.g. 'A*02:01'
peptide	The peptide sequence.
va	V-alpha gene.
ja	J-alpha gene.
cdr3a	CDR3-alpha sequence, starts with C, ends with the F/W/etc right before the GXG sequence in the J gene.
vb	V-beta gene.
jb	J-beta gene.
cdr3b	CDR3-beta sequence, starts with C, ends with the F/W/etc right before the GXG sequence in the J gene.
identifier	Unique sample identifier.
model_2_ptm_pae	PAE of the complex (provided by TCRdock).
pmhc_tcr_pae	TCR-pMHC specific PAE value (provided by TCRdock).
target_chainseq	Full sequence of the complex (MHC/peptide/TCRA/TCRB) (provided by TCRdock).
pdb_file_path	Path to the PDB file created by TCRdock. (must have _<LABEL>.pdb suffix if used for training (LABEL=0/1))

The TCRDock pipeline produces npy files containing the PAEs, named after their respective PDB files with the suffix _predicted_aligned_error.npy. These files must reside in the same directory as the PDB files. If training mode is activated, the label must be present before this suffix.

If the graphs are created for training (--training-mode), the PDB files must have the binder status (LABEL) as suffix (e.g. sample01_0.pdb), same for respective PAE files (e.g. sample01_0_predicted_aligned_error.npy)

To create the graphs expected by the models from the pdb files, you can run the following command:

t2pmhc create-t2pmhc-graphs \
    --mode <t2pmhc-gcn,t2pmhc-gat> \
    --samplesheet samplesheet.tsv \
    --training-mode / --prediction-mode \
    --out <path/to/graphs.pt> \
    --threshold <distance in Å> (optional, default: 10.0)

Train t2pmhc models

t2pmhc-gcn

t2pmhc train-t2pmhc-gcn \
    --run_name <name to save model under> \
    --hyperparameters path/to/t2pmhc/t2pmhc/data/hyperparams/t2pmhc_gcn.json \
    --samplesheet samplesheet.tsv \
    --saved_graphs <path/to/graphs.pt> \
    --save_model <path/to/model_dir>

t2pmhc-gat

t2pmhc train-t2pmhc-gat \
    --run_name <name to save model under> \
    --hyperparameters path/to/t2pmhc/t2pmhc/data/hyperparams/t2pmhc_gat.json \
    --samplesheet samplesheet.tsv \
    --saved_graphs <path/to/graphs.pt> \
    --save_model <path/to/model_dir>

Predict binder status of TCR-pMHC samples

You can either use a model you trained or use the published default models to predict the binder status for your TCR-pMHC complexes.
The resulting tsv file will contain the column binder_prob containing the binding probability of the complex assigned by t2pmhc.

Default mode

t2pmhc t2pmhc-predict-binding \
    --mode <t2pmhc-gcn, t2pmhc-gat> \
    --samplesheet samplesheet.tsv \
    --saved_graphs <path/to/graphs.pt> \
    --out samplesheet_predicted.tsv

Retrained mode

t2pmhc t2pmhc-predict-binding \
    --mode <t2pmhc-gcn, t2pmhc-gat> \
    --samplesheet samplesheet.tsv \
    --saved_graphs <path/to/graphs.pt> \
    --out samplesheet_predicted.tsv \
    --model <model.pt> \
    --pae_scaler_structure <pae_node_FULL.pkl> \
    --pae_scaler_tcrpmhc <pae_node_TCRPMHC.pkl> \
    --hydro_scaler <hydro_scaler.pkl> \
    --distance_scaler <distance_scaler.pkl> \
    --pae_scaler_edge <pae_edge_FULL.pkl> \

Evaluation and benchmarking

This repository contains model training and inference. The evaluation and benchmarking code for the t2pmhc publication is maintained separately in qbic-pipelines/t2pmhc_benchmark, a Nextflow (nf-core template) pipeline that runs t2pmhc together with all benchmarked competitors. It implements the construction of the leakage-free evaluation subsets, inference for every benchmarked predictor, and the per-peptide AUC evaluation and statistical tests reported in the paper. The evaluation protocol is documented in full in that repository's README.

Reported performance is the mean per-peptide AUC. An AUC is computed within each peptide and averaged across peptides, so that every peptide contributes equally and only the within-peptide ranking of TCRs is scored. Pooled AUCs over all TCR-pMHC pairs of a dataset are computed alongside the per-peptide values. Cross-validation is used for hyperparameter search and the ablation experiments (branches hyperparameter_search, pae_ablation_experiment, angstrom_threshold_experiment).

• you can find the hyperparameter search here

Citations

If you use t2pmhc, please cite the article as follows:

t2pmhc: A Structure-Informed Graph Neural Network to Predict TCR-pMHC Binding

Polster M, Stadelmaier J, De Gottardi R, Ball E, Scheid J, Bauer J, Nelde A, Claassen M, Dubbelaar ML, Walz JS, Nahnsen S. t2pmhc: A Structure-Informed Graph Neural Network to predict TCR-pMHC Binding. bioRxiv 2026.02.27.708137. doi:10.64898/2026.02.27.708137

To cite a specific software version, use the archived release: doi:10.5281/zenodo.21410458