The DDG API runs the Rosetta Cartesian DDG protocol. The cartesian DDG protocol is described in Prediction of Protein Mutational Free Energy: Benchmark and Sampling Improvements Increase Classification Accuracy.
The purpose of the Cartesian DDG protocol is to predict the impact of a single point mutation on the free energy of a protein.
The Cartesian DDG protocol only supports canonical amino acids and does not support structures containing any kind of small molecule (waters, drug-like ligands, metal ions, etc). The Clean PDB endpoint should be used to prepare any PDB files produced by non-Cyrus tools.
The DDG process consists of two steps. The first step is to relax the PDB using the ddg-relax API. This step must be performed only once for each structure prior to running mutagenesis experiments with the ddg API. If multiple rounds of mutagenesis experiments are to be performed on a single protein, the same relaxed model should be used as the input for each relaxed protein.
Inputs (DDG Relax)
pdb-file
A PDB file
Command Line Examples (DDG Relax)
Prepare an input PDB file for use with DDG.
Note that the ddg-relax API performs a different type of minimization than the relax API. The ddg-relax API must be used to prepare models for use with the ddg API.
cyrus submit ddg-relax <pdb-file>
Python Examples (DDG Relax)
Prepare an input pdb file for use with DDG
from engine.ddg-relax.client import DdgRelaxClient client = DdgRelaxClient() job_id = client.submit(pdb_path="input.pdb")
Inputs (DGG)
pdb-file
must be a PDB which has been run through the ddg-relax endpoint described above
Optional - mutations-file
Tab Separated Value (TSV)-formatted file containing mutations. To create an empty mutations file from an input PDB, run:
cyrus prepare mutations <pdb-file> --output-dir <output-dir>Each row can contain one or many mutations, in the format
DorDMG. For example, The TSV file below would allow residue 1 to mutate to Aspartic Acid, Glycine, or remain un-mutated as Methionine, and would not allow any mutations for residue 2:
position original_residue mutation 1 M DMG 2 Q Q
Optional - all-mutations mode
you can omit an input mutations-file and instead run in all-mutations mode, where all mutations at each position will be selected
Optional - dump-pdb mode
run with this flag to output the PDB for each mutation as well as the score
Command Line Examples (DDG)
Prepare an input mutations file for use with DDG
cyrus prepare mutations <pdb-file> --output-dir <output-dir>
Run DDG on an input structure with mutations that are included in the input mutations file
cyrus submit ddg <pdb-file> --mutations-file <mutations-file>
Run DDG on an input structure with all mutations selected
cyrus submit ddg <pdb-file> --all-mutations
Run DDG on an input structure with all mutations selected and output the PDBs as well as scores
cyrus submit ddg <pdb-file> --all-mutations --dump-pdb
Python Examples (DDG)
Run DDG on an input structure with mutations that are included in the input mutations file
from engine.ddg.client import DdgClient client = DdgClient() job_id = client.submit(pdb_path="input.pdb", mutations_path="input.tsv")
Run DDG on an input structure and dump the output PDB files
from engine.ddg.client import DdgClient client = DdgClient() job_id = client.submit(pdb_path="input.pdb", mutations_path="input.tsv", dump_pdb=True)
Outputs (DDG)
results.tsv
file with one mutation and score per-line
mutation-input.tsv
input mutations file
pdbresults.tar.gz
output PDB files, will be empty if
--dump-pdbomitted