Project leads: Kevin Bijan Givechian, Joรฃo Felipe Rocha, Chen Liu.
Correspondence: akiko.iwasaki@yale.edu, smita.krishnaswamy@yale.edu.
In case you don't have access to Nature, here are the main paper and the supplementary materials.
Table of Contents
News in English
-white){kind=icon}
-white){kind=icon}
News in Chinese
-white){kind=icon}
โ TODO: create and release an end-to-end tool.
โ
Feb 20, 2026: The multimodal datasets and model weights are now open-sourced. See instructions.
โ
Dec 31, 2025: Published in Nature Machine Intelligence.
โ
Dec 04, 2025: Informally presented at NeurIPS 2025 (did not submit, no dual-submission concern).
โ
Aug 18, 2025: Received the Colton Innovation Fund from Colton Center for Autoimmunity at Yale University.
โ
May 06, 2025: Submitted to Nature Machine Intelligence.
โ
Nov 05, 2024: Presented at MoML@MIT 2024 (non-archival abstract & poster).
โ
Nov 01, 2024: Preprint released.
ImmunoStruct is a multimodal deep learning framework that integrates sequence, structural, and biochemical information to predict multi-allele class-I peptide-MHC immunogenicity. By leveraging multimodal data from 26,049 peptide-MHCs and jointly modeling sequence and structure, ImmunoStruct significantly improves immunogenicity prediction performance for both infectious disease epitopes and cancer neoepitopes.
- Multimodal Integration: Combines peptide-MHC protein sequence, structure, and biochemical properties
- Novel Cancer-Wildtype Contrastive Learning: Enhances specificity for cancer neoepitope detection
- Enhanced Interpretability: Provides insights into the substructural basis of immunogenicity
If you use ImmunoStruct in your research, please cite our paper:
BibTeX:
@article{givechian2026immunostruct,
title={ImmunoStruct enables multimodal deep learning for immunogenicity prediction},
author={Givechian, Kevin Bijan and Rocha, Jo{\~a}o Felipe and Liu, Chen and Yang, Edward and Tyagi, Sidharth and Greene, Kerrie and Ying, Rex and Caron, Etienne and Iwasaki, Akiko and Krishnaswamy, Smita},
journal={Nature Machine Intelligence},
volume={8},
pages={70--83},
year={2026},
publisher={Nature Publishing Group UK London}
}Nature format:
Givechian, K.B., Rocha, J.F., Liu, C. et al. ImmunoStruct enables multimodal deep learning for immunogenicity prediction. Nat Mach Intell 8, 70โ83 (2026). https://doi.org/10.1038/s42256-025-01163-y
To get ImmunoStruct up and running locally, follow these steps.
Before installation, ensure you have:
- CUDA-compatible GPU (recommended)
- Conda package manager
- Weights & Biases account for experiment tracking
-
Clone the repository
git clone https://github.com/KrishnaswamyLab/ImmunoStruct.git cd ImmunoStruct -
Create conda environment and install dependencies
conda create --name immuno python=3.8 -c anaconda -c conda-forge -y conda activate immuno conda install cudatoolkit=11.2 wandb pydantic -c conda-forge -y conda install scikit-image pillow matplotlib seaborn tqdm -c anaconda -y python -m pip install torch==2.1.2 torchvision==0.16.2 torchaudio==2.1.2 --index-url https://download.pytorch.org/whl/cu118 python -m pip install dgl -f https://data.dgl.ai/wheels/torch-2.1/cu118/repo.html python -m pip install torchdata==0.7.1 python -m pip install torch-scatter==2.1.2+pt21cu118 torch-sparse==0.6.18+pt21cu118 torch-cluster==1.6.3+pt21cu118 torch-spline-conv==1.2.2+pt21cu118 torch_geometric==2.5.3 numpy==1.21.1 -f https://data.pyg.org/whl/torch-2.1.2+cu118.html python -m pip install jax==0.2.25 jaxlib==0.1.69+cuda111 -f https://storage.googleapis.com/jax-releases/jax_cuda_releases.html python -m pip install "alphafold-colabfold==2.0.0" "colabfold==1.2.0" "dm-haiku==0.0.4" python -m pip install "biopython==1.78" python -m pip install graphein[extras] python -m pip install lifelines python -m pip install huggingface_hub python -m pip install ipykernel python -m pip install ipywidgets
The following steps might be necessary if you encounter problems when running the inference. These are some package incompatibilities that we managed to resolve in a manual way:
- Go to
PATH_TO_ENV/lib/python3.8/site-packages/jaxlib/xla_client.py: changenp.objecttoobject. - Go to
PATH_TO_ENV/lib/python3.8/site-packages/alphafold/common/residue_constants.py: changenp.inttonp.int32. - Go to
PATH_TO_ENV/lib/python3.8/site-packages/alphafold/data/templates.py: changenp.objecttoobject.
- Go to
-
Create and build another environment for obtaining MSAs locally. Only relevant if you want to run your own protein folding.
conda create --name local_msa python=3.10 -c anaconda -c conda-forge -y conda activate local_msa conda install cudatoolkit=11.2 wandb pydantic -c conda-forge -y conda install scikit-image pillow matplotlib seaborn tqdm -c anaconda -y python -m pip install torch==2.1.2 torchvision==0.16.2 torchaudio==2.1.2 --index-url https://download.pytorch.org/whl/cu118 pip install colabfold[alphafold]==1.5.5 pip install jax==0.4.23 jaxlib==0.4.23+cuda11.cudnn86 -f https://storage.googleapis.com/jax-releases/jax_cuda_releases.html conda install -c bioconda mmseqs2 -y
-
Download the dataset from huggingface. You need to sign up for huggingface when prompted. Starting at the project root (
ImmunoStruct):conda activate immuno cd ./data/ hf download ChenLiu1996/ImmunoStruct --repo-type dataset --local-dir ./ -
Download the pre-trained model weights from huggingface. Starting at the project root (
ImmunoStruct):cd ./checkpoints/ hf download ChenLiu1996/ImmunoStruct --local-dir ./ -
Make sure the following files are in the
datafolder:ImmunoStruct_IEDB_data.csvImmunoStruct_CEDAR_data_cancer.csvImmunoStruct_CEDAR_data_wildtype.csvImmunoStruct_clinical_data.csvImmunoStruct_clinical_data_survival.csvHLA_allele_sequences.csv
-
Unzip the graph structure PyTorch files.
unzip graph_pyg_IEDB.zip unzip graph_pyg_CEDAR_cancer.zip unzip graph_pyg_CEDAR_wildtype.zip unzip graph_pyg_clinical.zip
Now the following folders should be under the
datafolder:graph_pyg_IEDBgraph_pyg_CEDAR_cancergraph_pyg_CEDAR_wildtypegraph_pyg_clinical
-
If you want to customize the graph-building logic, the graph structure PDB files produced by AlphaFold2 are already made available by the same huggingface download command. Unzip the corresponding zip files and you will have the following folders.
alphafold2_pdb_IEDBalphafold2_pdb_CEDAR_canceralphafold2_pdb_CEDAR_wildtypealphafold2_pdb_clinical
We have provided the structure data encoded as PyTorch Geometric (PyG) graphs on huggingface. You just need to follow the instruction in the previous Data Preparation section. You can skip this section if you are not planning to fold your own data.
How the PyG graphs are generated
The PyG graphs are generated using the following steps. The generation scripts are available in immunostruct/preprocessing, in case you ever need to run some or all of them.
- Option 1 is easy to perform, but it's slow and rate-limited.
- Option 2 involves more steps, but it is more suitable to larger datasets (>2000 sequences).
-
Option 1: Using the online MSA server (slow, rate-limited, not recommended for >2000 sequences). Starting at
ImmunoStructroot folder.# [CPU] Step 1-3. Prepare MSA for AlphaFold. # Download colabfold and REMEMBER where it is downloaded to. Likely default to `~/.cache/colabfold`. python -m colabfold.download # Prepare MSA. conda activate immuno cd immunostruct/preprocessing python step1-3_server_sequence_to_msa.py \ --input-csv ../../data/ImmunoStruct_IEDB_data.csv \ --output-dir ../../data/pdb_files/IEDB/ \ --tmp-dir /tmp/ \ --allele-col-name allele \ --peptide-col-name peptide python step1-3_server_sequence_to_msa.py \ --input-csv ../../data/ImmunoStruct_CEDAR_data_cancer.csv \ --output-dir ../../data/pdb_files/CEDAR_cancer/ \ --tmp-dir /tmp/ \ --allele-col-name allele \ --peptide-col-name mut_pep python step1-3_server_sequence_to_msa.py \ --input-csv ../../data/ImmunoStruct_CEDAR_data_wildtype.csv \ --output-dir ../../data/pdb_files/CEDAR_wildtype/ \ --tmp-dir /tmp/ \ --allele-col-name allele \ --peptide-col-name wt_pep python step1-3_server_sequence_to_msa.py \ --input-csv ../../data/ImmunoStruct_clinical_data.csv \ --output-dir ../../data/pdb_files/clinical/ \ --tmp-dir /tmp/ \ --allele-col-name allele \ --peptide-col-name mut_pep # [GPU] Step 4. AlphaFold2. # start/end help run multiple jobs in parallel. python step4_msa_to_pdb.py \ --input-csv ../../data/ImmunoStruct_IEDB_data.csv \ --output-dir ../../data/pdb_files/IEDB/ \ --start 0 --end 24540 \ --params-loc /path/to/colabfold \ --allele-col-name allele \ --peptide-col-name peptide python step4_msa_to_pdb.py \ --input-csv ../../data/ImmunoStruct_CEDAR_data_cancer.csv \ --output-dir ../../data/pdb_files/CEDAR_cancer/ \ --start 0 --end 2801 \ --params-loc /path/to/colabfold \ --allele-col-name allele \ --peptide-col-name mut_pep python step4_msa_to_pdb.py \ --input-csv ../../data/ImmunoStruct_CEDAR_data_wildtype.csv \ --output-dir ../../data/pdb_files/CEDAR_wildtype/ \ --start 0 --end 2801 \ --params-loc /path/to/colabfold \ --allele-col-name allele \ --peptide-col-name wt_pep python step4_msa_to_pdb.py \ --input-csv ../../data/ImmunoStruct_clinical_data.csv \ --output-dir ../../data/pdb_files/clinical/ \ --start 0 --end 29485 \ --params-loc /path/to/colabfold \ --allele-col-name allele \ --peptide-col-name mut_pep # [CPU] Step 5. Moving and renaming the structure data in PDB files. python step5_rename_pdb.py \ --input-dir ../../data/pdb_files/IEDB/ \ --output-dir ../../data/alphafold2_pdb_IEDB/ python step5_rename_pdb.py \ --input-dir ../../data/pdb_files/CEDAR_cancer/ \ --output-dir ../../data/alphafold2_pdb_CEDAR_cancer/ python step5_rename_pdb.py \ --input-dir ../../data/pdb_files/CEDAR_wildtype/ \ --output-dir ../../data/alphafold2_pdb_CEDAR_wildtype/ python step5_rename_pdb.py \ --input-dir ../../data/pdb_files/clinical/ \ --output-dir ../../data/alphafold2_pdb_clinical/ # [CPU] Step 6. Generating PyG graphs (structures in PDB files to structures in PyTorch .pt files). python step6_pdb_to_pyg.py \ --input-dir ../../data/alphafold2_pdb_IEDB/ \ --output-dir ../../data/graph_pyg_IEDB/ python step6_pdb_to_pyg.py \ --input-dir ../../data/alphafold2_pdb_CEDAR_cancer/ \ --output-dir ../../data/graph_pyg_CEDAR_cancer/ python step6_pdb_to_pyg.py \ --input-dir ../../data/alphafold2_pdb_CEDAR_wildtype/ \ --output-dir ../../data/graph_pyg_CEDAR_wildtype/ python step6_pdb_to_pyg.py \ --input-dir ../../data/alphafold2_pdb_clinical/ \ --output-dir ../../data/graph_pyg_clinical/
-
Option 2: Performing MSA locally (what we did). Starting at
ImmunoStructroot folder.# [CPU] Step 1-3. Prepare MSA for AlphaFold. # Download colabfold and REMEMBER where it is downloaded to. python -m colabfold.download # Download the MSA database locally. mkdir ./database_msa/ cd ./database_msa/ wget https://wwwuser.gwdg.de/~compbiol/colabfold/uniref30_2302.tar.gz tar -xzvf uniref30_2302.tar.gz mmseqs tsv2exprofiledb uniref30_2302 uniref30_2302_db wget https://wwwuser.gwdg.de/~compbiol/colabfold/colabfold_envdb_202108.tar.gz tar -xzvf colabfold_envdb_202108.tar.gz mmseqs tsv2exprofiledb colabfold_envdb_202108 colabfold_envdb_202108_db cd .. # Prepare MSA. conda activate local_msa cd immunostruct/preprocessing python step1_local_sequence_to_fasta.py \ --input-csv ../../data/ImmunoStruct_IEDB_data.csv \ --output-fasta ../../data/fasta/ImmunoStruct_IEDB_data.fasta \ --allele-col-name allele \ --peptide-col-name peptide python step2_local_fasta_to_a3m.py \ --input-fasta ../../data/fasta/ImmunoStruct_IEDB_data.fasta \ --msa-database-dir ../../database_msa/ \ --output-dir ../../data/a3m/IEDB/ python step3_local_a3m_to_msa.py \ --input-dir ../../data/a3m/IEDB/ \ --output-dir ../../data/pdb_files/IEDB/ \ --input-csv ../../data/ImmunoStruct_IEDB_data.csv \ --allele-col-name allele \ --peptide-col-name peptide python step1_local_sequence_to_fasta.py \ --input-csv ../../data/ImmunoStruct_CEDAR_data_cancer.csv \ --output-fasta ../../data/fasta/ImmunoStruct_CEDAR_data_cancer.fasta \ --allele-col-name allele \ --peptide-col-name mut_pep python step2_local_fasta_to_a3m.py \ --input-fasta ../../data/fasta/ImmunoStruct_CEDAR_data_cancer.fasta \ --msa-database-dir ../../database_msa/ \ --output-dir ../../data/a3m/CEDAR_cancer/ python step3_local_a3m_to_msa.py \ --input-dir ../../data/a3m/CEDAR_cancer/ \ --output-dir ../../data/pdb_files/CEDAR_cancer/ \ --input-csv ../../data/ImmunoStruct_CEDAR_data_cancer.csv \ --allele-col-name allele \ --peptide-col-name mut_pep python step1_local_sequence_to_fasta.py \ --input-csv ../../data/ImmunoStruct_CEDAR_data_wildtype.csv \ --output-fasta ../../data/fasta/ImmunoStruct_CEDAR_data_wildtype.fasta \ --allele-col-name allele \ --peptide-col-name wt_pep python step2_local_fasta_to_a3m.py \ --input-fasta ../../data/fasta/ImmunoStruct_CEDAR_data_wildtype.fasta \ --msa-database-dir ../../database_msa/ \ --output-dir ../../data/a3m/CEDAR_wildtype/ python step3_local_a3m_to_msa.py \ --input-dir ../../data/a3m/CEDAR_wildtype/ \ --output-dir ../../data/pdb_files/CEDAR_wildtype/ \ --input-csv ../../data/ImmunoStruct_CEDAR_data_wildtype.csv \ --allele-col-name allele \ --peptide-col-name wt_pep python step1_local_sequence_to_fasta.py \ --input-csv ../../data/ImmunoStruct_clinical_data.csv \ --output-fasta ../../data/fasta/ImmunoStruct_clinical_data.fasta \ --allele-col-name allele \ --peptide-col-name mut_pep python step2_local_fasta_to_a3m.py \ --input-fasta ../../data/fasta/ImmunoStruct_clinical_data.fasta \ --msa-database-dir ../../database_msa/ \ --output-dir ../../data/a3m/clinical/ python step3_local_a3m_to_msa.py \ --input-dir ../../data/a3m/clinical/ \ --output-dir ../../data/pdb_files/clinical/ \ --input-csv ../../data/ImmunoStruct_clinical_data.csv \ --allele-col-name allele \ --peptide-col-name mut_pep # [GPU] Step 4. AlphaFold2. # start/end help run multiple jobs in parallel. conda deactivate conda activate immuno python step4_msa_to_pdb.py \ --input-csv ../../data/ImmunoStruct_IEDB_data.csv \ --output-dir ../../data/pdb_files/IEDB/ \ --start 0 --end 24540 \ --params-loc /path/to/colabfold \ --allele-col-name allele \ --peptide-col-name peptide python step4_msa_to_pdb.py \ --input-csv ../../data/ImmunoStruct_CEDAR_data_cancer.csv \ --output-dir ../../data/pdb_files/CEDAR_cancer/ \ --start 0 --end 2801 \ --params-loc /path/to/colabfold \ --allele-col-name allele \ --peptide-col-name mut_pep python step4_msa_to_pdb.py \ --input-csv ../../data/ImmunoStruct_CEDAR_data_wildtype.csv \ --output-dir ../../data/pdb_files/CEDAR_wildtype/ \ --start 0 --end 2801 \ --params-loc /path/to/colabfold \ --allele-col-name allele \ --peptide-col-name wt_pep python step4_msa_to_pdb.py \ --input-csv ../../data/ImmunoStruct_clinical_data.csv \ --output-dir ../../data/pdb_files/clinical/ \ --start 0 --end 29485 \ --params-loc /path/to/colabfold \ --allele-col-name allele \ --peptide-col-name mut_pep # [CPU] Step 5. Moving and renaming the structure data in PDB files. python step5_rename_pdb.py \ --input-dir ../../data/pdb_files/IEDB/ \ --output-dir ../../data/alphafold2_pdb_IEDB/ python step5_rename_pdb.py \ --input-dir ../../data/pdb_files/CEDAR_cancer/ \ --output-dir ../../data/alphafold2_pdb_CEDAR_cancer/ python step5_rename_pdb.py \ --input-dir ../../data/pdb_files/CEDAR_wildtype/ \ --output-dir ../../data/alphafold2_pdb_CEDAR_wildtype/ python step5_rename_pdb.py \ --input-dir ../../data/pdb_files/clinical/ \ --output-dir ../../data/alphafold2_pdb_clinical/ # [CPU] Step 6. Generating PyG graphs (structures in PDB files to structures in PyTorch .pt files). python step6_pdb_to_pyg.py \ --input-dir ../../data/alphafold2_pdb_IEDB/ \ --output-dir ../../data/graph_pyg_IEDB/ python step6_pdb_to_pyg.py \ --input-dir ../../data/alphafold2_pdb_CEDAR_cancer/ \ --output-dir ../../data/graph_pyg_CEDAR_cancer/ python step6_pdb_to_pyg.py \ --input-dir ../../data/alphafold2_pdb_CEDAR_wildtype/ \ --output-dir ../../data/graph_pyg_CEDAR_wildtype/ python step6_pdb_to_pyg.py \ --input-dir ../../data/alphafold2_pdb_clinical/ \ --output-dir ../../data/graph_pyg_clinical/
Compute the biochemical meta-properties (Mprop1 / Mprop2):
Mprop1 and Mprop2 are the 2-d property vector each model consumes. The
tables in data/ already carry them; this step computes them for a new dataset
or a new set of peptides.
pip install peptides==0.5.0 mdtrajOne table is processed per run, with --dataset selecting which column spec to
apply:
python immunostruct/preprocessing/biochem_properties.py \
--dataset cedar_wt \
--in-table my_peptides.csv \
--out-table my_peptides_with_mprop.csv--out-table is always a new file; input tables are never written to. Add
--reuse-existing-props to keep a table's own descriptor columns instead of
recomputing them from sequence, and --scaler-out to record the fitted min/max
ranges as JSON.
The pipeline. Five stages, from peptide sequence and pMHC structure to the
2-D vector the models consume via nn.Linear(2, 32):
- 84 biochemical properties per peptide from the
peptidespackage โ the 75 descriptor-scale columns listed inDESCRIPTORS_75plus 9 scalars. The package version is pinned because.descriptors()returns 102 keys in 0.5.0, so the original 75 are selected explicitly rather than taken from whatever the call returns. - SASA via
mdtraj.shrake_rupley(probe_radius=0.14,n_sphere_points=960). The structures are a single fused chain of 272 MHC residues followed by the 9โ11mer, so the default--sasa-mode peptide_tailsums over the trailing peptide residues; - Structure join. Files are named
rank_1_prediction_Immuno<HLA><peptide>_<5hex>.pdb, where the key issha1(hla_seq + peptide)[:5]. - Smoothing.
QuantileTransformeron the foreignness score, thengaussian_filter1d(sigma 3 for foreignness, 5 for IEDB SASA, 3 for cedar SASA). - Meta-properties. Each of
Mprop1,Mprop2andmaster_property_scoreis the mean of a min-max-scaled subset of the columns above. The per-dataset member lists are inSPECSand are fixed inputs.
Two consequences of stages 4 and 5 are worth knowing, because they make the features table-level rather than per-peptide:
gaussian_filter1druns along the DataFrame row axis, so the input table must be passed in its original row order. Sorting or filtering upstream changes every output value, and a single peptide cannot be scored alone.MinMaxScaleris fit over the whole table, so the values are dataset-relative.--scaler-outwrites the fitted ranges to JSON for reuse.
Structures
The SASA stage reads pMHC structures from the folder given to --pdb-dir, in
the same way the graph construction step above reads its AlphaFold folders.
Place them under data/, for example data/alphafold_pdb_cedar/.
Each row is matched to a file by the 5-hex suffix of its filename, which is
sha1(hla_seq + peptide)[:5] -- the same key the graph pipeline uses. AlphaFold
output named rank_1_prediction_Immuno<HLA><peptide>_<5hex>.pdb therefore joins
without renaming. Rows with no matching structure get NaN, and the run reports
how many.
The key comes from the table's file_id_code or id column when present.
Putting a new cohort on an existing scale
Two stages fit on the rows present: the QuantileTransformer over the
foreignness column, and the MinMaxScaler over each meta-property's inputs. A
cohort processed on its own therefore lands on its own scale. To place it on the
scale of one of the tables in data/, append it to that table and process the
two together, keeping the reference rows first and in their original order:
import pandas as pd
ref = pd.read_table("data/cedar_data_final_with_mprop1_mprop2_v2.txt")
new = pd.read_table("new_cohort.txt")
pd.concat([ref, new], ignore_index=True).to_csv(
"combined.txt", sep="\t", index=False)Process combined.txt with the matching --dataset, then keep the trailing
rows.
-
Activate the environment
conda activate immuno export LD_LIBRARY_PATH=$CONDA_PREFIX/lib:$LD_LIBRARY_PATH
-
Set up Weights & Biases
Create a project on Weights & Biases matching your project name.
-
Our main experiments
These are examples for training ImmunoStruct.
# IEDB training python train_IEDB_wFT.py --model HybridModelv2 --sequence-loss --full-sequence --seed 1 --wandb-username YOUR_WANDB_USERNAME # CEDAR training python train_CEDAR_wFT.py --model HybridModel_Comparative --sequence-loss --full-sequence --comparative --seed 1 --wandb-username YOUR_WANDB_USERNAME
For running inference using the models we provide:
# IEDB inference python infer_IEDB_or_CEDAR.py --infer_dataset IEDB --model HybridModelv2 --model-path ../checkpoints/IEDB_model_seed1.pt --full-sequence --seed 1 # CEDAR inference python infer_IEDB_or_CEDAR.py --infer_dataset CEDAR --model HybridModel_Comparative --model-path ../checkpoints/CEDAR_model_seed2.pt --full-sequence --seed 2 # Clinical inference python infer_clinical_only.py --model HybridModel_Comparative --model-path ../checkpoints/CEDAR_model_seed2.pt --full-sequence
GLIBCXX Error
ImportError: $some_path/libstdc++.so.6: version 'GLIBCXX_3.4.29' not found
Solution: Add your conda environment path to LD_LIBRARY_PATH:
conda activate immuno
echo $CONDA_PREFIX
export LD_LIBRARY_PATH=$CONDA_PREFIX/lib:$LD_LIBRARY_PATHCUDA Compatibility Issues
- Ensure your CUDA version matches the PyTorch installation
- Verify GPU availability with
torch.cuda.is_available()
Memory Issues
- Reduce batch size in training scripts
- Use gradient checkpointing for large models
Wandb Authentication
- Login to Wandb:
wandb login - Ensure project names match between script and Wandb dashboard
Distributed under the Yale License. See LICENSE.txt for more information.
Krishnaswamy Lab - @KrishnaswamyLab
Project Link: https://github.com/KrishnaswamyLab/ImmunoStruct