OmegaTherm: A Practical Guide to Protein Stability Predictions

A protein variant can change both folding free energy and melting temperature, but those measurements answer different questions. OmegaTherm brings them into one sequence-based modeling framework while retaining separate outputs. For a first trial, the useful questions are what those outputs mean, how to represent mutations correctly, and which parts of the released workflow are ready to run.

This guide reviews the original study and public implementation, then builds a small input-preparation tool. Sources were checked on October 8, 2026. The study is a bioRxiv preprint posted September 28, 2026; the results below are the authors’ reported results, not a benchmark reproduced for this article.

1. What OmegaTherm predicts

The two outputs are related, but they are not interchangeable. Do not average them or convert one into the other with a fixed multiplier. In particular, a ΔTm prediction is a change, not the mutant’s absolute melting temperature.

Check the sign convention before ranking variants. The paper’s ΔΔG classification treats values above +0.5 kcal/mol as stabilizing, below −0.5 as destabilizing, and the interval between as neutral. That convention must not be silently mixed with a tool that assigns the opposite sign. These thresholds describe the study’s classification task, not a universal experimental acceptance rule. See the paper’s ΔΔG results section.

2. How the model combines the measurements

The official method description describes three main components:

1. A shared protein language model encodes the wild-type and mutant sequences and supplies sequence-derived contact information.
2. Measurement-specific, mutation-centered encoders combine context around the altered residues, including more distant contact neighbors.
3. Self-distillation and cross-distillation transfer supervision between incompletely paired ΔΔG and ΔTm datasets, with filters for inconsistent pseudo-labels.

An antisymmetric design aims to reverse the predicted sign when wild-type and mutant are exchanged. This is a useful consistency property, but it does not prove that a prediction is experimentally accurate. Multiple substitutions are modeled together; summing independently predicted single-mutant effects is not the same calculation.

Sequence-based input therefore does not mean the model ignores spatial context. It uses predicted contacts without requiring an experimentally determined structure from the user.

3. What the paper reports

The authors evaluate single and multiple mutations on S461 and M223 for ΔΔG, and S571 and M286 for ΔTm. They report single-mutation ΔΔG Pearson correlation of 0.83 and single-mutation ΔTm MAE of 4.89 °C. Their Methods describe filtering test proteins to at most 25% sequence identity to the corresponding training proteins. See Results and Methods.

Treat these as results under the paper’s benchmark protocol. Before comparing numbers with another model, align datasets, mutation directions, exclusions, and metrics. A whole-dataset correlation also does not tell you whether a model ranks variants well within your particular protein.

For your own experiment, keep homologous proteins and reversed mutation pairs from leaking across splits. Evaluate the measurement you actually need, report absolute errors as well as ranking, and retain a held-out set. The site’s protein group-split tutorial explains why an ordinary random row split can be misleading.

4. Choose the web server or local code

The public server accepts a CSV upload and asks for an email address. Its linked help page uses name, wt_seq, mut_seq, pH, and temp, with uppercase amino-acid sequences and temperature in °C.

There is an important interface distinction: on the date checked, the upload form explicitly required exactly one mutated residue per row. The local predictor supports multiple substitutions. For combinations, use the local route after obtaining its weights, or confirm current server support with the authors. Do not assume that a framework capability is already exposed by the web form.

The local implementation also accepts mutation strings, but this article prepares explicit wild-type/mutant sequence pairs. That makes the intended change easy to inspect before submission.

5. Prepare a small, checked input

Download prepare_omegatherm.py. It uses only Python’s standard library; Python 3.10 or newer is sufficient. In a fresh directory, run:

python3 prepare_omegatherm.py --help
python3 prepare_omegatherm.py variants.csv \
  --sequence ACDEFGHIKLMNPQRSTVWY \
  --mutation D3N \
  --mutation 'A1V;Y20F' \
  --ph 7 --temp 25

It prints Wrote 2 variants to variants.csv and creates:

name,wt_seq,mut_seq,pH,temp
variant_1,ACDEFGHIKLMNPQRSTVWY,ACNEFGHIKLMNPQRSTVWY,7.0,25.0
variant_2,ACDEFGHIKLMNPQRSTVWY,VCDEFGHIKLMNPQRSTVWF,7.0,25.0

This 20-residue sequence is a synthetic format example, not a biologically validated protein or a prediction result. D3N changes position 3, using 1-based numbering. The second row combines positions 1 and 20 in one variant; it is intended for the local multiple-mutation route, not the current single-mutation upload form.

For a real protein, use the exact sequence construct and conditions being assessed. A residue number from a PDB file, mature chain, or tagged construct may not match the position in the submitted sequence.

The helper below deliberately accepts only the 20 standard uppercase amino acids, rejects repeated positions and unchanged residues, and refuses to overwrite an existing output. Its 1,000-residue ceiling is a conservative tutorial policy, not a published OmegaTherm performance limit.

"""Build a validated OmegaTherm CSV; this does not run the prediction model."""
import argparse
import csv
import math
from pathlib import Path
import re

AMINO_ACIDS = set("ACDEFGHIKLMNPQRSTVWY")


def make_mutant(sequence, mutations):
    if not sequence or len(sequence) > 1000 or set(sequence) - AMINO_ACIDS:
        raise ValueError("Use 1-1000 uppercase standard amino-acid residues")
    tokens = mutations.split(";")
    result = list(sequence)
    used = set()
    for token in tokens:
        match = re.fullmatch(r"([ACDEFGHIKLMNPQRSTVWY])([1-9][0-9]*)([ACDEFGHIKLMNPQRSTVWY])", token)
        if match is None:
            raise ValueError(f"Invalid substitution: {token!r}")
        old, position, new = match.groups()
        index = int(position) - 1
        if index >= len(sequence) or sequence[index] != old:
            raise ValueError(f"Wild-type residue or position mismatch: {token}")
        if index in used or old == new:
            raise ValueError(f"Repeated position or unchanged residue: {token}")
        used.add(index)
        result[index] = new
    return "".join(result)


def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("output", type=Path, help="new CSV path; parent must exist")
    parser.add_argument("--sequence", required=True)
    parser.add_argument("--mutation", action="append", required=True,
                        help="one variant per flag; use semicolons within a variant")
    parser.add_argument("--ph", type=float, required=True)
    parser.add_argument("--temp", type=float, required=True, help="degrees Celsius")
    args = parser.parse_args()
    try:
        if not math.isfinite(args.ph) or not 0 <= args.ph <= 11:
            raise ValueError("pH must be finite and between 0 and 11")
        if not math.isfinite(args.temp) or not 0 <= args.temp <= 120:
            raise ValueError("Temperature must be finite and between 0 and 120 Celsius")
        rows = []
        for number, mutations in enumerate(args.mutation, start=1):
            mutant = make_mutant(args.sequence, mutations)
            rows.append([f"variant_{number}", args.sequence, mutant, args.ph, args.temp])
        with args.output.open("x", encoding="utf-8", newline="") as handle:
            writer = csv.writer(handle, lineterminator="\n")
            writer.writerow(["name", "wt_seq", "mut_seq", "pH", "temp"])
            writer.writerows(rows)
    except (OSError, ValueError) as exc:
        parser.exit(1, f"error: {exc}\n")
    print(f"Wrote {len(rows)} variants to {args.output}")


if __name__ == "__main__":
    main()

The local predictor can replace missing or nonnumeric condition fields with defaults. Its dataset code clamps pH to 0–11 and temperature to 0–120 °C before internal scaling. Our helper requires finite, explicit values within those intervals so that these transformations do not silently alter the submitted conditions. These software intervals are not validated operating ranges for the model. See the pinned input preparation and dataset implementation.

6. Understand what local inference still needs

The commands below match the inspected repository at commit 423b16a2361500a44c1afe7e383ad5167a8fabf7. They are a source-checked setup recipe; full model inference was not run for this article.

git clone https://github.com/CSUBioGroup/OmegaTherm.git
cd OmegaTherm
git checkout 423b16a2361500a44c1afe7e383ad5167a8fabf7
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements.txt
python predict_mutations.py --help

The repository expects the ESM-2 encoder plus three trained checkpoints for its default ensemble:

weights/
  esm2_t33_650M_UR50D/
  single_ddG_LocalTransformer_AntiSym_rank_FullFT_pseudo_finetune_final.pt
  single_dTm_LocalTransformer_AntiSym_rank_FullFT_pseudo_finetune_final.pt
  joint_fullft_localtransformer_cross_pseudo_final.pt

At the checked commit, the weights directory contains placement instructions, not the checkpoint binaries. The top-level README names the files but does not provide a complete checkpoint-download procedure. Obtain the matching artifacts from the authors’ official distribution before proceeding; cloning the repository or downloading ESM-2 alone is insufficient.

The dependency list is unpinned, so record the environment that actually works with the supplied checkpoints. Avoid disabling strict checkpoint loading merely to hide a mismatch.

Once the required artifacts are in place, copy your variants.csv into the repository root and run:

python predict_mutations.py \
  --input-csv variants.csv \
  --output-csv variants_predictions.csv \
  --batch-size 1 \
  --precision fp32

The prediction script chooses CUDA when available and CPU otherwise. Batch size 1 is a starting setting, not a guarantee that the model fits your hardware. The dataset enables tokenizer truncation with a default --max-length of 1022 tokens; check tokenized length and mutation visibility before attempting long sequences.

7. Read the outputs and test the preparation step

The local CSV distinguishes single-task columns (ddG_fullft, dTm_fullft) from joint-model columns (ddG_joint, dTm_joint). The final ddG_pred and dTm_pred columns average the available single-task and joint predictions. These are point estimates, not confidence intervals. The server’s example instead uses direct/inverse column names; do not assume the two output schemas are identical. See the local output code and server example.

Save this check beside the downloaded helper as check_input.py, then run python3 check_input.py:

from prepare_omegatherm import make_mutant

sequence = "ACDEFGHIKLMNPQRSTVWY"
assert make_mutant(sequence, "D3N") == "ACNEFGHIKLMNPQRSTVWY"
assert make_mutant(sequence, "A1V;Y20F") == "VCDEFGHIKLMNPQRSTVWF"
for invalid in ["A3N", "D3D", "D3N;N3A", "Y21F"]:
    try:
        make_mutant(sequence, invalid)
    except ValueError:
        pass
    else:
        raise AssertionError(f"Accepted invalid substitution: {invalid}")
print("PASS: single/multiple substitutions and invalid inputs")

The preparation tool passed six local tests, including agreement with the upstream mutation-construction functions for the two valid examples, rejection of invalid conditions, and preservation of existing output files. These tests validate input handling only; they do not validate neural-network predictions or reproduce the paper’s accuracy.

8. Troubleshooting and a sensible first experiment

Start with a small set of variants that have measurements under comparable conditions, then assess how useful the rankings and absolute errors are for that protein. A predicted stability improvement should not be treated as an affinity, expression, or activity measurement.

9. Summary

OmegaTherm offers a shared framework for two distinct stability responses and supports joint evaluation of multiple substitutions in its local implementation. Begin with validated sequence pairs and explicit conditions, and check the interface and checkpoint requirements before running it. Use the resulting scores to prioritize experiments, with validation matched to your protein and measurement.