ImmunoStruct

<a id="readme-top"></a>

<!-- PROJECT LOGO --> <div align="center"> <h1><img src="assets/ImmunoStruct_cover.png" width="200"><br><code>ImmunoStruct</code></h1> <h3>ImmunoStruct enables multimodal deep learning for immunogenicity prediction</h3>

<br> <br>

</div>

Project leads: Kevin Bijan Givechian, João Felipe Rocha, Chen Liu. <br>Correspondence: akiko.iwasaki@yale.edu, smita.krishnaswamy@yale.edu.

<br>In case you don't have access to Nature, here are the main paper and the supplementary materials.

<!-- TABLE OF CONTENTS --> <details> <summary>Table of Contents</summary> <ol> <li><a href="#news">News</a></li> <li><a href="#about-the-project">About The Project</a></li> <li><a href="#citation">Citation</a></li> <li><a href="#getting-started">Getting Started</a></li> <li><a href="#usage">Usage</a></li> <li><a href="#troubleshooting">Troubleshooting</a></li> <li><a href="#license">License</a></li> <li><a href="#contact">Contact</a></li> </ol> </details>

News

News in English<br> <br>

News in Chinese<br> <br> <br>

☐ TODO: create and release an end-to-end tool. <br>✅ Feb 20, 2026: The multimodal datasets and model weights are now open-sourced. See instructions. <br>✅ Dec 31, 2025: Published in Nature Machine Intelligence. <br>✅ Dec 04, 2025: Informally presented at NeurIPS 2025 (did not submit, no dual-submission concern). <br>✅ Aug 18, 2025: Received the Colton Innovation Fund from Colton Center for Autoimmunity at Yale University. <br>✅ May 06, 2025: Submitted to Nature Machine Intelligence. <br>✅ Nov 05, 2024: Presented at MoML@MIT 2024 (non-archival abstract & poster). <br>✅ Nov 01, 2024: Preprint released.

<!-- ABOUT THE PROJECT -->

About The Project

<div align="center"> <img src="assets/schematic.png" alt="ImmunoStruct Architecture" width="800"> </div>

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.

<p align="right">(<a href="#readme-top">back to top</a>)</p>

Key Features

• 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

<div align="center"> <img src="assets/contrastive_learning.png" alt="Contrastive Learning Approach" width="800"> <img src="assets/visualizations.png" alt="Visualizations" width="800"> </div> <p align="right">(<a href="#readme-top">back to top</a>)</p> <!-- CITATION -->

Citation

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:<br> 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

<p align="right">(<a href="#readme-top">back to top</a>)</p> <!-- GETTING STARTED -->

Getting Started

To get ImmunoStruct up and running locally, follow these steps.

Pre-requisites

Before installation, ensure you have:

• CUDA-compatible GPU (recommended)
• Conda package manager
• Weights & Biases account for experiment tracking

Installation

1. Clone the repository

   git clone https://github.com/KrishnaswamyLab/ImmunoStruct.git
   cd ImmunoStruct
   

2. 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+cu1