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](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/ └──