Skip to main content
Docs

Search guides and API endpoints, for example “Idempotency-Key” or “submit job”.

    Tools · Computational Biology

    Stability ΔΔG Predictor

    Rank point variants of a protein by the predicted change in folding stability, or scan residues to alanine, from one chain of a structure with ThermoMPNN.

    Updated November 9, 2026

    On this page

    Prices, workflows, and method papersOpen in the app

    Stability ΔΔG Predictor answers the first question to ask about any variant: is it likely to unfold the protein? You have a structure and a list of point variants — from Sequence Mutator, from a design run, or from your own notes — or you want to know which residues of a chain tolerate a change at all. The job returns a ranked table of predicted changes in folding free energy, in kcal/mol, so you can set aside the variants predicted to destabilize the fold before you spend compute on folding or docking them. It orders variants; it does not give accurate free energies.

    How the prediction works

    The model is ThermoMPNN, a ProteinMPNN graph network fine-tuned on mega-scale measurements of protein stability. It reads the backbone of one chain and predicts the change in folding free energy for each substitution in a single pass. No mutant structure is built and nothing is trained per protein: the parent's structure is the only input. A predicted structure can stand in for a crystal structure: on 87 chains of a literature benchmark, ESMFold2 models ranked as well as crystal structures (low-confidence models were not tested).

    Values follow the folding convention: negative predicts a more stable protein than the parent, positive a less stable one. The table ranks variants by that value, most stabilizing first.

    The published model is deterministic, so repeating it would give the same number. The standard deviation in each row is something this tool adds: the spread of the prediction across several passes with a small amount of Gaussian noise (0.2 Å) added to the backbone coordinates. It shows how far a prediction moves when the backbone moves. It grows with the size of the prediction, it is five to ten times smaller than the model's real error, and in the benchmark it did not tell us how wrong a prediction was. It is not a confidence interval or an error bar.

    A variant with several substitutions reports the sum of its single-site predictions. Interactions between neighbouring residues are not modeled.

    How well it works

    Measured on proteins the model was not trained on, against experimental ΔΔG (95% intervals; details in experiments/stability-ddg-benchmark).

    • Ranking. Mean rank correlation per domain 0.74 [0.70, 0.78] on held-out mega-scale measurements (19 domains, about 20 000 variants); 0.39 [0.22, 0.54] on literature mutations (S669, 488 variants). Better than a prior built from the amino-acid change on both, and than a ProteinMPNN log-probability score on the mega-scale data (0.53); on the literature set the two cannot be told apart.
    • Size. The typical error on literature mutations is 1.2 kcal/mol (root-mean-square 1.7), no better than guessing the average; on mega-scale data it is 0.55 (0.75). Use the values to order variants, not as free energies.
    • Direction. 99% of mega-scale variants measured at +1 kcal/mol or worse are predicted to destabilize (91% on the literature set), but only 63% (35%) of those measured at −1 or better are predicted to stabilize. Of each protein's top tenth by predicted stabilization, 4.9% were measured at −1 or better (5.3 times chance).
    • Alanine scans. The order of sites in a domain has a rank correlation of 0.73 [0.66, 0.80] on mega-scale data; not checked on literature data.

    Inputs

    • Structure: a PDB file. Only one chain is scored, as a monomer; other chains in the file are ignored, including as context for the chain you score. Upload it or bind it from an upstream structure step.
    • Chain: optional. Left blank, the first chain in the file whose sequence matches the parent is scored, or the first chain in the file when there is no parent.
    • Parent sequence: the chain you are mutating, as one-letter codes or one FASTA record, exactly as it appears in the structure. Required for mutation strings and variant sequences, optional for a scan.
    • Variants, in one of three ways:
      • Mutation strings in the Sequence Mutator syntax: one per line, T315I, joined with + for combined variants. Positions are the chain's own residue numbers, and each stated wild-type residue is checked against the chain when the job runs, so a numbering offset fails with the residue actually found.
      • Variant sequences: one FASTA record per variant, each the parent length; positions that differ from the parent become the scored substitutions.
      • A scan: replace each chosen residue, or every residue of the chain, with one amino acid (alanine by default) and rank the positions by what the change costs. Residues that already are that amino acid, non-standard residues, and residues with missing backbone atoms are left out and listed in the results.

    first_residue_number is optional. Left out, the chain's own first residue number is used; if you give it, it must match the chain.

    Outputs

    • predictions.csv: one row per variant: name, predicted ΔΔG, standard deviation across the noise passes, number of substitutions, and rank.
    • sequences.fasta: the scored parent (WT) and, for a variant run, every variant, so the survivors can be folded or modeled downstream.
    • summary.json: the chain that was scored, the settings, the engine revision, and for a scan which positions were scanned and which were skipped and why.

    In a workflow

    Both the predictions and the sequences ports carry the stability_ddg_kcal_mol metric: each variant's predicted ΔΔG, and 0.0 for the parent, its change relative to itself. That lets a filter step gate the next, more expensive step on the sequences port, where a filtered table could not feed a structure predictor. The ready-made workflow Triage point mutations by predicted stability before folding them chains Sequence Mutator, this tool, a filter that keeps the wild type and the variants predicted not to destabilize the fold, and ESMFold2 on the best of those.

    Pair it with Binding ΔΔG to catch a classic trap: a mutation that helps binding but destabilizes the fold.

    Honest limits

    • Rank-ordering within one campaign is what the tool is for. The values are not accurate free energies (the error on literature mutations is about 1.2 kcal/mol, and as large as the spread of the measurements themselves), and they are not melting temperatures.
    • Monomers and the 20 standard residues only. Disulfides, cofactors, metals, ligands, membrane proteins and interfaces between chains are not seen by the model, and none was benchmarked.
    • Several substitutions in one variant are summed, so strongly coupled changes can be mispredicted in either direction. The sum was not benchmarked.
    • A badly wrong structure can still give meaningless ranks, and the noise spread is not a reliable warning: it did not predict which predictions were wrong.
    • Predictions support prioritization. Express and measure the top variants.

    Run it from the API

    Submit with Submit a job and the job_type below. Price it first with Estimate job reservation cost: submitting reserves that amount from your wallet, and the charge settles at the actual runtime.

    Stability ΔΔG Predictor stability-ddg

    Job type
    stability-ddg
    Hardware
    cpu (default)
    Typical runtime
    2 min on CPU

    Payload

    Provide exactly one of: parent_sequence + mutations, parent_sequence + variant_sequences, scan.

    Payload fields
    FieldTypeDescription
    structurerequiredfile_object
    chainstring

    Limits: min length 1, max length 1

    parent_sequencestring | object
    mutations[]string[]

    Limits: min items 1, max items 50

    variant_sequences[]string[]

    Limits: min items 1, max items 50

    scanobject
    scan.positions[]integer[]

    Limits: min items 1, max items 500

    scan.tostring

    Default: "A"Limits: pattern ^[ACDEFGHIKLMNPQRSTVWYacdefghiklmnpqrstvwy]$

    first_residue_numberinteger

    Limits: ≥ -10000, ≤ 100000

    num_samplesinteger

    Default: 8Limits: ≥ 2, ≤ 32

    File fields take {"name": "x.pdb", "content_b64": "…"} or a stored artifact, {"$artifact": {"id": "art-…", "port": "…"}}. Files are up to 25 MiB each.

    Example

    from cognichem_client import CogniChem
    
    client = CogniChem.from_env()  # reads COGNICHEM_API_KEY
    payload = {
        "structure": {
            "name": "structure.pdb",
            "content_b64": "<file contents, base64>",
        },
        "parent_sequence": "ACDEFGHIKLMN",
        "mutations": ["A1V", "K9R", "A1V+K9R"],
    }
    
    estimate = client.jobs.estimate(job_type="stability-ddg", payload=payload, resource="cpu")
    print(f"Reserves ${estimate.cost:.2f}")
    
    job = client.jobs.submit(
        job_name="my-stability-ddg-run",
        job_type="stability-ddg",
        payload=payload,
        resource="cpu",
    )
    status = client.jobs.wait(job.process_id)
    if status.status == "completed":
        client.jobs.result(job.process_id, save_path=".")

    Sample data from the job catalog; long values are shortened here. Each job_name must be unique among your jobs.

    Workflow inputs

    • Protein sequences · optionalFASTA, RAW
    • Protein structurePDB
    • Protein sequences (list) · optionalFASTA, RAW

    Workflow outputs

    • ArchiveZIP
    • TableCSV
    • Protein sequencesFASTA