Structural biology

Protein Structures — AlphaFold & PDB

How to get a protein's 3D structure and show it to the user. Most "predict the structure of protein X" requests do not require running AlphaFold — the AlphaFold DB already holds a precomputed prediction for nearly every known protein. Run a prediction only for a sequence that is not a known UniProt entry.

1. AlphaFold DB — predicted structures (the usual path)

The AlphaFold Database has precomputed AlphaFold models for ~200M+ UniProt proteins. If the protein is a known UniProt entry, its predicted structure already exists — just fetch it (instant, free).

Use the API — do not hand-build file URLs (the model version, currently v6, changes; the API always returns the live URLs):

import requests

acc = "P00533"  # UniProt accession (human EGFR)
meta = requests.get(
    f"https://alphafold.ebi.ac.uk/api/prediction/{acc}", timeout=30
).json()[0]
cif_url = meta["cifUrl"]          # also: pdbUrl, bcifUrl
with open(f"{acc}.cif", "wb") as fh:
    fh.write(requests.get(cif_url, timeout=60).content)

No UniProt accession yet? Resolve a gene name / protein name to an accession first via the UniProt REST API (https://rest.uniprot.org/uniprotkb/search?query=<gene>+AND+organism_id:9606&format=json) or the gget package — pick the reviewed (Swiss-Prot) entry.

2. RCSB PDB — experimental structures

For a solved, experimental structure, download from the RCSB PDB by id:

https://files.rcsb.org/download/<PDBID>.cif      (or .pdb)

3. Predicting a novel sequence

If the sequence is not a known UniProt protein (a designed, mutant, or synthetic sequence), the AlphaFold DB has nothing — you must predict it.

ESMFold API — the practical path (no GPU)

ESMFold (Meta's structure predictor) has a public folding API: POST a raw amino-acid sequence, get a PDB structure back. No GPU, no install, no databases — this is the realistic way to predict a novel sequence here.

import requests

seq = "MALWMRLLPLLALLALWGPDPAAA..."          # one-letter, a single chain
resp = requests.post("https://api.esmatlas.com/foldSequence/v1/pdb/",
                     data=seq, timeout=180)
resp.raise_for_status()
with open("predicted.pdb", "w") as fh:
    fh.write(resp.text)

Caveats — state them when reporting a prediction: ESMFold is a single-sequence language-model predictor (no MSA), so it is less accurate than AlphaFold2 on low-homology / hard targets; it predicts a single chain (no complexes); there is a length limit (~400 residues). It is a free public service — it can be slow or briefly unavailable.

ColabFold / local AlphaFold — only with a real GPU

AlphaFold2-quality prediction (with MSA) means ColabFold (colabfold_batch) or local AlphaFold — both need a CUDA GPU. This is not available on a Mac or any machine without an NVIDIA GPU. Run nvidia-smi to check first; never assume this route exists. (Full local AlphaFold2/3 also needs hundreds of GB of databases — impractical.) Without a GPU, use the ESMFold API above, or the ColabFold notebook in a browser (not agent-drivable).

Confidence — pLDDT

AlphaFold reports a per-residue confidence, pLDDT (0–100): >90 very high, 70–90 confident, 50–70 low, <50 very low (often intrinsically disordered). Always caveat low-pLDDT regions when interpreting a predicted model. AlphaFold also outputs PAE (predicted aligned error) — use it to judge inter-domain / inter-chain placement confidence.

Visualising the structure

Show the structure in the Mol* LiveView viewer (see the live_view skill, molstar viewer):

# an AlphaFold model — Mol* fetches it and colours by pLDDT
open_live_view(view_type="molstar", title="EGFR (AlphaFold)",
               state={"alphafold": "P00533"})

# an experimental PDB entry
open_live_view(view_type="molstar", title="...", state={"pdbId": "1CBS"})

# a local structure file (an ESMFold / ColabFold output, a downloaded model)
serve_local_data("predicted.pdb")               # -> { url }
open_live_view(view_type="molstar", title="...",
               state={"url": <that url>, "format": "pdb"})