GPTomics/bio-structural-biology-modern-structure-prediction

Version Compatibility

Reference examples tested with: fair-esm 2.0+, biopython 1.83+, numpy 1.26+, requests 2.31+, chai_lab 0.6+, boltz 2.0+

Before using code patterns, verify installed versions match. If versions differ:

• Python: pip show <package> then help(module.function) to check signatures
• CLI: <tool> --version then <tool> --help to confirm flags

If code throws ImportError, AttributeError, or TypeError, introspect the installed package and adapt the example to match the actual API rather than retrying.

Modern Structure Prediction

"Predict the structure of my protein" -> Map an amino-acid (and optionally ligand/nucleic-acid) sequence to a single 3D model plus per-residue and pairwise confidence.

• Python: ESMFold local via esm.pretrained.esmfold_v1() (no MSA); ColabFold/AlphaFold via MMseqs2 MSA; AlphaFold3/Chai-1/Boltz for complexes and ligands.

Governing Principle: a prediction is a hypothesis, and the predictor is chosen by the input and the question

The trap is treating a prediction as an answer and picking a model by novelty. Two facts govern every decision here. First, MSA depth is the dominant accuracy determinant for the coevolution-based models (AlphaFold2/3, Chai-1, Boltz): quality tracks how well-represented the sequence's family is, not how hard the biology is, so these models excel on deep-MSA families and degrade on orphan, fast-evolving, viral, or de-novo-designed sequences (Jumper 2021 Nature 596:583; Lin 2023 Science 379:1123). ESMFold is single-sequence with no MSA, so it is fast enough for metagenomic scale but is lower-accuracy on average and degrades hardest exactly where evolutionary signal is thin. Second, a default prediction is ONE dominant conformer, not an ensemble: it does not give apo vs holo, allosteric states, or fold switches, and it carries no Boltzmann populations. MSA subsampling and AF-Cluster sample some alternate states but are unreliable, seed-sensitive hypotheses (Wayment-Steele 2024 Nature 625:832), a generality directly challenged by a Matters Arising (Schafer & Porter 2025 Nature 638:E8-E12).

Three category errors follow and must be avoided. (1) These are not variant-effect, ddG, or stability engines: a single point mutation barely changes a deep MSA, so wild-type vs mutant predictions come back near-identical with near-identical pLDDT, and the model is insensitive to the mutation by construction (Buel & Walters 2022 Nat Struct Mol Biol 29:1; Pak 2023 PLoS ONE 18:e0282689). Use AlphaMissense, FoldX/Rosetta ddG, or ESM/EVE variant scores instead. (2) No co-folder gives a trustworthy Kd from geometry: a plausible complex or ligand pose is not evidence of binding or affinity, and CASP16 assessors found co-fold affinity ranking essentially unreliable; Boltz-2's affinity module is a screening prior only, not a measured constant. (3) AF3-class diffusion models can hallucinate confident-looking order in genuinely disordered regions and have measurable chirality violations (~4.4% on PoseBusters) and atom clashes (Abramson 2024 Nature 630:493), so every ligand pose needs a physical-validity check. A confident prediction is a starting hypothesis with spatially varying reliability; validate it against experiment before believing any part of it.

Decision: which predictor for the job

| Job | Preferred | Why / caveat | |---|---|---| | Single-domain monomer, MAX accuracy | AlphaFold2 (LocalColabFold) or AlphaFold3 | Deep MSA = best accuracy; AF2 mature and well-understood | | Monomer, deep MSA, fast and free | ColabFold (MMseqs2 MSA) | 40-60x faster search, near-AF2 accuracy (Mirdita 2022) | | Metagenomic / genome-scale / triage | ESMFold | Fastest (no MSA); lower accuracy, weak on large/low-family proteins | | Single-sequence when no homologs exist | ESMFold or Chai-1 (single-seq mode) | Both skip MSA; expect reduced accuracy, sanity-check hard | | Protein-protein COMPLEX | AF-Multimer / AF3 / Boltz / Chai-1 | Gate on ipTM + inter-chain PAE, NOT per-chain pLDDT | | Complex WITH ligand/ion/nucleic acid/PTM | AF3, Boltz-1/2, or Chai-1 | Co-folders; validate the POSE (PoseBusters), NOT affinity | | Binding-affinity PRIOR for screening | Boltz-2 (affinity module) | Screening prior only; a relative affinity score, not a trusted Kd | | Commercial / on-prem deployment | Boltz-1/2 or Chai-1 (both Apache-2.0/MIT, commercial OK) | AF3 weights are non-commercial (Google terms) | | Alternative conformational states | AF2 + MSA subsampling / AF-Cluster | UNRELIABLE; hypotheses only, not ensembles or populations | | Variant effect / stability / pathogenicity | NOT these tools | Insensitive to point mutations; use AlphaMissense/FoldX/ESM |

Licenses drift; verify before deploying. AF2 code Apache-2.0, weights CC-BY-4.0 (permissive). AF3 code Apache-2.0, weights under the non-commercial "AlphaFold 3 Model Parameters Terms of Use", granted on request to non-commercial orgs and received directly from Google (open, not open-source). Boltz-1 and Boltz-2 are MIT (code + weights, commercial use permitted). Chai-1 was relicensed to Apache-2.0 for both code and weights in November 2024 (commercial use, including drug discovery, permitted; it launched Sept 2024 under a restrictive non-commercial license, so older notes may say otherwise - verify terms). ESMFold code/weights are MIT.

Decision: which confidence metric answers which question

| Metric | Scope | Answers | Read it for | |---|---|---|---| | pLDDT (0-100) | Per-residue, LOCAL | How well-placed is this residue's local environment | Trimming; a long <50 stretch usually flags an intrinsically disordered region, not an error | | PAE (Angstrom) | Residue-pair | Expected error at j when aligned on i | Domain packing, linker geometry, inter-chain arrangement | | pTM (0-1) | Whole model, GLOBAL | Estimated TM-score of the overall fold | Is the topology plausible (>~0.5) | | ipTM (0-1) | Interface | Accuracy of relative subunit positioning | Complex interface reliability (>~0.8 likely, <~0.6 unreliable) |

The load-bearing reads: high per-residue pLDDT with a high inter-domain PAE block means each domain is confident internally but their relative arrangement is unknown - do not trust the linker or domain-domain interface. For a complex, judge the interface on ipTM plus the inter-chain PAE block; a complex can have high pLDDT on both chains and still be a garbage interface. AF-Multimer ranks models by 0.8ipTM + 0.2pTM, deliberately weighting the interface. All these metrics are self-reported and can be confidently wrong together on out-of-distribution inputs.

Predict a monomer with ESMFold (fast, no MSA)

Goal: Get a single-chain model in seconds without building an MSA, and read pLDDT off the B-factor column.

Approach: Run ESMFold locally with esm.pretrained.esmfold_v1(); the hosted esmatlas API is intermittently down (SSL/internal-server errors) so local is the reliable path. pLDDT rides in the B-factor column but is confidence, not a temperature factor.

import torch
import esm

model = esm.pretrained.esmfold_v1().eval().to('cuda')  # needs ~16 GB GPU for typical proteins

sequence = 'MVLSPADKTNVKAAWGKVGAHAGEYGAEALERMFLSFPTTKTYFPHFDLSH'
with torch.no_grad():
    pdb_text = model.infer_pdb(sequence)  # returns a PDB string with pLDDT in B-factor column
with open('esmfold.pdb', 'w') as f:
    f.write(pdb_text)

Hosted-API fallback (only when no GPU and the endpoint is up):

import requests

url = 'https://api.esmatlas.com/foldSequence/v1/pdb/'
resp = requests.post(url, data=sequence, timeout=300)  # 300 s: long sequences take minutes
resp.raise_for_status()
pdb_text = resp.text

Read per-residue confidence

Goal: Summarize where a prediction is trustworthy so downstream use is restricted to confident cores.

Approach: pLDDT sits in the B-factor column of every prediction (ESMFold, AlphaFold, co-folders). Band it into the standard cutoffs; a contiguous very-low band usually marks a disordered region, not a failure.

from Bio.PDB import PDBParser

parser = PDBParser(QUIET=True)
structure = parser.get_structure('pred', 'esmfold.pdb')
plddt = {res.id[1]: res['CA'].get_bfactor() for res in structure[0].get_residues() if 'CA' in res}

# Bands from the AlphaFold/EBI convention: >90 very high, 70-90 confident, 50-70 low, <50 very low.
very_high = [r for r, s in plddt.items() if s > 90]
confident = [r for r, s in plddt.items() if 70 <= s <= 90]
very_low = [r for r, s in plddt.items() if s < 50]  # likely intrinsically disordered, not wrong
print(f'mean pLDDT {sum(plddt.values())/len(plddt):.1f}; {len(very_low)} very-low residues')

Predict a complex and gate on the interface

Goal: Model a protein-protein or protein-ligand complex and decide whether to believe the interface.

Approach: Use a co-folder (Chai-1 or Boltz), then accept the interface only if ipTM and the inter-chain PAE block agree. Chai-1 and Boltz run from the CLI; both default to no MSA and can call an MSA server. Verify the exact CLI with --help since these packages evolve fast.

import subprocess

# Chai-1: one FASTA with a header per chain; '--use-msa-server' fetches an MSA (improves accuracy).
# Reference invocation - confirm with `chai-lab fold --help`.
subprocess.run(['chai-lab', 'fold', '--use-msa-server', 'complex.fasta', 'chai_out/'], check=True)

# Boltz: FASTA or YAML input; YAML is required to request the Boltz-2 affinity module.
# Reference invocation - confirm with `boltz predict --help`.
subprocess.run(['boltz', 'predict', 'complex.fasta', '--use_msa_server'], check=True)

Goal: Gate the predicted interface before trusting any cross-chain distance.

Approach: Read ipTM and pTM from the confidence JSON the co-folder writes, and band the interface on ipTM. Below ~0.6 the interface is unreliable or the chains likely do not interact; 0.6-0.8 is uncertain and the inter-chain PAE block decides; a confident interface wants ipTM > ~0.8.

import json

with open('chai_out/scores.model_idx_0.json') as f:  # exact filename varies by tool/version
    conf = json.load(f)
iptm = conf.get('iptm')
ptm = conf.get('ptm')
if iptm is None or iptm < 0.6:        # <0.6: unreliable or chains likely do not interact
    print(f'interface NOT reliable (ipTM={iptm}); inspect inter-chain PAE before any claim')
elif iptm < 0.8:                      # 0.6-0.8: uncertain - the inter-chain PAE block decides
    print(f'interface UNCERTAIN (ipTM={iptm:.2f}); gate on the inter-chain PAE block')
else:
    ptm_str = f'{ptm:.2f}' if ptm is not None else 'NA'  # some score files omit pTM
    print(f'interface confident (ipTM={iptm:.2f}, pTM={ptm_str}); still confirm with inter-chain PAE')

Prepare an AlphaFold3 server job

Goal: Submit a monomer or complex to the AlphaFold Server without local weights.

Approach: The server takes a JSON job listing entities and seeds; multiple seeds sample the diffusion head, so request several and inspect the spread rather than trusting one sample.

import json

def af3_job(sequences, name='prediction', seeds=(1, 2, 3)):
    entities = [{'proteinChain': {'sequence': s, 'count': 1}} for s in sequences]
    return json.dumps([{'name': name, 'modelSeeds': list(seeds), 'sequences': entities}], indent=2)

job_json = af3_job(['MVLSPADKTNVKAAWGKVGAHAGEYGAEALERMFLSFPTTKTYFPHFDLSH'])

Reconcile multiple predictions

Goal: Compare models from different predictors and locate the regions they agree on.

Approach: Superimpose on a fixed CA correspondence and report pairwise RMSD, but treat RMSD as fold-agreement only where the aligned selection is stated; prefer a length-normalized fold metric (TM-score) for cross-method fold claims. See geometric-analysis for TM-score and superposition caveats.

from Bio.PDB import PDBParser, Superimposer

def ca_rmsd(pdb_a, pdb_b):
    parser = PDBParser(QUIET=True)
    a = [r['CA'] for r in parser.get_structure('a', pdb_a)[0].get_residues() if 'CA' in r]
    b = [r['CA'] for r in parser.get_structure('b', pdb_b)[0].get_residues() if 'CA' in r]
    n = min(len(a), len(b))  # Superimposer needs an equal-length ordered atom correspondence
    sup = Superimposer()
    sup.set_atoms(a[:n], b[:n])
    return sup.rms

print(f'ESMFold vs AF3 CA-RMSD: {ca_rmsd("esmfold.pdb", "af3.pdb"):.2f} Angstrom')

Common Errors

| Symptom | Cause | Fix | |---|---|---| | Mutant and wild-type predictions look identical | A point mutation barely changes a deep MSA; the model is insensitive to it | Do not read structure/pLDDT deltas as variant effect; use AlphaMissense, FoldX, or ESM | | Confident model but wrong in the lab | Prediction is one dominant conformer, not an ensemble; no apo/holo/allosteric states | Treat as a hypothesis; sample states cautiously (MSA subsampling) and validate experimentally | | Complex accepted on high per-chain pLDDT | pLDDT is intra-chain local confidence, blind to the interface | Gate on ipTM + inter-chain PAE block; reject interface if ipTM < ~0.6 (0.6-0.8 uncertain) | | Long low-pLDDT stretch treated as an error | Low pLDDT correlates with intrinsic disorder | Read <50 regions as likely IDRs (biologically real flexibility), not modeling failures | | Two domains confident but arrangement wrong | High intra-domain pLDDT with high inter-domain PAE | Trust each domain, not the relative orientation or linker; split at high-PAE hinges | | ESMFold much worse than AlphaFold on an orphan | ESMFold is single-sequence and degrades where evolutionary signal is thin | Use MSA-based ColabFold/AF for orphan/de-novo proteins; keep ESMFold for scale | | Ligand pose has wrong chirality or clashes | AF3-class diffusion can violate stereochemistry (~4.4% chirality) | Run PoseBusters/validity checks on every pose; do not assume physical plausibility | | Reported Kd from a co-fold pose | Co-folders give geometry, not affinity; CASP16 found affinity ranking unreliable | Use Boltz-2 affinity only as a screening prior; confirm with FEP or experiment | | esmatlas API returns SSL / internal-server error | The hosted ESMFold endpoint is intermittently down | Run ESMFold locally via esm.pretrained.esmfold_v1() | | Two predictions "disagree" but were run differently | Different MSA depth/source, recycles, seeds, or templates change the answer | Report the MSA pipeline and settings; two predictions are not comparable if these differ | | RMSD between predictions looks huge for the same fold | Global all-atom RMSD is dominated by flexible loops and needs a stated selection | Superimpose on CA/core and report the selection; use TM-score for fold agreement |

Related Skills

• alphafold-predictions - Retrieve precomputed AlphaFold DB models and read their pLDDT/PAE
• structure-io - Parse and write predicted PDB/mmCIF files
• geometric-analysis - RMSD, superposition, and TM-score caveats for comparing models
• structure-navigation - Walk chains/residues/atoms in a predicted structure
• structure-preparation - Trim, add hydrogens, and protonate a predicted model before docking or MD
• binding-site-detection - Detect pockets on a predicted model (inherits apo/rotamer uncertainty)
• alignment/structural-alignment - Structure-based alignment before comparing sequence-different models
• chemoinformatics/virtual-screening - Dock into a predicted pocket (inherits predicted rotamer/backbone error)
• chemoinformatics/ml-docking-rescoring - Rescore co-folded poses; co-fold geometry is not affinity

References

Jumper J, et al. Highly accurate protein structure prediction with AlphaFold. Nature 596:583-589 (2021). doi:10.1038/s41586-021-03819-2. Abramson J, et al. Accurate structure prediction of biomolecular interactions with AlphaFold 3. Nature 630:493-500 (2024). doi:10.1038/s41586-024-07487-w. Lin Z, et al. Evolutionary-scale prediction of atomic-level protein structure with a language model. Science 379:1123-1130 (2023). doi:10.1126/science.ade2574. Evans R, et al. Protein complex prediction with AlphaFold-Multimer. bioRxiv 2021.10.04.463034 (2021, preprint). doi:10.1101/2021.10.04.463034. Baek M, et al. Accurate prediction of protein structures and interactions using a three-track neural network. Science 373:871-876 (2021). doi:10.1126/science.abj8754. Mirdita M, et al. ColabFold: making protein folding accessible to all. Nat Methods 19:679-682 (2022). doi:10.1038/s41592-022-01488-1. Wayment-Steele HK, et al. Predicting multiple conformations via sequence clustering and AlphaFold2. Nature 625:832-839 (2024). doi:10.1038/s41586-023-06832-9. Schafer JW, ..., Porter LL (2025) Sequence clustering confounds AlphaFold2 (Matters Arising). Nature 638:E8-E12. doi:10.1038/s41586-024-08267-2. Buel GR, Walters KJ. Can AlphaFold2 predict the impact of missense mutations on structure? Nat Struct Mol Biol 29:1-2 (2022). doi:10.1038/s41594-021-00714-2. Pak MA, et al. Using AlphaFold to predict the impact of single mutations on protein stability and function. PLoS ONE 18:e0282689 (2023). doi:10.1371/journal.pone.0282689. Wohlwend J, et al. Boltz-1: democratizing biomolecular interaction modeling. bioRxiv 2024.11.19.624167 (2024, preprint). doi:10.1101/2024.11.19.624167. Chai Discovery. Chai-1: decoding the molecular interactions of life. bioRxiv 2024.10.10.615955 (2024, preprint). doi:10.1101/2024.10.10.615955.