README.md

metadata

title: DeepMutate-3D
emoji: 🧬
colorFrom: red
colorTo: blue
sdk: gradio
sdk_version: 5.50.0
python_version: 3.12.12
app_file: app.py
pinned: false
license: apache-2.0
short_description: ESM-2 mutation scanning painted onto the AlphaFold 3D fold
models:
  - facebook/esm2_t33_650M_UR50D
  - facebook/esm2_t30_150M_UR50D
  - facebook/esm2_t12_35M_UR50D
preload_from_hub:
  - facebook/esm2_t33_650M_UR50D

Predict the effect of every possible point mutation in a protein and see the result on its 3D structure.

DeepMutate-3D scores all 19 possible substitutions at every residue with the ESM-2 protein language model, then paints the per-residue sensitivity onto the AlphaFold predicted fold. Red marks positions where mutation is likely to be damaging. Blue marks positions that tolerate change.

Contents

• Install
• Quick start
• Usage
• How it works
• Benchmarks
• Examples
• Citation
• License

Install

git clone https://github.com/Saadman/DeepMutate-3D.git
cd DeepMutate-3D
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

Runs on NVIDIA (cuda), Apple Silicon (mps) or CPU. The device is selected automatically. The first run downloads the model weights and caches them.

Quick start

python app.py

Gradio prints the local URL on startup, usually http://127.0.0.1:7860. It falls back to the next free port if that one is taken, and honours GRADIO_SERVER_PORT if you set it.

Open the printed URL, enter a UniProt ID such as P69905, leave the sequence box empty, and press scan.

Usage

Inputs. A protein sequence (raw or FASTA) and a UniProt accession. If the sequence box is empty, the canonical sequence is fetched from UniProt, which also guarantees the scores line up with the structure.

Options.

Option	Choices	Notes
Model	ESM-2 35M, 150M, 650M	650M is the default and the most accurate
Scoring mode	masked marginals, wildtype marginals	wildtype is far faster and nearly as accurate

Outputs.

• An interactive 3D structure coloured by mutation sensitivity. Hover any point on the ribbon to read that residue's scores.
• A per-residue table: sensitivity score, verdict, most damaging substitution and most tolerated substitution.
• Two downloads: the table as CSV, and the structure as a PDB file whose B-factor column carries the sensitivity score, so it opens in PyMOL or ChimeraX and colours with spectrum b, red_white_blue.

Proteins longer than the 1022 residue ESM-2 context are covered with overlapping windows, so length is not a limit.

How it works

For every position i and every substitution m, the model computes a log-likelihood ratio against the wildtype residue:

LLR(i, m) = log P(m | context) - log P(wildtype_i | context)

The 19 non-wildtype LLRs at each position are averaged into a single Residue Sensitivity Score. Scores are written into the PDB B-factor column and rendered with py3Dmol using a red-white-blue gradient centred on zero.

Nothing is trained or fine-tuned here. Predictions are zero-shot.

Benchmarks

Zero-shot, no experimental data shown to the model.

Benchmark	Scale	Result
ProteinGym	197 DMS assays, 644,231 variants	Spearman rho 0.431
ClinVar	2,011 proteins, 38,901 variants	AUROC 0.881

Full tables, the model size ablation, and the runtime comparison across CPU, Apple Silicon and NVIDIA are in docs/BENCHMARKS.md.

Reproduce:

pip install -r validation/requirements.txt
mkdir -p validation/data
curl -L -o validation/data/DMS_substitutions.parquet \
  https://proteingym.s3.amazonaws.com/DMS_substitutions.parquet
python validation/run_proteingym.py --mode wt

Examples

Worked case studies with reproducible output are in docs/USE_CASES.md, covering cancer hotspot recovery in TP53, catalytic site recovery across an enzyme panel, and selecting tolerant positions for library design.

python examples/use_cases.py

Citation

If you use DeepMutate-3D, please cite the preprint:

Karim, R. DeepMutate-3D: interactive protein language model mutation scanning on predicted structures. Zenodo (2026). https://doi.org/10.5281/zenodo.22679613

and the underlying resources. AlphaFold data is CC-BY-4.0 and requires attribution.

• Lin, Z. et al. Evolutionary-scale prediction of atomic-level protein structure with a language model. Science 379, 1123-1130 (2023).
• Meier, J. et al. Language models enable zero-shot prediction of the effects of mutations on protein function. NeurIPS (2021).
• Jumper, J. et al. Highly accurate protein structure prediction with AlphaFold. Nature 596, 583-589 (2021).
• Varadi, M. et al. AlphaFold Protein Structure Database in 2024. Nucleic Acids Research 52, D368-D375 (2024).

Contributing

Issues and pull requests are welcome. CONTRIBUTING.md lists the gaps I know about, including the AlphaMissense comparison and the untested 650M masked-marginal configuration.

License

Apache-2.0. Free for academic and commercial use.

DeepMutate-3D retrieves but does not redistribute ESM-2 (MIT), AlphaFold DB structures (CC-BY-4.0) and UniProt sequences (CC-BY-4.0). Full attributions in NOTICE.

Disclaimer

DeepMutate-3D predicts evolutionary constraint, which correlates with but is not identical to pathogenicity. It is a research tool for hypothesis generation and must not be used to inform clinical or diagnostic decisions.