Metadata-Version: 2.4
Name: t2pmhc
Version: 1.1.3
Summary: A structure-informed graph neural network for predicting TCR-pMHC binding
Author: Mark Polster
License-Expression: MIT
Project-URL: Repository, https://github.com/qbic-pipelines/t2pmhc
Project-URL: Changelog, https://github.com/qbic-pipelines/t2pmhc/blob/main/CHANGELOG.md
Classifier: Programming Language :: Python :: 3.11
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: biopython>=1.85
Requires-Dist: joblib>=1.4
Requires-Dist: numpy<3,>=1.26
Requires-Dist: pandas>=2.1
Requires-Dist: rich>=13
Requires-Dist: rich-click>=1.9
Requires-Dist: scikit-learn<1.8,>=1.6
Requires-Dist: torch>=2.6
Requires-Dist: torch_geometric>=2.6
Dynamic: license-file

# t2pmhc

[![DOI](https://zenodo.org/badge/1098871676.svg)](https://doi.org/10.5281/zenodo.21410458)

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

<h1 align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="assets/t2pmhc_logo.png">
    <img alt="tpmhc" src="assets/t2pmhc_logo.png" width="500">
  </picture>
</h1>


# 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](https://github.com/phbradley/TCRdock).  
To predict TCR-pMHC structures with TCRdock you can use our branch of the [nf-core/proteinfold](https://github.com/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](https://github.com/mapo9/nf-core_proteinfold/tree/tcrdock) to create the docker container and run the pipeline.

Minimal samplesheet:  

```console
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:  

```console
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)) |
<br>

> 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)
<br>

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](https://github.com/qbic-pipelines/t2pmhc/tree/hyperparameter_search)

# 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
