README.md

---
frameworks:
- PyTorch
language:
- en
license: other
tags:
- OneScience
- bioscience
- antibody-structure-prediction
- protein-structure-prediction
- IgFold
- AntiBERTy
tasks: []
---

<p align="center">
  <strong>
    <span style="font-size: 30px;">IgFold</span>
  </strong>
</p>

# 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](https://www.nature.com/articles/s41467-023-38063-x)

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

```bash
python -m pip install -U huggingface_hub

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



### Install the Runtime Environment

**DCU Environment**

```bash
# 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**

```bash
# 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:

```bash
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:

```bash
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](https://www.pyrosetta.org/downloads).

#### OpenMM Refinement

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

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

#### Chothia Numbering

To convert predicted structures to Chothia numbering, install AbNumber:

```bash
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:

```text
output/inference/antibody.pdb
```

Run:

```bash
python scripts/inference.py
```

To use a custom FASTA file:

```bash
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:

```text
>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:

```text
--refine
--openmm
--renum
```

### Paired Antibody Structure Prediction

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

```python
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:

```text
my_antibody.pdb
```

### Nanobody or Single-Chain Antibody Prediction

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

```python
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:

```python
do_refine=False
```

If Chothia renumbering is also unnecessary, set:

```python
do_renum=False
```

Example:

```python
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()`:

```python
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:

```python
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:

```python
use_openmm=True
```

Example:

```python
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](https://github.com/Graylab/IgFold/blob/main/LICENSE.md).

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.

```bibtex
@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}
}
```