DDG API

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-Levitate 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. In the second step of the DDG process the TSV mutation file (described below) is parsed to generate a list of all specified single point mutations. Each one of these mutations is simulated via the Cartesian DDG protocol and DDG scores are reported for each mutation.

DDG Relax

Command Line Interface

Examples

Prepare an input PDB file for use with DDG.

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.

lev engine submit ddg-relax <pdb-file>

Flags

  • pdb_file (str) (Required)
    • Input PDB file
    • You can specify this flag as the first positional argument or with the --pdb-file flag

Python Interface

Examples

Prepare an input pdb file for use with DDG

from engine import EngineClient

client = EngineClient()
client.authorize()

job_id = client.submit_ddg_relax(
    pdb_path="input.pdb"
)

Flags

  • pdb_path (str) (Required)
    • Input PDB file
    • You can specify this flag as the first positional argument or with the --pdb-file flag

DDG

Command Line Interface

Examples

Prepare an input mutations file for use with DDG

lev engine prepare mutations <pdb-file> \
    --output-dir <output-dir>

Run DDG on an input structure with mutations that are included in the input mutations file

lev engine submit ddg <pdb-file> \
    --mutations-file <mutations-file>

Run DDG on an input structure with all mutations selected

lev engine submit ddg <pdb-file> \
    --all-mutations

Run DDG on an input structure with all mutations selected and output the PDBs as well as scores

lev engine submit ddg <pdb-file> \
    --all-mutations \
    --dump-pdb

Run DDG on an input structure with single mutations from mutations file and multi-mutations from multi-mutations file

lev engine submit ddg <pdb-file> \
    --mutations-file <mutations-file> \
    --multi-mutations-file <multi-mutations-file>

Flags

  • --all-mutations (bool) (Default = false)
    • Run with this flag to output the PDB for each mutation as well as the score
  • --cutoff (int) (Default = 0)
    • The PSSM score cutoff. Mutations with scores >= than the specified score will be evaluated
  • --dump-pdb (bool) (Default = false)
    • Run with this flag to output the PDB for each mutation as well as the score
  • --multi-mutations-file (str) (Optional)
    • TSV file containing mutations to run simultaneously. Similar format to the mutations file, but with each run’s mutations separated with --- 
        ---
  position    original_residue    mutation
  5   K   S
  42  T   I
  ---
  position    original_residue    mutation
  5   K   S
  42  T   K
  ---
  • mutations-file (str) (Optional)
    • Tab Separated Value (TSV)-formatted file containing mutations. To create an empty mutations file from an input PDB, run: 
        lev engine prepare mutations <pdb-file> --output-dir <output-dir>
  • pdb-file (str) (Required)
    • Input PDB file
    • You can specify this flag as the first positional argument or with the --pdb-file flag
    • Examples:
      • "input.pdb" - Local PDB file
      • "structures/protein.pdb" - PDB file in subdirectory
      • "/path/to/structure.pdb" - Full path to PDB file
  • pssm-file (str) (Optional)
    • PSSM file to use for DDG calculations

Python Interface

Examples

Run DDG on an input structure with mutations that are included in the input mutations file

from engine import EngineClient

client = EngineClient()
client.authorize()

job_id = client.submit_ddg(
    pdb_path="input.pdb",
    mutations_path="input.tsv"
)

Run DDG on an input structure and dump the output PDB files

from engine import EngineClient

client = EngineClient()
client.authorize()

job_id = client.submit_ddg(
    pdb_path="input.pdb",
    mutations_path="input.tsv",
    dump_pdb=True
)

Flags

  • cutoff (int) (Default = 0)
    • The PSSM score cutoff. Mutations with scores >= than the specified score will be evaluated
  • dump_pdb (bool) (Default = false)
    • Run with this flag to output the PDB for each mutation as well as the score
  • multi_mutations_path (str) (Optional)
    • TSV file containing mutations to run simultaneously. Similar format to the mutations file, but with each run’s mutations separated with --- 
        ---
  position    original_residue    mutation
  5   K   S
  42  T   I
  ---
  position    original_residue    mutation
  5   K   S
  42  T   K
  ---
  • mutations_path (str) (Optional)
    • Tab Separated Value (TSV)-formatted file containing mutations. To create an empty mutations file from an input PDB, run: 
        lev engine prepare mutations <pdb-file> --output-dir <output-dir>
    • Each row can contain one or many mutations, in the format D or DMG. For example, The TSV file below would run DDG on M1D, M1G and Q2T and would report scores for all 3 of those mutations. The mutations are performed separate from each-other (ie the M1D and M1G mutations are not performed at the same time.)
    • Do not supply the native residue as a mutation, that doesn’t make sense. 
        position	original_residue	mutation
  1	M DG
  2	Q T
  • pdb_path (str) (Required)
    • Input PDB file
    • You can specify this flag as the first positional argument or with the --pdb-file flag
  • pssm_path (str) (Optional)
    • PSSM file to use for DDG calculations

Outputs

  • results.tsv
    • file with one mutation and score per-line
  • multi-results.tsv
    • file with one score per multi-mutation run
  • mutation-input.tsv
    • input mutations file
  • multi-mutation-input.tsv
    • input multi-mutations file
  • pdbresults.tar.gz
    • output PDB files, will be empty if --dump-pdb omitted

Updated: