README.md

---
license: mit
language:
- en
- zh
tags:
- OneScience
- life-science
- protein
- binding-affinity
- mutation
- Rosetta
frameworks: Other
---

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

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

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

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

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

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

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

```python
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

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

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

Run the official example:

```bash
python scripts/run_example_1.py
```

On success, the following directory will be generated:

```text
output/
```

# Example Data

The official example directory is:

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

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

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

Run:

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

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

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

The format is:

```text
(chain ID, PDB residue number, insertion code)
```

Results are saved in:

```text
output_saturation/
```

## Parallel Execution Recommendations

The official scripts use the following defaults:

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

```bash
python scripts/analyze_flex_ddG.py output
```

For saturation mutagenesis results:

```bash
python scripts/analyze_flex_ddG.py output_saturation
```

The analysis script outputs:

```text
wt_dG
mut_dG
ΔΔG
```

The results are written to:

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

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

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

```bash
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](https://doi.org/10.1021/acs.jpcb.7b11367).
- 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](https://doi.org/10.1016/j.jmb.2008.05.023).
- 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.