Paraplume: A fast and accurate paratope prediction method provides insights into repertoire-scale binding dynamics

This is the repository containing data to reproduce results of the paper. We release three separate folders. I - BENCHMARK.TAR.GZ (comes with pecan.tar.gz paragraph.tar.gz and mipe.tar.gz) This is the folder where comparisons with other methods were made. - We used the **mipe**, **pecan** and **paragraph** datasets. - In the `Scripts` folder, bash scripts starting with `create_datasets` were used to create labeled datasets. It takes as input a csv files present in the `dataset` folder and a folder of 3D structures from SabDab. - The structures used for the paragraph dataset are in the `structures/imgt_renumbered_expanded` folder, structures for the pecan dataset in `structures/imgt_renumbered_pecan`, and for mipe dataset, in `structures/imgt_renumbered_mipe`. For the mipe dataset we also modeled structures using ABB3 to re-benchmark Paragraph without experimentally solved structures as inputs on their dataset. This is because we found that the results displayed for Paragraph in the MIPE paper were surprisingly low. All structures were IMGT renumbered to correct numbering errors. - The `create_dataset` scripts create two files: a `.json` file with the sequences and their paratope labels, and a `.pt` file with the embeddings of each sequence. - Script `train_mipe.sh` (resp. `train_paragraph.sh` and `train_pecan.sh`) was used to train Paraplume on the mipe (resp. paragraph and pecan) dataset. Script `train_mipe_3D.sh` (resp. pecan and paragraph) trains Paragraph on the mipe (resp. paragraph and pecan) dataset, which was needed to create Paraplume-G, the combination of Paraplume and Paragraph. - Scripts starting by `chain_study` were used to test the trained models on single chains only. Results are saved in the `mipe`, `paragraph` and `pecan` folders. - In `6b0s` we analyze the predictions of Paraplume trained on the Paragraph train set on an unseen sequence in the test set: antibody with PDB code 6b0s. We used PyMol to compare the predictions with the ground truth. - Benchmark for Paraplume was done using `benchmark/paraplume_requirements.txt` - Benchmark for Paraplume-G was done using `benchmark/paraplume_G_requirements.txt` ⚠️ NOTE: 1. If reproducing the results, some of the folder/file paths might need changing. 2. The paragraph, pecan and mipe folders were inside benchmark but were uploaded separately for convenience. Contact [e-mail] if you need help. II - DATAWITHSCRIPTS.TAR.GZ This is the folder where we we used Paragraph to analyze data. - Paragraph was trained on 1000 structures from the whole expanded dataset of Paragraph, with early stopping done on a vlidation set of 85 structures to stop training before over-fitting. PDB `4FQI` was excluded from the train and validation sets as we analyze variants of this antibody. Training and validation sets are available in `benchmark/datasets/paragraph_all_expanded`. - All analyses on antibody repertoires (figures 4-5) were done in `repertoire_analysis`. The `repertoire_analysis/briney` folder contains sequences and germlines with paratope predictions (files starting with `paratope`) from the healthy human donor 316188 of this [study](https://www.nature.com/articles/s41586-019-0879-y). The `repertoire_analysis/hifibio&naive_mice` folder contains all sequences and germlines along with paratope predictions for the immunized mouse repertoire, sorted for binding to tetanos toxin by HiFiBiO in 2020 ([paper](https://www.researchgate.net/publication/340288245_High-throughput_single-cell_activity-based_screening_and_sequencing_of_antibodies_using_droplet_microfluidics)), as well as for the naive mouse repertoire ([paper](https://pubmed.ncbi.nlm.nih.gov/31428692/)). The `repertoire_analysis/philipps` folder contains all paratope predictions for the Deep Mutational Scan on a broadly neutralizing antibody of this [study](https://pubmed.ncbi.nlm.nih.gov/34491198/). - Work on sequence representation (figure 6) was done in the `data_with_scripts/sequence_representation` subfolder. Comparisons of the unweighted and paratope weighted were done for affinity, binder classification, epitope binning and expression in the corresponding subfolders. - Study of the paratope asymmetry (figure3, including data curation needed for the study) is done in folder `data_with_scripts/paratope_asymmetry`. - Use of the paratope asymmetry to compute an upper bound of sequence-based paratope prediction methods (table3) was done in folder `data_with_scripts/paratope_limits`. - Speed and CO2 emissions comparisons were done in `data_with_scripts/speed_tests` - Paratope inference was done using `benchmark/paraplume_requirements.txt`. All other analyses, including figures, were done under `data_with_scripts/analysis.txt` - Code for all figures is available in `data_with_scripts/figure_notebooks` ⚠️ **Note**: If reproducing the results, some of the folder/file paths might need changing. Contact [e-mail] if you need help. III - GRAPHEXTENSION.TAR.GZ This is the folder where we implemented the Paragraph method from [here](https://github.com/oxpig/Paragraph). More specifically we use the implementation of the EGNN from lucidrain (`EGNN.py`) and the Paragraph's model (`model.py`). `train_graph_light.py` trains the model, `evaluate_graph.py` evaluates performance on the test set, `predict_graph.py` fills the occupancy and betafactor columns of PDBs in the test set with labels and predictions to visualize te results. `graph_torch_dataset.py` is a dataloader for the model.