IgFold

Official repository for IgFold: Fast, accurate antibody structure prediction from deep learning on massive set of natural antibodies.

The code and pre-trained models from this work are made available for non-commercial use (including at commercial entities) under the terms of the JHU Academic Software License Agreement. For commercial inquiries, please obtain a license through Johns Hopkins Technology Ventures.

Try antibody structure prediction in Google Colab.

Updates

 - Version 1.0.0
   - Requires PyTorch >= 2.0 and transformers >= 4.36 (5.x supported); PyTorch-Lightning is no longer a dependency
   - Model weights in safetensors format (`igfold convert-weights` converts .ckpt files); AntiBERTy weights
     are downloaded from the Hugging Face Hub on first use
   - `igfold` command-line interface; batched prediction and pooled sequence embeddings in the Python API
   - Device selection (`--device cuda:1`; "mps" supported); `IGFOLD_WEIGHTS_DIR` for external weights
   - Locked pixi environments; renumbering uses ANARCII (pip-installable, no HMMER)
   - mmCIF output (`.cif` extension); residue numbering restarts for each chain
   - Input validation (chain ids, residue alphabet, sequence length)
   - Templates are aligned to the input sequences, allowing mutations and missing residues
   - OpenMM >= 8 supported for refinement
   - Fixes to the gradient refinement (chain-boundary masks in the violation losses, coordinates now
     correspond to the final refined frames) and to backbone O placement at chain ends

Installation

IgFold is managed with pixi, which installs Python, PyTorch and the optional refinement and renumbering dependencies (OpenMM, pdbfixer, ANARCII) into a locked environment inside the repository. Install pixi, then:

git clone git@github.com:Graylab/IgFold.git
cd IgFold
pixi install -e full

Three environments are defined in pyproject.toml:

Run anything inside an environment with pixi run -e <env> <command>, or open a shell with pixi shell -e full. The -e full flag is omitted in the examples below when the default environment is enough.

Pre-trained weights

The four pre-trained model weights (igfold_*.safetensors, 25 MB in total) are not stored in this repository. They are distributed with the PyPI package; to use them with a clone, copy the igfold/trained_models/IgFold/ directory from an installed package into the clone, or point the IGFOLD_WEIGHTS_DIR environment variable at any directory containing them. Legacy .ckpt weights from IgFold <= 0.4.0 are converted automatically on first use (or explicitly with igfold convert-weights).

The AntiBERTy language-model weights (about 100 MB) are downloaded from huggingface.co/jeffruffolo/AntiBERTy on first use and cached in ~/.cache/huggingface; set ANTIBERTY_WEIGHTS_DIR to use a local copy offline.

Installing with pip

IgFold (with the pre-trained weights) is also on PyPI, for Python >= 3.11 and PyTorch >= 2.0:

pip install igfold                       # prediction only
pip install "igfold[refine,renum,viz]"   # with OpenMM refinement, ANARCII renumbering and plotting

Renumbering and truncation

Chothia renumbering (--renumber) and trimming of full-length chains to the variable domain (--truncate) use ANARCII, a pip-installable numbering tool (pixi install -e full, or pip install "igfold[renum]"). Its weights ship with the package, so no external binaries or databases are needed.

PyRosetta refinement

The manuscript refined structures with PyRosetta, which is distributed under its own license and is not installed by pixi. If PyRosetta is importable in the environment, --refine pyrosetta uses it; otherwise use --refine openmm.

Quick start

Predict a paired Fv, refine it with OpenMM, and renumber it (Chothia):

pixi run -e full igfold fold \
  -H EVQLVQSGPEVKKPGTSVKVSCKASGFTFMSSAVQWVRQARGQRLEWIGWIVIGSGNTNYAQKFQERVTITRDMSTSTAYMELSSLRSEDTAVYYCAAPYCSSISCNDGFDIWGQGTMVTVS \
  -L DVVMTQTPFSLPVSLGDQASISCRSSQSLVHSNGNTYLHWYLQKPGQSPKLLIYKVSNRFSGVPDRFSGSGSGTDFTLKISRVEAEDLGVYFCSQSTHVPYTFGGGTKLEIK \
  -o my_antibody.pdb --refine openmm --renumber

A nanobody (or a single heavy or light chain) is predicted by giving one sequence:

pixi run igfold fold \
  -H QVQLQESGGGLVQAGGSLTLSCAVSGLTFSNYAMGWFRQAPGKEREFVAAITWDGGNTYYTDSVKGRFTISRDNAKNTVFLQMNSLKPEDTAVYYCAAKLLGSSRYELALAGYDYWGQGTQVTVS \
  -o my_nanobody.cif

pixi run fold ... is a shortcut for pixi run igfold fold ....

Command-line reference

igfold fold

Predicts one structure from sequences given on the command line or in a FASTA file. Run igfold fold --help for the full option list.

Input. Give exactly one of the following. Sequences must be antibody variable domains (Fv, roughly 110-130 residues per chain) made of the 20 standard amino acids; lowercase and whitespace are accepted.

Output.

Refinement. IgFold predicts backbone and CB atoms; refinement builds and relaxes the full-atom structure while restraining the predicted backbone.

Templates. A template structure guides the prediction, for example a parent antibody when predicting a point mutant. Template chains are matched to the input by chain id (H/L, or the legacy A/B) and then aligned to the sequences, so missing residues and mutations are tolerated.

Model and hardware.

Examples:

# FASTA input, mmCIF output, single model on a specific GPU
pixi run igfold fold --fasta my_antibody.fasta -o my_antibody.cif --num-models 1 --device cuda:1

# Full-length chains: trim to the Fv, refine and renumber
pixi run -e full igfold fold --fasta full_chains.fasta -o fv.pdb --truncate --refine openmm --renumber

# Predict a mutant using the parent structure as a template, except for CDR H3
pixi run igfold fold -H <mutant heavy> -L <light> --template parent.pdb --ignore-cdrs h3 -o mutant.pdb

igfold convert-weights

Converts legacy IgFold <= 0.4.0 .ckpt weight files to safetensors, writing a .safetensors file next to each input. Without arguments it converts every .ckpt in the weights directory.

pixi run igfold convert-weights                    # all .ckpt files in the weights directory
pixi run igfold convert-weights path/to/igfold_1.ckpt

Python API

The same functionality is available from Python, including batched prediction of many antibodies, per-residue and pooled sequence embeddings, and access to the raw coordinates and predicted RMSD:

from igfold import IgFoldRunner

igfold = IgFoldRunner()
out = igfold.fold("my_antibody.pdb", sequences={"H": heavy, "L": light}, do_refine=False, do_renum=True)
out.coords  # (1, L, 5, 3) N, CA, C, CB, O
out.prmsd   # (1, L, 4) predicted RMSD for N, CA, C, CB

See docs/python_api.md for the full reference.

Development

pixi install -e dev
pixi run -e dev test      # pytest (tests needing weights are skipped if none are installed)
pixi run -e dev lint      # pre-commit: ruff lint + format, whitespace and file checks
pixi run -e dev pre-commit install

Predictions are checked against reference structures in tests/data/; CI runs the test suite on Linux and macOS.

Synthetic antibody structures

To demonstrate the capabilities of IgFold for large-scale prediction of antibody structures, we applied the model to two sets of natural paired antibody sequences.

The first set contains 104K non-redundant paired antibody sequences from the Observed Antibody Space database. These predicted structures are made available for use online.

wget https://data.graylab.jhu.edu/OAS_paired.tar.gz

The second set contains 1.3M unique paired antibodies from four human donors, collected by Jaffe et al.. These predicted structures are made available for use online.

wget https://data.graylab.jhu.edu/Jaffe2022.tar.gz

Bug reports

If you run into any problems while using IgFold, please create a Github issue with a description of the problem and the steps to reproduce it.

Citing this work

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