Machine Learning Dataset and Benchmark for Accurate T Cell Receptor-pHLA Binding Prediction

This repository contains the Hi-TPH dataset, a large-scale Hierarchical dataset for TCR-pHLA binding prediction, and corresponding codes used for data collection and benchmarks.

🌟 Overview of Hi-TPH

⚙️ Dependency

Install basic packages using env.yaml/requirements.txt or the following instructions:

conda create -n hitph python=3.8
conda activate hitph

# remove '-i https://pypi.tuna.tsinghua.edu.cn/simple/' if necessary
pip install pandas==2.0.3 numpy==1.24.3 scikit-learn tqdm jupyter notebook -i https://pypi.tuna.tsinghua.edu.cn/simple/

conda install pytorch==1.13.0 pytorch-cuda=11.6 -c pytorch -c nvidia
# pip --trusted-host pypi.tuna.tsinghua.edu.cn install torch==1.13.0+cu116 --extra-index-url https://download.pytorch.org/whl/cu116

pip install transformers==4.36.2 datasets==2.16.1 tokenizers==0.15.0 -i https://pypi.tuna.tsinghua.edu.cn/simple/

pip install tape_proteins biopython==1.83 -i https://pypi.tuna.tsinghua.edu.cn/simple/

# for plotting and running notebooks
conda install matplotlib seaborn jupyter notebook

An alternative Python 3.10 environment (AMPLIFY needs python>=3.10):

conda create -n py310 python=3.10
conda activate py310

pip install pandas==2.0 numpy==1.26 scikit-learn tqdm -i https://pypi.tuna.tsinghua.edu.cn/simple/

# AMPLIFY needs python>=3.10, torch==2.2, xformers==0.0.24, ...
# details see: https://github.com/chandar-lab/AMPLIFY/blob/main/pyproject.toml
pip install torch==2.2.0 xformers==0.0.24 --index-url https://download.pytorch.org/whl/cu118 -i https://pypi.tuna.tsinghua.edu.cn/simple/
pip install transformers==4.38 accelerate==0.27 deepspeed==0.13 -i https://pypi.tuna.tsinghua.edu.cn/simple/

pip install tape_proteins biopython==1.83 -i https://pypi.tuna.tsinghua.edu.cn/simple/

# for plotting and running notebooks
conda install matplotlib seaborn jupyter notebook

🔍 Data Curation

1. data_preprocess folder descripes detailed data collection and processing procedures.

   • check data_preprocess/README.md for instructions.

2. data details:

📊 Benchmarks

1. The split Level I-IV benchmark datasets are saved in benchmarks_dataset folder.

2. Run benchmarks of different levels as follows (in benchmarks folder):

   • [Settings] First, change the path in the following file to your own：

     • bash files in benchmarks/scripts: **_path, e.g., data_path.
     • plm_models.py in benchmarks: **_checkpoint, e.g., esm2_8m_checkpoint.

   • [Training] See benchmarks/scripts/train_**.sh to run train_main.py for training models.

     • If finetune PLMs, you need to add a line to the script with the parameter --finetune; if not finetune PLMs, remove it.

   • [Evaluation] After Training, you can test the model with test_main.py.

     • See benchmarks/scripts/eval_**.sh to run test_main.py

Note: we have uploaded checkpoints of Hi-TPH-PLMs to HuggingFace🤗: Jiadong001/Hi-TPH-PLMs.

👍 Acknowledgements

We thank the developers and maintainers of the public biological databases and datasets that enabled this work, including:

• Immune Epitope Database (IEDB)
• VDJdb
• McPAS-TCR
• ImmuneCODE
• IMMREP2023 evaluation dataset
• IMGT (Reference amino acid sequences for HLA alleles and human TCR genes)
• Open datasets from published/preprint studies (e.g., STAPLER)