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

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

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')