isalgo/vdjdb_structure_models

Predicted structures for VDJdb records

This repository contains structure data for selected VDJdb records obtained using AI-based modelling in data/ folder:

• —pdb_files.tgz contains predicted TCR:pMHC structures with canonical chain names, orientation and placement, superimposed by aligning and rotation. File names start with tcr_pmhc_hash which must be used for connecting the structure with the VDJdb record.
• —pdb_files_native.tgz contains real TCR:pMHC structures from PDB, processed to canonical coordinated in the same way as pdb_files.tgz.
• —coordinates_aa.tgz contains tables with amino acid Ca atom coordinates for each residue of deposited structures.
• —contacts_aa.tgz contains files with residue pairs at a distance <= 5A for each of the deposited structures. Currently only TCR alpha CDR3-peptide and beta CDR3-peptide are considered.
• —complementarity_maps.tgz and complementarity_maps_simplified.tgz contains 2D projections of TCR alpha CDR3, TCR beta CDR3 and peptide residue coordinates in for of SVG plots produced by matplotlib.

Metadata for all structures is concatenated with corresponding VDJdb record metadata and stored in vdjdb_structures_metadata.tsv.gz. The file contains default VDJdb "full table" columns together with the following columns calculated for each structure:

• —num_contacts - number of contacts in the available structure between TCR and peptide.
• —ranking_confidence, plddt, ptm, iptm, tcr_pmhc_iptm - TCRmodel2 quality metrics (for more information please visit TCRmodel2 webpage).
• —scanning_angle and pitch_angle - scanning and pitch TCR:pMHC structure angles calculated with STCRpy.
• —is_native - whether the structure is experimentally acquired (from PDB) or predicted.
• —tcr_pmhc_hash - unique TCR:pMHC record hash for matching predicted structure PDBs.

Contents at a glance

A metadata row without a matching PDB is normal — the file set is the subset that modelled and passed QC. Join on tcr_pmhc_hash; predicted filenames are aligned_aligned_<hash>.pdb, natives are aligned_<pdbid>.pdb.

Provenance

• —TCR:epitope pairings are EXPERIMENTAL — VDJdb records, carried through with the full VDJdb "full table" columns (reference.id, method.*, meta.*, vdjdb.score).
• —Predicted structures are COMPUTED (TCRmodel2/AlphaFold). ranking_confidence, plddt, ptm, iptm, tcr_pmhc_iptm are the generator's own confidence metrics, not measurements.
• —Native structures are EXPERIMENTAL (RCSB), re-processed into the same canonical frame.
• —Derived columns (num_contacts, scanning_angle, pitch_angle) are computed from the deposited coordinates — for predicted rows they inherit the model's error, and the angles in particular track AlphaFold confidence rather than being independent of it.

Used by

The TCRen2 receptor-ranking benchmark (isalgo/tcren_structures) draws its real-binder positives from this pool — filtered to is_native == False, restricted to hashes present in pdb_files.tgz, and with TCRvdb pairs excluded — then matches them per epitope against the decoys in isalgo/tcren_structures::vdjdb_negatives/ and ::immrep23_negatives/. See isalgo/tcren_structures::vdjdb_binder_benchmark/README.md.