tooluniverse-protein-structure-prediction

What this skill does

# 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

| Parameter | Required | Description | Example |
|-----------|----------|-------------|---------|
| **sequence** | Yes (for ESMFold) | Amino acid sequence (single-letter FASTA) | `MVLSPADKTNVK...` |
| **uniprot_id** | Yes (for AlphaFold) | UniProt accession | `P04637`, `P69905` |
| **variant** | No | Variant notation for structural impact | `P04637 R175H`, `TP53 R175H` |
| **max_length** | No | ESMFold limit: ~800 residues recommended | — |

---

## 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

| pLDDT Range | Interpretation | Reliability |
|-------------|---------------|-------------|
| >90 | Very high confidence | Equivalent to experimental quality |
| 70-90 | High confidence | Backbone reliable, side chains approximate |
| 50-70 | Low confidence | Potentially disordered or flexible region |
| <50 | Very low confidence | Likely intrinsically disordered; do not interpret |

| pTM Score | Fold Confidence |
|-----------|----------------|
| >0.8 | High confidence global fold |
| 0.5-0.8 | Moderate; some domains may be uncertain |
| <0.5 | Low global fold confidence |

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

### 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
- If AlphaFold confidence is very high (mean pLDDT > 85): recommend using AlphaFold as primary reference

---

## Phase 4: Experimental Structure Comparison

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

### Tools

**RCSBAdvSearch_se