README.md

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

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

# 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](https://web-2069360198568017922-iaaj.ksai.scnet.cn:58043/home)

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

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

```text
https://zenodo.org/records/12631662
```

Command:

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

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

The file must exist.

`scripts/recommend.py` always loads the model from:

```text
~/.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

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

```bash
python scripts/recommend.py --help
```

Run a quick verification with the official example structure:

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

# Example Data

The official repository provides an example structure in:

```text
scripts/examples/
```

The directory contains:

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

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

For example:

```text
structure.pdb
chain A
```

# Inference Examples

## Basic Mutation Recommendation

The simplest way to run it is:

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

Default output:

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

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

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

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

## CPU Inference

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

```text
--seqpath
--outpath
```

the program automatically saves the results under `output/`.

The main outputs include:

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

```text
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](https://doi.org/10.1126/science.adk8946).
- 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.