Upload folder using huggingface_hub

6f1e670 verified about 18 hours ago

14.7 kB

license: apache-2.0
language:
  - en
  - zh
tags:
  - OneScience
  - life-science
  - protein
  - directed-evolution
  - multi-mutant
  - protein-language-model
  - MULTI-evolve
frameworks: PyTorch

MULTI-evolve

Model Introduction

MULTI-evolve (model-guided, universal, targeted installation of multi-mutants) is an end-to-end framework for protein directed evolution. It trains sequence-to-fitness prediction models, proposes combinatorial multi-mutants, generates MULTI-assembly site-directed mutagenesis oligonucleotides, and supports screening single-mutant candidates through a protein language model zero-shot ensemble method.

Paper:

Rapid directed evolution guided by protein language models and epistatic interactions
Science, 2026
https://doi.org/10.1126/science.aea1820

Model Description

The core workflow of MULTI-evolve includes:

Train fully connected neural networks using experimental sequence-to-fitness data.
Compare different data splits, sequence representations, and machine learning models.
Select the best-performing prediction model to score combinatorial mutants and propose candidates.
Generate MULTI-assembly site-directed mutagenesis oligonucleotides from the selected multi-mutants.
In selected iterations, use a protein language model zero-shot ensemble method to screen single-mutant candidates.

Use Cases

Use case	Description
Protein directed evolution	Train fitness prediction models from experimental data and screen candidate mutations
Multi-mutant design	Predict combinatorial mutations and screen multi-mutants with high predicted fitness
Protein complex optimization	Support mutation formats and inputs for multichain proteins
Zero-shot mutation screening	Use a protein language model ensemble method to screen candidate single mutations

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

Supervised model training and standard combinatorial mutation prediction in MULTI-evolve can run on a CPU or GPU/DCU.
Protein language model zero-shot prediction uses models such as ESM and ESM-IF; a GPU/DCU is recommended.

Set Up the Runtime Environment

DCU Environment

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

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 env.yml and install or adjust the relevant dependencies as needed.

Prepare Models and Data

The different MULTI-evolve functions have different model and data requirements. Prepare the resources for standard supervised training, combinatorial multi-mutant recommendation, MULTI-assembly design, protein language model zero-shot screening, and benchmark reproduction separately.

1) Supervised Learning Input Data

To train your own protein fitness prediction model with MULTI-evolve, prepare:

Wild-type protein FASTA
+
Experimental training data CSV

The training data CSV must contain at least:

mutation
property_value

For example, the mutation format for a single-chain protein is:

A40P/E61Y

For multichain proteins, use : to separate different chains:

A40P/E61Y:WT

Where:

/   Separates multiple mutations on the same chain
:   Separates different protein chains
WT  Indicates that the corresponding chain remains wild type

The official repository provides example data:

data/
├── example_protein/
└── example_multichain_protein/

Therefore, no additional training data download is required to run the official basic examples.

2) Combinatorial Mutation Candidate Pool

When running combinatorial multi-mutant recommendation, in addition to the wild-type FASTA and training data, provide a mutation pool: a list of candidate single mutations eligible for combinatorial design.

Example:

data/example_protein/combo_muts.csv

Pass this file as the:

--mutation-pool

parameter, for example:

p2_propose.py \
  --experiment-name multievolve_example \
  --protein-name example_protein \
  --wt-files apex.fasta \
  --training-dataset example_dataset.csv \
  --mutation-pool combo_muts.csv \
  --top-muts-per-load 3 \
  --export-name multievolve_proposals

3) Protein Language Model Zero-Shot Mode

The MULTI-evolve protein language model zero-shot ensemble workflow requires:

Wild-type FASTA
+
PDB/CIF protein structure

The current official code uses the following models:

ESM-1v:
esm1v_t33_650M_UR90S_1
esm1v_t33_650M_UR90S_2
esm1v_t33_650M_UR90S_3
esm1v_t33_650M_UR90S_4
esm1v_t33_650M_UR90S_5

ESM-2:
esm2_t36_3B_UR50D

ESM-IF1:
esm_if1_gvp4_t16_142M_UR50

MULTI-evolve calls these models through fair-esm. On the first run, if the corresponding weights are not available locally, fair-esm automatically downloads the models and caches them in the PyTorch Hub checkpoint directory.

The default cache location is:

~/.cache/torch/hub/checkpoints/

ESM-2 also uses the corresponding contact regression weights:

esm2_t36_3B_UR50D-contact-regression.pt

The current repository already includes esm2_t36_3B_UR50D-contact-regression.pt under hub/checkpoints/.

For network-restricted or offline environments, download the weights in advance:

mkdir -p ~/.cache/torch/hub/checkpoints
cd ~/.cache/torch/hub/checkpoints

wget https://dl.fbaipublicfiles.com/fair-esm/models/esm1v_t33_650M_UR90S_1.pt
wget https://dl.fbaipublicfiles.com/fair-esm/models/esm1v_t33_650M_UR90S_2.pt
wget https://dl.fbaipublicfiles.com/fair-esm/models/esm1v_t33_650M_UR90S_3.pt
wget https://dl.fbaipublicfiles.com/fair-esm/models/esm1v_t33_650M_UR90S_4.pt
wget https://dl.fbaipublicfiles.com/fair-esm/models/esm1v_t33_650M_UR90S_5.pt

wget https://dl.fbaipublicfiles.com/fair-esm/models/esm2_t36_3B_UR50D.pt
wget https://dl.fbaipublicfiles.com/fair-esm/regression/esm2_t36_3B_UR50D-contact-regression.pt

wget https://dl.fbaipublicfiles.com/fair-esm/models/esm_if1_gvp4_t16_142M_UR50.pt

To save the models in the current project or another location, set the PyTorch Hub cache root with TORCH_HOME. For example, to use a directory in the current project:

cd /path/to/MULTI-evolve
export TORCH_HOME=$PWD
mkdir -p ${TORCH_HOME}/hub/checkpoints

Then save or symlink the weights above to:

/path/to/MULTI-evolve/hub/checkpoints/

This avoids modifying the MULTI-evolve source code.

4) Benchmark DMS Data

To run the official benchmark and reproduce the performance comparison across different:

data splitting methods
sequence representation methods
machine learning models

you must additionally prepare the official benchmark DMS data by downloading it separately from Zenodo.

Download:

DOI: 10.5281/zenodo.17620759
https://zenodo.org/records/17620759

After downloading, place the DMS CSV files directly in the following directory. If the directory does not exist, create it manually first:

data/benchmark/datasets/

The benchmark script entry point in the current repository is:

scripts/notebooks/benchmark/multievolve_hyperparameter_tuning.py

3. Quick Start

Download the Model Package

hf download OneScience-Group/MULTI-evolve \
  --local-dir ./MULTI-evolve

cd MULTI-evolve

Standard supervised training and combinatorial mutation recommendation in MULTI-evolve do not require additional large fixed datasets; you can use the example data in the repository or your own experimental data.
The protein language model zero-shot mode may require additional ESM/ESM-IF model caches; prepare them in advance in offline environments.

Quick Verification

Install the current repository:

python -m pip install -e . --no-deps

Check the commands:

p1_train.py --help
p2_propose.py --help
p3_assembly_design.py --help
plm_zeroshot_ensemble.py --help

Example Data

The official repository provides:

data/
├── example_protein/
├── example_multichain_protein/
└── benchmark/

The official command-line examples primarily use:

cd data/example_protein

Typical inputs include:

apex.fasta
example_dataset.csv
combo_muts.csv
APEX_33overhang.fasta
apex.cif

These files are used for:

File	Purpose
`apex.fasta`	Wild-type protein amino acid sequence
`example_dataset.csv`	Training data
`combo_muts.csv`	Combinatorial mutation candidate pool
`APEX_33overhang.fasta`	DNA input required for MULTI-assembly oligonucleotide design
`apex.cif`	Structure-conditioned scoring for protein language models

Inference and Training Examples

Step 1: Train the Neural Network Model

# If the runtime environment is not active, activate the conda environment in use, such as onescience311
conda activate onescience311
cd data/example_protein

p1_train.py \
  --experiment-name multievolve_example \
  --protein-name example_protein \
  --wt-files apex.fasta \
  --training-dataset-fname example_dataset.csv \
  --wandb-key dummy \
  --mode test

Key parameters:

Parameter	Description
`--experiment-name`	Current experiment name; keep it consistent in subsequent steps
`--protein-name`	Protein name
`--wt-files`	Wild-type FASTA; use commas to separate multiple FASTA files for multichain proteins
`--training-dataset-fname`	Training data CSV
`--mode`	`test` or `standard`

Step 2: Propose Combinatorial Multi-Mutants

p2_propose.py \
  --experiment-name multievolve_example \
  --protein-name example_protein \
  --wt-files apex.fasta \
  --training-dataset example_dataset.csv \
  --mutation-pool combo_muts.csv \
  --top-muts-per-load 3 \
  --export-name multievolve_proposals

The script loads the trained model saved to the local cache in Step 1 and scores the combinatorial mutation candidates.

Typical output:

multievolve_proposals.csv

For protein complexes, candidate files are also generated separately for each chain.

Step 3: Design MULTI-assembly Oligonucleotides

p3_assembly_design.py \
  --mutations-file multievolve_proposals.csv \
  --wt-fasta APEX_33overhang.fasta \
  --overhang 33 \
  --species human \
  --oligo-direction top \
  --tm 80 \
  --output design

Where:

Parameter	Description
`--mutations-file`	Candidate mutation CSV generated in Step 2
`--wt-fasta`	Wild-type DNA FASTA containing overhangs at both ends
`--overhang`	Overhang length
`--species`	`human`, `ecoli`, or `yeast`
`--oligo-direction`	`top` or `bottom`
`--tm`	Target oligonucleotide melting temperature; the official recommendation is 80 °C
`--output`	`design` or `update`

Outputs:

cloning_sheet.csv
oligos.csv

Protein Language Model Zero-Shot Ensemble

plm_zeroshot_ensemble.py \
  --wt-file apex.fasta \
  --pdb-files apex.cif \
  --chain-id A \
  --variants 24 \
  --excluded-positions 1,14,41,112 \
  --normalizing-method aa_substitution_type

Where:

Parameter	Description
`--wt-file`	Wild-type protein FASTA
`--pdb-files`	PDB/CIF structure files; use commas to separate multiple structures
`--chain-id`	Chain ID of the target protein in the structure file
`--variants`	Number of mutations nominated by each method
`--excluded-positions`	Positions excluded from mutation
`--normalizing-method`	`aa_substitution_type` or `aa_mutation`

This workflow ensembles four methods and produces:

plm_zeroshot_ensemble_nominated_mutations.csv

Output Description

MULTI-evolve generates model caches, evaluation results, and candidate sequences at different stages.

The official repository automatically creates the following after execution:

proteins/
└── <protein_name>/
    ├── feature_cache/
    ├── model_cache/
    │   └── <dataset>/
    │       ├── objects/
    │       └── results/
    ├── proposers/
    │   └── results/
    └── split_cache/
        └── <dataset>/

The main outputs include:

Output	Description
`model_cache/`	Trained models and comparison results
`feature_cache/`	Cached sequence representations
`multievolve_proposals.csv`	Recommended multi-mutant candidates
`cloning_sheet.csv`	MULTI-assembly cloning design sheet
`oligos.csv`	Site-directed mutagenesis oligonucleotide sequences
`plm_zeroshot_ensemble_nominated_mutations.csv`	Protein language model zero-shot ensemble recommendations

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 MULTI-evolve paper: Rapid directed evolution guided by protein language models and epistatic interactions.
The LICENSE in the repository root is currently Apache License 2.0. This license permits use, modification, distribution, and commercial use, but redistribution requires retaining the license, copyright, and attribution notices, and clearly indicating modified files.
Apache-2.0 also includes a patent license and explicitly does not grant rights to use the project's trademarks.
setup.py still contains an MIT License classifier, which is inconsistent with the actual LICENSE file in the repository root. For SCNet/ModelScope redistribution, use the Apache-2.0 LICENSE in the repository root as the authoritative license, and retain the original license file.
This repository is a DCU-adapted version of MULTI-evolve, with some environment configurations, dependencies, and execution procedures adjusted. Use of the repository code, model weights, and related data remains subject to the licenses and terms of use of their respective original projects.