| name | alterlab-alphafold-db |
| description | Access the AlphaFold DB of 200M+ AI-PREDICTED protein structures — retrieve models by UniProt accession, download PDB/mmCIF files, and analyze prediction confidence metrics (pLDDT, PAE). Use when a UniProt ID needs a computationally predicted 3D structure or when no experimental structure exists, for homology modeling, protein engineering, or structure-based drug discovery; for EXPERIMENTALLY determined structures (X-ray, cryo-EM, NMR) prefer alterlab-pdb, and for protein sequences, annotations, or accession ID mapping prefer alterlab-uniprot instead. Part of the AlterLab Academic Skills suite. |
| license | MIT |
| allowed-tools | Read WebFetch Bash(curl:*) Bash(python:*) |
| compatibility | Keyless AlphaFold DB (EBI) REST API; optional Google Cloud/BigQuery for bulk proteome downloads |
| metadata | {"skill-author":"AlterLab","version":"1.1.0"} |
AlphaFold Database
Overview
AlphaFold DB is a public repository of AI-predicted 3D protein structures for over 200 million proteins, maintained by DeepMind and EMBL-EBI. Access structure predictions with confidence metrics, download coordinate files, retrieve bulk datasets, and integrate predictions into computational workflows.
When to Use This Skill
This skill should be used when working with AI-predicted protein structures in scenarios such as:
- Retrieving protein structure predictions by UniProt ID or protein name
- Downloading PDB/mmCIF coordinate files for structural analysis
- Analyzing prediction confidence metrics (pLDDT, PAE) to assess reliability
- Accessing bulk proteome datasets via Google Cloud Platform
- Comparing predicted structures with experimental data
- Performing structure-based drug discovery or protein engineering
- Building structural models for proteins lacking experimental structures
- Integrating AlphaFold predictions into computational pipelines
Core Capabilities
Worked, copy-paste Python recipes for every capability below live in
references/code_examples.md. Load it when you need runnable code; the summaries
here give the routing and the key decisions.
1. Searching and Retrieving Predictions
Three entry points, in order of preference:
- Biopython (recommended):
Bio.PDB.alphafold_db.get_predictions(accession),
download_cif_for(...), get_structural_models_for(...) — simplest path.
- Direct REST:
GET https://alphafold.ebi.ac.uk/api/prediction/{uniprot_id};
the AlphaFold ID is response[0]['entryId'].
- Find accessions first via UniProt when you only have a gene name or PDB ID —
use the UniProt ID-mapping job API (
get_uniprot_ids helper in
code_examples.md §1; valid db names at
https://rest.uniprot.org/configure/idmapping/fields).
2. Downloading Structure Files
The /prediction response carries version-stamped file URLs — use those, don't
hand-build a _v{N} suffix. The DB version advances (currently v6) and old
_v4 file URLs now 404:
cifUrl / pdbUrl / bcifUrl — atomic coordinates (mmCIF / PDB / binary CIF).plddtDocUrl — per-residue pLDDT scores (0-100).paeDocUrl — PAE matrix.
Download recipe (resolve URLs from the API, write bytes) in code_examples.md §2.
3. Working with Confidence Metrics
- pLDDT: from
plddtDocUrl, read confidence['confidenceScore'] (keys:
residueNumber, confidenceScore, confidenceCategory); thresholds in
"Confidence Interpretation Guidelines" below.
- PAE: from
paeDocUrl. The endpoint returns a single-element JSON array of
one object, so index [0] before the key
(pae[0]['predicted_aligned_error']). Visualization recipe in
code_examples.md §3.
4. Bulk Data Access via Google Cloud
For proteome-scale work, pull from gs://public-datasets-deepmind-alphafold-v4/
with gsutil, or query bigquery-public-data.deepmind_alphafold.metadata to
filter by organism/confidence. The species-download helper validates the taxonomy
ID and uses list-form subprocess.run (never shell=True). See
code_examples.md §4 and references/api_reference.md (Google Cloud / BigQuery).
5. Parsing and Analyzing Structures
Parse mmCIF with Bio.PDB.MMCIFParser; pLDDT is stored in the B-factor column
(residue['CA'].get_bfactor()). Contact-map and B-factor extraction recipes in
code_examples.md §5.
6. Batch Processing Multiple Proteins
Loop accessions → predictions → confidence stats → summary DataFrame. Full
example in code_examples.md §6.
Installation and Setup
uv pip install biopython requests
uv pip install numpy matplotlib pandas scipy
uv pip install google-cloud-bigquery gsutil
3D-Beacons alternative: AlphaFold is also reachable via the 3D-Beacons
federated API (https://www.ebi.ac.uk/pdbe/pdbe-kb/3dbeacons/api/uniprot/summary/{id}.json),
filtering structures where provider == 'AlphaFold DB'. Recipe in
code_examples.md (3D-Beacons section).
Common Use Cases
Structural Proteomics
- Download complete proteome predictions for analysis
- Identify high-confidence structural regions across proteins
- Compare predicted structures with experimental data
- Build structural models for protein families
Drug Discovery
- Retrieve target protein structures for docking studies
- Analyze binding site conformations
- Identify druggable pockets in predicted structures
- Compare structures across homologs
Protein Engineering
- Identify stable/unstable regions using pLDDT
- Design mutations in high-confidence regions
- Analyze domain architectures using PAE
- Model protein variants and mutations
Evolutionary Studies
- Compare ortholog structures across species
- Analyze conservation of structural features
- Study domain evolution patterns
- Identify functionally important regions
Key Concepts
UniProt Accession: Primary identifier for proteins (e.g., "P00520"). Required for querying AlphaFold DB.
AlphaFold ID: Internal identifier format: AF-[UniProt accession]-F[fragment number] (e.g., "AF-P00520-F1").
pLDDT (predicted Local Distance Difference Test): Per-residue confidence metric (0-100). Higher values indicate more confident predictions.
PAE (Predicted Aligned Error): Matrix indicating confidence in relative positions between residue pairs. Low values (<5 Å) suggest confident relative positioning.
Database Version: The REST API currently serves v6 (the response reports latestVersion / allVersions); the bulk GCS/BigQuery datasets lag at v4. File URLs include a version suffix (e.g., model_v6.cif) — read them from the prediction response rather than hardcoding the suffix.
Fragment Number: Large proteins may be split into fragments. Fragment number appears in AlphaFold ID (e.g., F1, F2).
Confidence Interpretation Guidelines
pLDDT Thresholds:
- >90: Very high confidence - suitable for detailed analysis
- 70-90: High confidence - generally reliable backbone structure
- 50-70: Low confidence - use with caution, flexible regions
- <50: Very low confidence - likely disordered or unreliable
PAE Guidelines:
- <5 Å: Confident relative positioning of domains
- 5-10 Å: Moderate confidence in arrangement
- >15 Å: Uncertain relative positions, domains may be mobile
Resources
references/code_examples.md
Worked, copy-paste Python recipes for every Core Capability: prediction
retrieval (Biopython / REST / UniProt mapping), file downloads, pLDDT + PAE
analysis, GCP/BigQuery bulk access, mmCIF parsing, batch processing, and the
3D-Beacons alternative.
Load this when you need runnable code.
references/api_reference.md
Comprehensive API documentation covering:
- Complete REST API endpoint specifications
- File format details and data schemas
- Google Cloud dataset structure and access patterns
- Advanced query examples and batch processing strategies
- Rate limiting, caching, and best practices
- Troubleshooting common issues
Consult this reference for detailed API information, bulk download strategies, or when working with large-scale datasets.
Important Notes
Data Usage and Attribution
- AlphaFold DB is freely available under CC-BY-4.0 license
- Cite: Jumper et al. (2021) Nature and Varadi et al. (2022) Nucleic Acids Research
- Predictions are computational models, not experimental structures
- Always assess confidence metrics before downstream analysis
Version Management
- REST API serves v6 (
latestVersion); bulk GCS/BigQuery datasets lag at v4
- Read file URLs from the
/prediction response — never hardcode the _v{N} suffix
- Old
_v4 file URLs now 404; superseded versions are removed from /files
- Track which version a downloaded result came from
Data Quality Considerations
- High pLDDT doesn't guarantee functional accuracy
- Low confidence regions may be disordered in vivo
- PAE indicates relative domain confidence, not absolute positioning
- Predictions lack ligands, post-translational modifications, and cofactors
- Multi-chain complexes are not predicted (single chains only)
Performance Tips
- Use Biopython for simple single-protein access
- Use Google Cloud for bulk downloads (much faster than individual files)
- Cache downloaded files locally to avoid repeated downloads
- BigQuery free tier: 1 TB processed data per month
- Consider network bandwidth for large-scale downloads
Additional Resources
Scripts
scripts/query_alphafold.py — runnable helper for the AlphaFold REST API (no key):
python scripts/query_alphafold.py prediction P00520
python scripts/query_alphafold.py confidence P00520 --summary
python scripts/query_alphafold.py download P00520 --fmt cif -o ./structures
