README.md

metadata

license: mit
language:
  - en
  - zh
tags:
  - OneScience
  - life-science
  - protein
  - antibody
  - mutation
  - inverse-folding
  - structural-evolution
frameworks: PyTorch

Structural Evolution

Model Introduction

Structural Evolution is an unsupervised protein and antibody mutation recommendation workflow based on a structure-informed protein language model. It takes a PDB/CIF structure of a protein or protein complex as input, scores candidate mutation sequences under structural conditions with ESM-IF1, and selects high-probability substitutions from deep mutational scanning candidates to assist protein and antibody sequence optimization.

Paper:

Unsupervised evolution of protein and antibody complexes with a structure-informed language model
https://doi.org/10.1126/science.adk8946

Model Description

Structural Evolution uses the structure-conditioned language model ESM-IF1 to recommend mutations for a target chain in a given protein structure. The program first extracts the target chain's wild-type sequence from the input PDB/CIF and generates single-point deep mutational scanning candidates. It then calculates the log-likelihood of each candidate under a single-chain or multichain backbone condition and selects recommended mutations in descending score order.

Use Cases

Use case	Description
Single-point protein mutation recommendation	Select high-probability amino acid substitutions from structure information
Antibody sequence optimization	Recommend structure-conditioned mutations for antibody heavy and light chains separately
Protein complex optimization	Evaluate target-chain mutations in a multichain backbone context
Deep mutational scanning candidate screening	Score all single-point mutations and output high-scoring candidates

Usage

1. Using OneCode

Experience intelligent one-click AI4S programming in the OneCode online environment:

Try intelligent one-click AI4S programming

2. Manual Installation and Usage

Hardware Requirements

• Structural Evolution supports inference on CPUs and GPUs.
• A GPU/DCU is recommended for ESM-IF1 inference to accelerate candidate sequence scoring.
• Larger protein complexes or larger mutation candidate libraries require more GPU/DCU memory and host memory.
• If no GPU/DCU is available, you can explicitly use the CPU with --nogpu, but execution will be significantly slower.

Set Up the Runtime Environment

DCU Environment

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

# Install with uv support
pip install onescience[bio] \
  -i http://mirrors.onescience.ai:3141/pypi/simple/ \
  --trusted-host mirrors.onescience.ai

Environment Notes

• If you encounter missing dependencies or version incompatibilities during execution, refer to the dependency versions specified in environment.yml and install or adjust the relevant dependencies as needed.

Prepare the Weights

Complete Structural Evolution inference only requires the additional ESM-IF1 model weights. Standard mutation recommendation does not require downloading any additional training dataset from the paper.

1) ESM-IF1 Model Weights

Download the ESM-IF1 weights:

https://zenodo.org/records/12631662

Command:

wget -P ~/.cache/torch/hub/checkpoints \
  https://zenodo.org/records/12631662/files/esm_if1_20220410.zip

unzip ~/.cache/torch/hub/checkpoints/esm_if1_20220410.zip \
  -d ~/.cache/torch/hub/checkpoints/

After extraction, make sure that the following file exists:

~/.cache/torch/hub/checkpoints/
└── esm_if1_20220410.pt

The file must exist.

scripts/recommend.py always loads the model from:

~/.cache/torch/hub/checkpoints/esm_if1_20220410.pt

loads the model from this path. If you save the weights elsewhere, update the checkpoint path in the code.

3. Quick Start

Download the Model Package

hf download OneScience-Group/structural-evolution \
  --local-dir ./structural-evolution

cd structural-evolution

• Structural Evolution additionally depends on the ESM-IF1 model weights. Prepare esm_if1_20220410.pt as described in "Prepare the Weights" and make sure that the checkpoint path in the code matches its actual location.

Quick Verification

View the inference options:

python scripts/recommend.py --help

Run a quick verification with the official example structure:

python scripts/recommend.py \
  scripts/examples/7mmo_abc_fvar.pdb \
  --chain A \
  --n 10

Example Data

The official repository provides an example structure in:

scripts/examples/

The directory contains:

scripts/examples/
└── 7mmo_abc_fvar.pdb

This structure contains the LYCoV-1404 antibody variable region and SARS-CoV-2 RBD, and demonstrates mutation recommendation for an antibody heavy chain.

For your own tasks, prepare:

PDB or CIF structure of a protein or protein complex
+
Target chain ID

For example:

structure.pdb
chain A

Inference Examples

Basic Mutation Recommendation

The simplest way to run it is:

python scripts/recommend.py \
  /path/to/structure.pdb \
  --chain A

Default output:

Top 10 mutations
maxrep = 1
multichain backbone = True

This recommends 10 mutations by default and allows each original residue position to appear at most once.

Antibody Example

Official example:

python scripts/recommend.py \
  scripts/examples/7mmo_abc_fvar.pdb \
  --chain A \
  --seqpath scripts/examples/7mmo_chainA_lib.fasta \
  --outpath scripts/examples/7mmo_chainA_scores.csv \
  --upperbound 109 \
  --offset 1

Where:

Parameter	Description
--chain	Target chain ID
--seqpath	Output path for the generated deep mutational scanning FASTA
--outpath	Output path for the CSV containing scores for all mutation candidates
--n	Number of mutations to recommend; default: 10
--maxrep	Maximum number of times the same position may appear in the recommendations; default: 1
--upperbound	During final recommendation, consider only positions below this residue number
--offset	Offset correction for PDB residue numbering
--order	Specify chain order in a multichain structure
--multichain-backbone	Use all chains as the structural context
--singlechain-backbone	Use only the target chain backbone
--nogpu	Force CPU execution

In the antibody example above, --chain A specifies the heavy chain. --upperbound 109 excludes mutations in the final framework region. Because the input structure lacks the first residue, --offset 1 corrects the mutation numbering.

Customize the Number of Recommendations

For example, output the top 20 candidates and allow the same position to appear at most twice:

python scripts/recommend.py \
  /path/to/your_structure.pdb \
  --chain A \
  --n 20 \
  --maxrep 2

Single-Chain Backbone Condition

To use only the backbone information of the target chain:

python scripts/recommend.py \
  /path/to/your_structure.pdb \
  --chain A \
  --singlechain-backbone

CPU Inference

python scripts/recommend.py \
  /path/to/your_structure.pdb \
  --chain A \
  --nogpu

Output Description

Structural Evolution first generates a complete single-point deep mutational scanning sequence library for the target chain in the input structure, then uses ESM-IF1 to calculate the structure-conditioned log-likelihood of each candidate sequence.

If the following options are not specified manually:

--seqpath
--outpath

the program automatically saves the results under output/.

The main outputs include:

*.fasta
*.csv

The files are:

Output	Description
DMS FASTA	Contains the wild-type sequence and all single-point mutation candidates
scores CSV	Stores candidate sequences and their corresponding log_likelihood scores
Terminal output	Top-N recommended mutations sorted by log_likelihood

Candidate sequences in the CSV are sorted by:

log_likelihood

in descending order, and recommended mutations are finally selected using parameters such as n, maxrep, and upperbound.

Official OneScience Information

Platform	Main OneScience 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

• Original Structural Evolution paper: Unsupervised evolution of protein and antibody complexes with a structure-informed language model.
• Structural Evolution is released under the MIT License, which permits use, copying, modification, publication, distribution, sublicensing, and commercial use provided that the copyright notice and license text are retained. See LICENSE in the repository root.
• Structural Evolution inference depends on ESM-IF1 and related ESM code. The MIT License of the Structural Evolution repository does not automatically cover third-party model weights or dependency resources. For commercial use, redistribution, or other purposes, also review the applicable ESM/ESM-IF1 licenses and model-weight terms of use.
• If you use this repository in research, cite the original Structural Evolution paper and, as appropriate, the related work on ESM-IF1 and other components actually used.