OneScience-Group/flex_ddG_tutorial

Flex ddG

Model Introduction

Flex ddG is a Rosetta-based workflow for predicting the effects of mutations at protein-protein interfaces and estimating changes in binding free energy before and after mutation (interface ΔΔG). It uses the Rosetta Backrub protocol to sample local backbone conformations, then performs side-chain repacking, structural minimization, and interface energy calculations for the wild type and mutant to assess how mutations affect protein binding affinity.

Paper:

Flex ddG: Rosetta Ensemble-Based Estimation of Changes in Protein–Protein Binding Affinity upon Mutation
https://doi.org/10.1021/acs.jpcb.7b11367

Model Description

Flex ddG is not a model that relies on neural network weights; it is a computational workflow based on the Rosetta energy function and conformational sampling. Inputs typically include a protein complex PDB file, interface chain information, and a Rosetta resfile describing the mutations. The workflow uses Backrub sampling to generate an ensemble of conformations, optimizes and calculates interface energies for the wild type and mutant separately, and ultimately produces ΔΔG.

Use Cases

Use case	Description
Protein-protein interface mutation effect prediction	Predict changes in binding free energy ΔΔG caused by mutations
Interface hotspot residue analysis	Evaluate the effects of mutations at specific sites on binding stability
Single-site saturation mutagenesis scan	Generate all 20 standard amino acid substitutions at a target site and calculate ΔΔG for each
Protein engineering and interface optimization	Help screen for mutations that may enhance or weaken protein interactions

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

• The core computations in Flex ddG are performed by Rosetta CPU programs; the standard workflow does not require a GPU/DCU.
• The official Python scripts use multiprocessing to launch multiple Rosetta instances concurrently. Each Rosetta instance requires approximately 2 GB of memory, so set the concurrency level according to the number of CPU cores and the node's available memory.

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

• The core dependency of Flex ddG is Rosetta. The main workflow requires the rosetta_scripts executable built by Rosetta.

Install Rosetta

Flex ddG does not require neural network model weights or additional large datasets, but Rosetta must be installed separately.

1) Install Rosetta

Rosetta must be licensed, downloaded, and installed separately according to the official RosettaCommons instructions:

https://www.rosettacommons.org/software

The Rosetta license is independent of the MIT License for the Flex ddG tutorial repository. Academic and non-commercial users can apply for a non-commercial license; commercial use requires a separate license.

After installation, make sure that at least the following files exist:

/path/to/rosetta/source/bin/rosetta_scripts
/path/to/rosetta/source/bin/score_jd2

2) Configure the Rosetta Paths

Before running the workflow, update the following line in scripts/run_example_1.py and scripts/run_example_2_saturation.py:

rosetta_scripts_path = os.path.expanduser("~/rosetta/source/bin/rosetta_scripts")

To run scripts/extract_structures.py, also update score_jd2_path in the script to the actual path of the Rosetta score_jd2 executable.

3. Quick Start

Download the Model Package

hf download OneScience-Group/flex_ddG --local-dir ./flex_ddG
cd flex_ddG

• Flex ddG additionally depends on Rosetta. Rosetta is not included in this model repository; first apply for a license and install Rosetta as described in "Install Rosetta", then configure rosetta_scripts_path.
• To extract PDB structures from struct.db3, you also need to configure the path to Rosetta's score_jd2 executable.
• The default parameters in this document are intended only for quick functional verification and do not represent parameters for production scientific calculations.

Quick Verification

First, verify that the Rosetta executable is available:

/path/to/rosetta/source/bin/rosetta_scripts -help

Run the official example:

python scripts/run_example_1.py

On success, the following directory will be generated:

output/

Example Data

The official example directory is:

scripts/inputs/
└── 1JTG/
    ├── 1JTG_AB.pdb
    ├── chains_to_move.txt
    ├── nataa_mutations.resfile
    ├── mutations.resfile
    ├── mutations.mutfile
    ├── pdb2rosetta.resmap.json
    └── rosetta2pdb.resmap.json

The files are:

File	Description
1JTG_AB.pdb	Protein complex structure
chains_to_move.txt	Defines the chain that moves as one side of the interface during calculations
nataa_mutations.resfile	The mutation resfile used by Flex ddG
mutations.resfile	Example mutation configuration
mutations.mutfile	Example mutation information

The resfile used by Flex ddG must begin with NATAA. The official scripts explicitly state that it should not be replaced with NATRO, as this changes the repacking behavior of residues near the mutant and introduces bias into ΔΔG.

For your own tasks, you typically need at least:

Complex PDB
+ Interface chain information
+ A resfile describing the mutations

Inference Examples

Flex ddG Calculation for Specified Mutations

Make sure that the Rosetta path in scripts/run_example_1.py is configured correctly:

rosetta_scripts_path = "/path/to/rosetta/source/bin/rosetta_scripts"

Run:

python scripts/run_example_1.py

The script reads the complex structure, chains_to_move.txt, and nataa_mutations.resfile from scripts/inputs/, then calls conf/ddG-backrub.xml to run Flex ddG.

Key parameters:

Parameter	Default	Common production setting/meaning
nstruct	3	Typically about 35 or more independent replicates in production
number_backrub_trials	10	35000 is commonly used in the official benchmark
max_minimization_iter	5	Standard value: 5000
abs_score_convergence_thresh	200.0	Standard value: 1.0
backrub_trajectory_stride	5	Controls the interval between Backrub trajectory checkpoints

The small parameter values in this document are intended to shorten runtime and should not be used directly for production ΔΔG calculations.

Single-Site Saturation Mutagenesis

Run:

python scripts/run_example_2_saturation.py

The script sequentially generates a resfile for each of the 20 standard amino acid substitutions at the specified residue and runs Flex ddG.

Configure the target site in the script:

residue_to_mutate = ('B', 49, '')

The format is:

(chain ID, PDB residue number, insertion code)

Results are saved in:

output_saturation/

Parallel Execution Recommendations

The official scripts use the following defaults:

use_multiprocessing = True
max_cpus = 2

During actual execution, adjust max_cpus according to the allocated number of CPU cores and the node's available memory. Each Rosetta instance uses CPU and memory independently, so setting it to all available cores unconditionally is not recommended.

Result Analysis

After Example 1 is complete:

python scripts/analyze_flex_ddG.py output

For saturation mutagenesis results:

python scripts/analyze_flex_ddG.py output_saturation

The analysis script outputs:

wt_dG
mut_dG
ΔΔG

The results are written to:

analysis_output/

the CSV files in this directory. It also provides reweighted mutant ΔΔG values using the GAM model fitted in the original Flex ddG paper.

To extract structures after Backrub, wild-type minimization, or mutant minimization:

python scripts/extract_structures.py output

The script looks for struct.db3 and calls Rosetta score_jd2 to export PDB files.

Output Description

After running scripts/run_example_1.py, the main results are located at:

output/
└── <case>/
    └── <replicate>/
        ├── rosetta.out
        ├── ddG.db3
        └── struct.db3

The files are:

File	Description
rosetta.out	Rosetta run log
ddG.db3	Database of Flex ddG energy and trajectory results
struct.db3	Database of structures generated by Rosetta
analysis_output/*.csv	Summary of ΔΔG results generated by scripts/analyze_flex_ddG.py

The analysis script reads the Backrub trajectory stride from the ddG.db3 generated by each run, so you usually do not need to modify the analysis script manually. If the database does not contain a stride, use:

python scripts/analyze_flex_ddG.py output --stride N

to override it.

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 Flex ddG paper: Flex ddG: Rosetta Ensemble-Based Estimation of Changes in Protein–Protein Binding Affinity upon Mutation.
• Flex ddG uses the Rosetta Backrub conformational sampling method. Related paper: Backrub-Like Backbone Simulation Recapitulates Natural Protein Conformational Variability and Improves Mutant Side-Chain Prediction.
• The official flex_ddG_tutorial source code is released under the MIT License; see LICENSE in the repository root.
• Rosetta is not covered by the MIT License of the Flex ddG tutorial repository. Rosetta is distributed under a separate software license; academic and non-commercial users can apply for a non-commercial license, while commercial use requires a separate commercial license.
• For research use, we recommend citing the relevant Flex ddG, Backrub, and Rosetta publications, and adding citations as required by the relevant OneScience project.