SwiftTCR: Efficient computational docking protocol of TCRpMHC-I complexes using restricted rotation matrices
SwiftTCR is a fast fourier transform based rigid-body docking tool designed to dock T-cell receptors (TCR) to peptide-MHC complexes.
Manuscript link: SwiftTCR
- Optimized rigid-body docking of TCR-pMHC complexes
- Fast docking (~200 seconds on 12 CPU cores)
- Efficient clustering algorithms for data analysis
To get started with SwiftTCR, follow these steps:
- Clone this repository and navigate to it.
# Clone the repository
git clone [email protected]:X-lab-3D/swifttcr.git
# Move into the repository
cd swifttcr
SwiftTCR is built on Piper (v0.0.4). For academic use, Piper can be obtained by contacting Sandor Vajda's lab ([email protected]) or George Jones ([email protected]). When contacting them, make sure you request version v0.0.4.
For industrial use, a license agreement must be obtained through Acpharis Inc. or Schrödinger LLC.
You should receive a file called "piper_package.tar.bz2".
Unzip the file with:
tar -xvf piper_package.tar.bz2
#Make the piper folder
mkdir tools/piper
# Move piper
mv piper_package/* tools/piper/
In the end, you should have a tools/piper folder with all the piper components, inclusing the piper executable, inside your swifttcr folder.
- Conda >= 23.10.0
To quickly install all the necessary packages in a conda environment, you can use:
# Create the environment
conda env create -f swifttcr_install.yml
# Activate the environment
conda activate swifttcr
Done! You can now run SwiftTCR by running :
python3 scripts/swift_tcr.py -r </your/input/peptide-mhc> -l </your/input/tcr> -o <output_directory> -op <output_prefix> -c <number_of_cores> -t <clustering_threshold (default=3)> -m <amount_of_models_to_generate>Example command:
python3 scripts/swift_tcr.py -r example/input/pmhc_1/unbound_structures/3w0w/3w0w_pmhc_renumbered.pdb -l example/input/pmhc_1/unbound_structures/3w0w/3w0w_tcr.pdb -o example/output/ -op first_test -c 6 -t 3 -m 100Help You can get the arguments description by running:
python3 scripts/swift_tcr.py -hAll dependencies are installed by conda through the swifttcr_install.yml file. We report them here just for clarity:
- Python 3.9.12
- Pymol open source: 3.0.0
- anarci: 2021.02.04
- gradpose: 0.1
- pdb-tools: 2.5.0
- torch: 2.4.1
- pdb2sql: 0.5.3
- Biopython: 1.84
- PDB2PQR: 3.6.1
- Matplotlib: 3.9.2
- Plotly: 5.24.1
- A = MHC (Not IMGT numbered)
- B = β2m (Not IMGT numbered)
- C = Peptide (Not IMGT numbered)
- D = TCR Alpha Chain (IMGT numbered)
- E = TCR Beta Chain (IMGT numbered)
- A = The ABC Chains of original Peptide-MHC combined
- D = The Alpha and Beta chains of TCR combined
The output is a folder, named using the specified output prefix, created within the designated output directory. This folder contains the following files and subfolders:
output
└── example_output_folder
├── pmhc_pnon.ms
├── pmhc_pnon.pdb
├── pmhc_pnon_rename.pdb
├── clustering.txt
├── ft.000.00
├── irmsd.csv
├── merged
│ └── merged_0.pdb
├── renumbered_tcr.pdb
├── renumbered_tcr_pnon.ms
└── renumbered_tcr_pnon.pdb
A prepared peptide–MHC structure in .ms format. This file includes the definition of attractive residues in column 10 (0.0 or 1.0), which are used by the docking engine to bias or constrain interactions. In this file all peptide residues are selected for attraction (1).
A pdb2pqr-prepared peptide–MHC structure generated by prepare.py. The script performs several cleanup and normalization steps:
-
Chain extraction or assignment
-
If chains are specified, only those chains are kept.
-
If no chain ID is present, the script assigns chain A.
-
Backbone integrity filtering
Residues missing backbone atoms (N, CA, C) are removed.
pdb2pqr processing
The structure is passed through pdb2pqr (CHARMM force field) to
-
add missing atoms
-
assign charges and radii
-
standardize atom naming and geometry
-
CHARMM-specific atom fixes
-
ILE CD1 → CD conversion
-
Residues normalized to a complete CHARMM-compatible atom set
A version of the pMHC PDB where:
All chains have been renamed to chain A
Residue numbers have been offset by +1000 per chain to encode chain origin in the numbering.
Chain A → residues 1–999
Chain B → residues 1000–1999
Chain C → residues 2000–2999
This file contains the clustering results of all generated TCR–pMHC docking models. Each line reports a cluster center (a representative model) along with the number of neighboring models assigned to that cluster.
Example entry:
Cluster center: merged_23.pdb with 123 neighbors.
This means that merged_23.pdb is the representative structure for a cluster containing 123 models that are structurally similar according to the clustering metric (typically RMSD or interface RMSD).
The final line of the file reports the total number of clusters identified.
Raw PIPER docking output corresponding to coefficient set 00. This file contains the scored Fourier–transform–based docking solutions generated by PIPER.
For details on coefficient indexing and output structure, see for example:
tools/piper/piper --help
A comma-separated file containing the pairwise interface RMSD (iRMSD) between all generated merged models. Every model is compared against every other model, producing a matrix in long-table form.
Each row follows the format:
model_A, model_B, iRMSD_value
Example:
merged_0.pdb, merged_1.pdb, 0.7426182627677917
This indicates that the interface RMSD between merged_0.pdb and merged_1.pdb is 0.74 Å. All iRMSD values are calculated over the Carbon-alphas only and are reported in angstroms (Å).
A folder containing all predicted docked TCR–peptide–MHC structures generated during the modeling workflow.
Each file inside (e.g., merged_0.pdb, merged_1.pdb, …) represents a single docking model with the TCR positioned relative to the peptide–MHC according to its predicted binding pose.
TCR structure automatically renumbered to IMGT numbering using ANARCI. This process standardizes the TCR residue numbering according to IMGT numbering schemes, enabling consistent mapping of complementarity-determining regions (CDRs) and framework regions.
The same as the pmhc_pnon.ms but for tcr structure all the CDR loops are marked as attractive residues.
The renumbered TCR structure aligned to the reference TCR structure. In addition to the ANARCI renumbering, chain IDs have been modified to match the naming convention of the reference complex.
Currently, SwiftTCR only support pMHC-I complexes but we are currently experimenting with pMHC-II implementation. Star the project to follow for updates.
Here you can find useful tools that we use to generate input structures for SwiftTCR or to speed up SwiftTCR.
| Tool | Description | Link |
|---|---|---|
| Pandora | Fast and accurate pMHC modelling | https://github.com/X-lab-3D/PANDORA |
| TCRmodel2 | Accurate TCR modelling with AlphaFold2 | https://github.com/piercelab/tcrmodel2 |
| Gradpose | Ultra-fast large scale structures superposition | https://github.com/X-lab-3D/GradPose |