IgFold

Model Introduction

IgFold is an open-source antibody structure prediction model developed by the Gray Lab. It rapidly predicts three-dimensional antibody structures directly from amino acid sequences.

The model supports paired heavy/light-chain antibodies, single-chain antibodies, and nanobodies. It can also return residue-level predicted RMSD values and multiple levels of antibody sequence representations.

Paper: Fast, accurate antibody structure prediction from deep learning on massive set of natural antibodies

Model Description

IgFold uses AntiBERTy to extract antibody sequence representations and predicts antibody structures through graph Transformer layers, template feature integration, and an invariant point attention-based structure module.

The model provides the following main capabilities:

Predict paired antibody structures from heavy-chain and light-chain sequences;
Predict single-chain antibody or nanobody structures from a single heavy-chain or light-chain sequence;
Output predicted RMSD values for the N, CA, C, and CB atoms of each residue;
Output intermediate representations from AntiBERTy, the graph Transformer, and the structure module;
Support template structures;
Support structural refinement using PyRosetta or OpenMM;
Support conversion of predicted structures to Chothia numbering.

Use Cases

Use Case	Description
Paired antibody structure prediction	Generate antibody PDB structures from heavy-chain and light-chain sequences.
Single-chain antibody prediction	Predict a structure from a single heavy-chain or light-chain sequence.
Nanobody structure prediction	Generate a PDB structure from a nanobody heavy-chain sequence.
Prediction error analysis	Obtain residue-level predicted RMSD values, which are also written to the B-factor column of the output PDB file.
Antibody representation extraction	Extract AntiBERTy, graph Transformer, and structure-module embeddings.

Usage

Manual Installation

Hardware Requirements

The model can run on CPU or accelerator devices supported by PyTorch;
GPU or other compatible accelerator devices are recommended for structure prediction;
PyRosetta refinement mainly uses CPU resources, and runtime depends on sequence length and CPU performance;
The actual accelerator configuration and installation procedure depend on the locally installed PyTorch version, drivers, and runtime environment.

Download the Model Package

Install the Hugging Face command-line tool and download the model repository:

python -m pip install -U huggingface_hub

hf download OneScience-Group/IgFold --local-dir ./IgFold
cd IgFold

Install the Runtime Environment

DCU Environment

# Activate DTK and Conda first
conda create -n onescience311 python=3.11 -y
conda activate onescience311

python -m pip install "onescience[bio-dcu]" \
  -i http://mirrors.onescience.ai:3141/pypi/simple/ \
  --trusted-host mirrors.onescience.ai

GPU Environment

# Activate Conda first
conda create -n onescience311 python=3.11 -y
conda activate onescience311

python -m pip install "onescience[bio-gpu]" \
  -i http://mirrors.onescience.ai:3141/pypi/simple/ \
  --trusted-host mirrors.onescience.ai

Install the additional dependencies required by EpHod:

python -m pip install --no-deps -r requirements.txt

The weight/wheels/ directory also contains offline-installable IgFold and AntiBERTy wheel packages together with their official pretrained assets:

python -m pip install --no-deps \
  weight/wheels/antiberty-0.1.3-py3-none-any.whl \
  weight/wheels/igfold-0.4.0-py3-none-any.whl

PyTorch installation requirements vary across hardware platforms.

To use GPU or another accelerator device, install a PyTorch build compatible with the corresponding hardware platform and ensure that the remaining dependencies satisfy the versions declared in requirements.txt.

Optional Dependencies

PyRosetta Refinement

IgFold supports structural refinement using PyRosetta.

Install a PyRosetta version compatible with the current Python version and operating system according to the official PyRosetta installation instructions.

OpenMM Refinement

If PyRosetta is not used, OpenMM and PDBFixer can be installed instead:

conda install -c conda-forge openmm==7.7.0 pdbfixer

Chothia Numbering

To convert predicted structures to Chothia numbering, install AbNumber:

conda install -c bioconda abnumber

Quick Inference

The model package provides a directly executable inference entry point.

If neither sequences nor a FASTA file are specified, the script uses the paired heavy/light-chain example from the official IgFold README and writes the predicted structure to:

output/inference/antibody.pdb

Run:

python scripts/inference.py

To use a custom FASTA file:

python scripts/inference.py \
  --fasta /path/to/antibody.fasta \
  --output output/inference/my_antibody.pdb

Chain identifiers in the FASTA file should be H and L.

Example:

>sample:H
EVQLVQSGPEVKKPGTSVKVSCKAS...
>sample:L
DVVMTQTPFSLPVSLGDQASISCR...

When optional features are disabled, basic inference does not require:

SAbDab PDB data;
PyRosetta;
OpenMM;
AbNumber.

After installing the corresponding optional dependencies, structural refinement and renumbering can be enabled through options such as:

--refine
--openmm
--renum

Paired Antibody Structure Prediction

Heavy-chain and light-chain sequences are provided as a dictionary using H and L as keys:

from igfold import IgFoldRunner
from igfold.refine.pyrosetta_ref import init_pyrosetta

init_pyrosetta()

sequences = {
    "H": "EVQLVQSGPEVKKPGTSVKVSCKASGFTFMSSAVQWVRQARGQRLEWIGWIVIGSGNTNYAQKFQERVTITRDMSTSTAYMELSSLRSEDTAVYYCAAPYCSSISCNDGFDIWGQGTMVTVS",
    "L": "DVVMTQTPFSLPVSLGDQASISCRSSQSLVHSNGNTYLHWYLQKPGQSPKLLIYKVSNRFSGVPDRFSGSGSGTDFTLKISRVEAEDLGVYFCSQSTHVPYTFGGGTKLEIK",
}

pred_pdb = "my_antibody.pdb"

igfold = IgFoldRunner()

igfold.fold(
    pred_pdb,
    sequences=sequences,
    do_refine=True,
    do_renum=True,
)

After successful execution, the predicted structure is saved to:

my_antibody.pdb

Nanobody or Single-Chain Antibody Prediction

For nanobody or single-chain heavy/light-chain prediction, only one sequence is required:

from igfold import IgFoldRunner
from igfold.refine.pyrosetta_ref import init_pyrosetta

init_pyrosetta()

sequences = {
    "H": "QVQLQESGGGLVQAGGSLTLSCAVSGLTFSNYAMGWFRQAPGKEREFVAAITWDGGNTYYTDSVKGRFTISRDNAKNTVFLQMNSLKPEDTAVYYCAAKLLGSSRYELALAGYDYWGQGTQVTVS",
}

pred_pdb = "my_nanobody.pdb"

igfold = IgFoldRunner()

igfold.fold(
    pred_pdb,
    sequences=sequences,
    do_refine=True,
    do_renum=True,
)

Inference Without Structural Refinement

If PyRosetta or OpenMM refinement is not required, set:

do_refine=False

If Chothia renumbering is also unnecessary, set:

do_renum=False

Example:

from igfold import IgFoldRunner

sequences = {
    "H": "QVQLQESGGGLVQAGGSLTLSCAVSGLTFSNYAMGWFRQAPGKEREFVAAITWDGGNTYYTDSVKGRFTISRDNAKNTVFLQMNSLKPEDTAVYYCAAKLLGSSRYELALAGYDYWGQGTQVTVS",
}

pred_pdb = "my_nanobody.pdb"

igfold = IgFoldRunner()

igfold.fold(
    pred_pdb,
    sequences=sequences,
    do_refine=False,
    do_renum=False,
)

In this configuration, PyRosetta, OpenMM, and AbNumber are not required.

Predicted RMSD

IgFold predicts residue-level RMSD values and stores them in the B-factor column of the output PDB file.

The same values are also returned by fold():

from igfold import IgFoldRunner

sequences = {
    "H": "EVQLVQSGPEVKKPGTSVKVSCKASGFTFMSSAVQWVRQARGQRLEWIGWIVIGSGNTNYAQKFQERVTITRDMSTSTAYMELSSLRSEDTAVYYCAAPYCSSISCNDGFDIWGQGTMVTVS",
    "L": "DVVMTQTPFSLPVSLGDQASISCRSSQSLVHSNGNTYLHWYLQKPGQSPKLLIYKVSNRFSGVPDRFSGSGSGTDFTLKISRVEAEDLGVYFCSQSTHVPYTFGGGTKLEIK",
}

pred_pdb = "my_antibody.pdb"

igfold = IgFoldRunner()

out = igfold.fold(
    pred_pdb,
    sequences=sequences,
    do_refine=False,
    do_renum=False,
)

print(out.prmsd)
# Predicted RMSD for the N, CA, C, and CB atoms of each residue.
# Shape: [1, L, 4]

prmsd is a model-predicted error estimate.

It is not the actual RMSD obtained by aligning the predicted structure with an experimentally determined structure.

Antibody Sequence Embeddings

The embed() method provides antibody representations from multiple stages of the IgFold pipeline:

from igfold import IgFoldRunner

sequences = {
    "H": "EVQLVQSGPEVKKPGTSVKVSCKASGFTFMSSAVQWVRQARGQRLEWIGWIVIGSGNTNYAQKFQERVTITRDMSTSTAYMELSSLRSEDTAVYYCAAPYCSSISCNDGFDIWGQGTMVTVS",
    "L": "DVVMTQTPFSLPVSLGDQASISCRSSQSLVHSNGNTYLHWYLQKPGQSPKLLIYKVSNRFSGVPDRFSGSGSGTDFTLKISRVEAEDLGVYFCSQSTHVPYTFGGGTKLEIK",
}

igfold = IgFoldRunner()
emb = igfold.embed(sequences=sequences)

print(emb.bert_embs.shape)
# AntiBERTy final-layer representations: [1, L, 512]

print(emb.gt_embs.shape)
# Graph Transformer representations: [1, L, 64]

print(emb.structure_embs.shape)
# Structure-module representations: [1, L, 64]

Prefer OpenMM Refinement

After installing OpenMM and PDBFixer, OpenMM refinement can be selected by setting:

use_openmm=True

Example:

from igfold import IgFoldRunner

sequences = {
    "H": "EVQLVQSGPEVKKPGTSVKVSCKASGFTFMSSAVQWVRQARGQRLEWIGWIVIGSGNTNYAQKFQERVTITRDMSTSTAYMELSSLRSEDTAVYYCAAPYCSSISCNDGFDIWGQGTMVTVS",
    "L": "DVVMTQTPFSLPVSLGDQASISCRSSQSLVHSNGNTYLHWYLQKPGQSPKLLIYKVSNRFSGVPDRFSGSGSGTDFTLKISRVEAEDLGVYFCSQSTHVPYTFGGGTKLEIK",
}

pred_pdb = "my_antibody.pdb"

igfold = IgFoldRunner()

igfold.fold(
    pred_pdb,
    sequences=sequences,
    do_refine=True,
    use_openmm=True,
    do_renum=True,
)

Training

The official IgFold repository does not provide a complete directly executable training entry point, dataset class, or end-to-end training script.

Therefore, this Hugging Face model package does not provide a training command.

The model/training/ directory contains utility functions used for model loss computation but does not constitute a complete training program.

The official structural training data used in the IgFold paper is available from Zenodo:

https://doi.org/10.5281/zenodo.7820263

The dataset includes:

Experimentally determined SAbDab antibody structures;
Predicted structures generated from paired OAS sequences;
Predicted structures generated from unpaired OAS sequences.

These datasets are useful for reproducing the training methodology described in the paper or for structural evaluation.

They are not required for sequence-to-structure inference.

Because this model package does not provide a complete training entry point, the full SAbDab .fasta and .pdb datasets do not need to be included in the Hugging Face model repository.

To independently reproduce IgFold training, users would need to implement or reconstruct the following components using the methodology described in the paper, upstream loss functions, and official training data:

Dataset;
DataLoader;
Optimizer;
Training loop;
Validation procedure;
Checkpoint management.

Predicted Antibody Structure Datasets

The IgFold authors also released two large collections of predicted antibody structures:

104K non-redundant paired antibody structures from OAS:
https://data.graylab.jhu.edu/OAS_paired.tar.gz
1.3M predicted human paired antibody structures from the Jaffe et al. dataset:
https://data.graylab.jhu.edu/Jaffe2022.tar.gz

OneScience Official Resources

Platform	OneScience Main Repository	Skills Repository
Gitee	https://gitee.com/onescience-ai/onescience	https://gitee.com/onescience-ai/oneskills
GitHub	https://github.com/onescience-ai/OneScience	https://github.com/onescience-ai/oneskills

Citation and License

IgFold source code, pretrained models, and associated materials are distributed under the JHU Academic Software License Agreement.

The license permits use under the academic and non-commercial terms specified by Johns Hopkins University.

Commercial use may require a separate license obtained through Johns Hopkins Technology Ventures.

This Hugging Face model package does not modify or extend the original licensing terms of IgFold, AntiBERTy, PyRosetta, SAbDab, OAS, pretrained models, datasets, or other third-party resources.

@article{ruffolo2023fast,
  title={Fast, accurate antibody structure prediction from deep learning on massive set of natural antibodies},
  author={Ruffolo, Jeffrey A and Chu, Lee-Shin and Mahajan, Sai Pooja and Gray, Jeffrey J},
  journal={Nature Communications},
  volume={14},
  number={1},
  pages={2389},
  year={2023},
  publisher={Nature Publishing Group UK London}
}

@article{ruffolo2021deciphering,
  title={Deciphering antibody affinity maturation with language models and weakly supervised learning},
  author={Ruffolo, Jeffrey A and Gray, Jeffrey J and Sulam, Jeremias},
  journal={arXiv},
  year={2021}
}

Downloads last month: -; Downloads are not tracked for this model. How to track

Inference Providers NEW

This model isn't deployed by any Inference Provider. 🙋 Ask for provider support