tooluniverse-protein-structure-prediction

Protein Structure Prediction and Analysis

End-to-end workflow for protein structure prediction starting from a sequence or UniProt accession. Combines ESMFold de novo prediction, AlphaFold database retrieval, experimental structure benchmarking from RCSB, ProtVar variant impact assessment, and ProtParam sequence property calculation.

KEY PRINCIPLES:

1. Sequence first — obtain or verify the protein sequence before prediction
2. ESMFold for fast de novo — works directly on sequence (up to ~800 residues); no database lookup needed
3. AlphaFold for reference — retrieve precomputed AlphaFold model for comparison; use qualifier parameter (UniProt accession)
4. Quality before interpretation — always report pLDDT scores; do not interpret low-confidence regions as folded
5. Experimental validation — compare predictions to RCSB experimental structures when available
6. ProtVar for variants — use when the question involves mutations or SNVs affecting structure
7. English-first queries — use English protein names in all tool calls; respond in the user's language

LOOK UP, DON'T GUESS

When uncertain about any scientific fact, SEARCH databases first rather than reasoning from memory. A database-verified answer is always more reliable than a guess.

COMPUTE, DON'T DESCRIBE

When analysis requires computation (statistics, data processing, scoring, enrichment), write and run Python code via Bash. Don't describe what you would do — execute it and report actual results. Use ToolUniverse tools to retrieve data, then Python (pandas, scipy, statsmodels, matplotlib) to analyze it.

When to Use

Apply when users ask:

• "Predict the structure of this sequence: [FASTA]"
• "What does the AlphaFold model for [protein] look like?"
• "How confident is the AlphaFold prediction for [protein]?"
• "Is there an experimental structure for [protein] and how does it compare to AlphaFold?"
• "How does mutation [variant] affect the structure of [protein]?"
• "What are the physicochemical properties of [protein] sequence?"
• "Predict the structure of this novel protein" / "I have a new sequence, can you model it?"

Not for (use tooluniverse-protein-structure-retrieval instead): retrieval-only tasks where user provides a PDB ID or wants to browse experimental structures without prediction.

Input Parameters

Workflow Overview

Phase 0: Input preparation (sequence retrieval if needed)
    |
Phase 1: Sequence properties (ProtParam_calculate)
    |
Phase 2: De novo prediction (ESMFold_predict_structure)
    |
Phase 3: AlphaFold reference (alphafold_get_prediction + alphafold_get_summary)
    |
Phase 4: Experimental structure comparison (RCSBAdvSearch_search_structures, RCSBData_get_entry)
    |
Phase 5: Variant structural impact (ProtVar_map_variant + ProtVar_get_function) [if variant provided]
    |
Phase 6: Quality synthesis and interpretation

Phase 0: Input Preparation

Objective: Obtain or verify the protein sequence needed for ESMFold prediction.

If sequence is already provided

Use it directly for ESMFold_predict_structure. Check length:

• 1-400 residues: full prediction, high confidence expected
• 400-800 residues: prediction supported, may be slower
• >800 residues: ESMFold may fail or produce lower quality; recommend using AlphaFold instead

If only protein name or UniProt ID is provided

Retrieve sequence from UniProt_get_entry_by_accession:

• accession: UniProt accession
• Extract the sequence.value field from the response

Note: If only a name is given (not accession), first resolve with UniProt_search or MyGene_query_genes to get the UniProt accession, then fetch the sequence.

Phase 1: Sequence Properties

Objective: Calculate physicochemical properties before prediction to contextualize results.

Tools

ProtParam_calculate:

• sequence: amino acid sequence string (single-letter code)
• Returns: molecular weight, isoelectric point (pI), extinction coefficient, instability index, GRAVY score, amino acid composition

Key Properties to Report

• Molecular weight — size context
• Isoelectric point (pI) — charge at neutral pH
• Instability index — >40 suggests unstable protein; affects prediction quality
• GRAVY score — hydrophobicity; >0 indicates membrane association tendency
• Length — determines ESMFold feasibility

Phase 2: De Novo Structure Prediction (ESMFold)

Objective: Predict 3D structure from sequence using Meta's ESM-2 language model.

Tools

ESMFold_predict_structure:

• sequence: amino acid sequence string
• Returns: predicted structure in PDB format, per-residue pLDDT confidence scores, pTM score (global fold confidence)

Workflow

1. Call ESMFold_predict_structure with the sequence
2. Parse pLDDT scores:
   • Per-residue confidence array
   • Compute mean pLDDT over all residues
   • Identify low-confidence regions (pLDDT < 50)
3. Parse pTM score (predicted Template Modeling score) — overall fold quality
4. Record the PDB-format coordinate output for downstream visualization

Quality Interpretation

ESMFold vs AlphaFold

• ESMFold: faster, works directly on sequence, good for novel sequences, no database lookup
• AlphaFold: uses multiple sequence alignment (MSA); typically higher accuracy for well-conserved proteins
• Both predict single-chain monomer structures (not complexes in standard mode)

Phase 3: AlphaFold Reference Model

Objective: Retrieve precomputed AlphaFold2 model for comparison and higher-accuracy reference.

Tools

alphafold_get_prediction:

• qualifier (or alias uniprot_id / uniprot_accession): UniProt accession (e.g., "P04637")
• Returns: AlphaFold model URL, pLDDT scores, model version

alphafold_get_summary:

• qualifier (or alias uniprot_id / uniprot_accession): UniProt accession
• Returns: prediction summary including confidence metrics, model quality

alphafold_get_annotations (optional):

• qualifier: UniProt accession
• Returns: functional region annotations overlaid on structure (binding sites, active sites)

AlphaFill_get_transplants (optional, ligands/cofactors):

• uniprot: UniProt accession (e.g., "P00520" ABL1)
• Returns: ligands, cofactors, and ions transplanted onto the AlphaFold model by homology, with per-transplant local RMSD and source PDB IDs
• When to use it: the apo AlphaFold model omits bound ligands/metals; run this to recover the likely cofactor/ligand/ion environment (e.g., ABL1 → STI/imatinib) for structure-guided binding-site interpretation

Workflow

1. Call alphafold_get_prediction and alphafold_get_summary
2. Extract mean pLDDT and per-residue confidence
3. Compare ESMFold vs AlphaFold pLDDT profiles:
   • Do they agree on low-confidence regions?
   • Large differences may indicate disordered/flexible regions
4. Note the AlphaFold model version (v1/v2/v3/v4)

Decision Logic

• If no UniProt accession available: skip AlphaFold; use ESMFold only
• If protein is a complex or has multiple chains: note that both tools predict single chains -- see "Complex / Ligand-Binding Prediction (Boltz)" below if the question specifically needs a multimer or protein-ligand complex, not just monomer confidence
• If AlphaFold confidence is very high (mean pLDDT > 85): recommend using AlphaFold as primary reference

Complex / Ligand-Binding Prediction (Boltz, paid -- optional)

ESMFold and standard AlphaFold (above) predict single chains only. When the question is specifically about a complex -- multi-chain assembly, or protein-ligand binding -- the official Boltz API (Boltz_* tools) covers that gap, but it's operationally different from everything else in this skill: it requires BOLTZ_API_KEY, it's a paid, asynchronous job (submit, poll, retrieve), not a free synchronous call.

Always estimate cost before submitting: call Boltz_estimate_structure_binding_cost with the same input first, and confirm with the user before calling Boltz_start_structure_binding -- don't submit a paid job on a user's behalf without that confirmation. Boltz_start_structure_binding also requires a caller-supplied idempotency_key to avoid double-billing on retry.

Workflow: Boltz_estimate_structure_binding_cost (confirm cost) -> Boltz_start_structure_binding (submit) -> Boltz_get_structure_binding (poll by job ID until complete) -> interpret confidence the same way as ESMFold/AlphaFold above.

For simple monomer confidence with no complex/binding question, ESMFold and AlphaFold remain the right default -- they're free and synchronous. Reach for Boltz only when the question can't be answered without it.

Membrane Topology & Signal Peptide Prediction (DTU tools, optional)

dtu_protein_predict runs DTU Health Tech's ML predictors on a raw sequence via the BioLib cloud runner (pip install pybiolib, anonymous, no account) — a different question than ESMFold/AlphaFold's 3D coordinates: per-residue topology and sequence features rather than a fold.

Jobs run anonymously on shared BioLib cloud infrastructure and commonly take 2-5 minutes — raise max_wait_time for large/multiple sequences, and don't treat a slow response as a hang. Input is FASTA text, a bare amino-acid string, or a fasta_path. Missing pybiolib fails cleanly with an install instruction rather than a stack trace — check for that first if the tool errors immediately.

Use this alongside Phase 1 (ProtParam) when the protein might be membrane-associated or secreted (e.g. GRAVY score > 0, or a "receptor"/"secreted"-sounding name) — a membrane topology or signal-peptide call changes how you read ESMFold/AlphaFold confidence (transmembrane helices are often high-pLDDT despite being embedded in a lipid bilayer the model never sees).

Phase 4: Experimental Structure Comparison

Objective: Check whether experimental structures exist in PDB and how predictions compare.

Tools

RCSBAdvSearch_search_structures (search by protein/gene name):

• query: protein name or gene symbol
• limit: number of results (default 10)
• Returns: list of PDB entries with resolution, method, title

RCSBData_get_entry (details for a specific PDB ID):

• pdb_id: 4-character PDB identifier
• Returns: metadata including method, resolution, chains, ligands, release date

Workflow

1. Search for experimental structures using protein name
2. Filter for highest-resolution X-ray or cryo-EM structures
3. For the best experimental structure, retrieve entry details
4. Compare to predictions:
   • If experimental structure exists: note coverage, resolution, method
   • Flag regions predicted with high confidence but missing from experimental structure (could be disordered in crystal)
   • Flag regions in experimental structure with low pLDDT (may be crystal artifacts vs true fold)

Fallback

• If RCSB search returns no results: note "no experimental structure found in PDB" and proceed with predictions only
• Suggest checking PDBe as secondary source

Phase 5: Variant Structural Impact (When Variant Provided)

Objective: Assess how a specific amino acid substitution affects the predicted structure.

Tools

ProtVar_map_variant:

• variant: string notation like "P04637 R175H" or HGVS notation
• Returns: mapped residue position, genomic coordinates, consequence type, variant accession

ProtVar_get_function:

• accession: UniProt accession
• position: integer residue position
• variant_aa: mutant amino acid (single letter)
• Returns: functional annotations — domain, active site, binding site, conservation score, clinical significance, predicted pathogenicity

Workflow

1. Call ProtVar_map_variant to resolve the variant and confirm position
2. Call ProtVar_get_function with wild-type position to get domain context
3. Assess: is the mutated residue in a critical structural region?
   • Active site / binding site: likely high functional impact
   • Buried hydrophobic core: likely destabilizes fold
   • Surface-exposed, disordered region: less likely to affect overall fold
4. Compare pLDDT at that position (from ESMFold/AlphaFold) to assess if the region is well-predicted

Evidence Grading for Variant Impact

Phase 6: Quality Synthesis and Report

Required Report Sections

1. Protein summary — name, length, pI, stability index (from ProtParam)

2. Structure prediction summary table:

   Method	Mean pLDDT	pTM/Global Score	Coverage	Notes
   ESMFold	X.X	X.X	100% (full seq)	—
   AlphaFold	X.X	—	100%	version vN
   Experimental (best)	N/A	N/A	XX%	PDB: XXXX, Xray, X.X A

3. Confidence map — regions of high vs low confidence; highlight disordered regions

4. Experimental structure comparison — does PDB have coverage? How does prediction align?

5. Variant impact (if applicable) — domain context, pathogenicity, structural consequence

6. Recommendations:

   • Which model to use for downstream applications (docking, design, etc.)
   • Regions to treat as unreliable
   • Suggested experimental validation approaches

Quality Minimums

• Report mean pLDDT for both ESMFold and AlphaFold
• Identify all low-confidence regions (pLDDT < 50) by residue range
• Check PDB for experimental structures (at minimum 1 search query)
• Compare at least 2 prediction sources when UniProt accession is available

Tool Parameter Reference

Fallback Strategies

Databases Integrated

Limitations

• ESMFold length limit: sequences longer than ~800 residues may fail or have reduced quality
• Single-chain only (ESMFold/AlphaFold): both predict monomers; for a multi-chain complex or protein-ligand binding, see the Boltz section above -- paid, not a free default
• Disordered regions: pLDDT < 50 indicates intrinsically disordered regions (IDRs) — do not interpret these as structured
• No dynamics: predicted structures are static; do not represent conformational flexibility or allosteric changes
• Novel folds: ESMFold may struggle with proteins having no homologs in training data
• AlphaFold DB coverage: some recently characterized proteins may not yet be in the AlphaFold database