t2pmhc

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

Prerequisites

t2pmhc has two 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.

Manual (conda/pip) installation. The manual installation has been tested on Linux (Rocky Linux 9.8 & Ubuntu 24.04) with Python 3.11 with the tool versions in the requirements.txt.

Installation

1. Docker

You can pull the image here:

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

2. Python

• 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 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.

All files are located in the example/ directory.

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

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

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> \

Publication

• 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