{
  "skill": "alterlab-alphafold-db",
  "evals": [
    {
      "id": "predicted-structure-by-uniprot",
      "prompt": "I have UniProt accession P00520 and there's no experimental PDB structure for it. Can you pull the AlphaFold predicted 3D structure and download the mmCIF coordinate file?",
      "expected_output": "Invokes alterlab-alphafold-db. Retrieves the AlphaFold prediction for P00520 (e.g. via the prediction API endpoint or Biopython's alphafold_db.get_predictions), selects the canonical record (uniprotAccession == P00520, not an isoform) and its model ID (modelEntityId AF-P00520-F1), and downloads the mmCIF model coordinate file using the version-stamped cifUrl from the prediction response (currently model_v6.cif) rather than a hardcoded _v4 URL. Notes that this is an AI prediction, not an experimental structure.",
      "assertions": [
        { "type": "should_trigger", "value": true },
        { "type": "output_contains", "value": "AlphaFold" },
        { "type": "behavior", "value": "Resolves the UniProt accession to an AlphaFold prediction and downloads the mmCIF/PDB model file rather than searching for an experimental structure." }
      ]
    },
    {
      "id": "confidence-plddt-pae",
      "prompt": "For the AlphaFold model AF-P04637-F1, how reliable is the prediction? I want the per-residue pLDDT scores and the PAE matrix so I can judge which domains are confidently placed.",
      "expected_output": "Invokes alterlab-alphafold-db. Fetches the per-residue confidence JSON (pLDDT, from plddtDocUrl) and the PAE JSON (from paeDocUrl) for AF-P04637-F1 — using the version-stamped URLs from the prediction response, not hardcoded _v4 URLs. Interprets pLDDT bands (>90 very high, 70-90 high, 50-70 low, <50 very low) and PAE thresholds (<5 Å confident relative positioning, >15 Å uncertain domain arrangement), and explains which regions/domains are reliable.",
      "assertions": [
        { "type": "should_trigger", "value": true },
        { "type": "output_contains", "value": "pLDDT" },
        { "type": "behavior", "value": "Distinguishes pLDDT (per-residue confidence) from PAE (relative domain confidence) and applies the documented thresholds." }
      ]
    },
    {
      "id": "bulk-proteome-download",
      "prompt": "I need every AlphaFold predicted structure for the entire human proteome for a large-scale structural analysis. What's the fastest way to grab them all in bulk?",
      "expected_output": "Invokes alterlab-alphafold-db. Recommends a bulk archive rather than fetching files one at a time: the current v6 human proteome tar from the EMBL-EBI FTP (https://ftp.ebi.ac.uk/pub/databases/alphafold/latest/UP000005640_9606_HUMAN_v6.tar, listed in download_metadata.json), or the per-taxon Google Cloud Storage archives (gs://public-datasets-deepmind-alphafold-v4/proteomes/, taxonomy ID 9606) via gsutil, noting that the GCS/BigQuery copies are still v4. May mention BigQuery metadata for filtering high-confidence entries.",
      "assertions": [
        { "type": "should_trigger", "value": true },
        { "type": "behavior", "value": "Points to a bulk proteome archive (EMBL-EBI FTP v6 tar or Google Cloud/gsutil by taxonomy ID) rather than per-protein API calls." }
      ]
    },
    {
      "id": "batch-plddt-stats",
      "prompt": "I have a list of UniProt IDs (P00520, P12931, P04637). For each one, download the AlphaFold model and give me the average pLDDT and the fraction of residues above 90 confidence.",
      "expected_output": "Invokes alterlab-alphafold-db. Loops over the UniProt IDs, retrieves each prediction and its per-residue confidence JSON (via plddtDocUrl, or reads pLDDT from the mmCIF B-factor column), and computes average pLDDT and the high-confidence (>90) fraction per protein, returning a per-protein summary table.",
      "assertions": [
        { "type": "should_trigger", "value": true },
        { "type": "behavior", "value": "Iterates over multiple UniProt accessions and reports per-protein confidence statistics (mean pLDDT, high-confidence fraction)." }
      ]
    },
    {
      "id": "near-miss-pdb",
      "prompt": "I need the actual experimental X-ray crystal structure for hemoglobin, PDB ID 1HHO — download the coordinate file from the Protein Data Bank, not a model.",
      "expected_output": "Does NOT invoke this skill; defers to alterlab-pdb. The user explicitly wants an experimental, deposited X-ray structure by PDB ID from the Protein Data Bank, not an AI-predicted AlphaFold model.",
      "assertions": [
        { "type": "should_not_trigger", "value": true },
        { "type": "output_contains", "value": "alterlab-pdb" }
      ]
    },
    {
      "id": "near-miss-uniprot",
      "prompt": "Just give me the amino acid FASTA sequence for UniProt P00520 — I only need the sequence, no structure.",
      "expected_output": "Does NOT invoke this skill; defers to alterlab-uniprot. The user wants only the protein FASTA sequence from UniProt's REST API, with no structural prediction, coordinates, or confidence metrics involved.",
      "assertions": [
        { "type": "should_not_trigger", "value": true },
        { "type": "output_contains", "value": "alterlab-uniprot" }
      ]
    },
    {
      "id": "near-miss-fold-new-sequence",
      "prompt": "I designed a new 120-residue binder sequence that isn't in UniProt. Fold it together with its target as a complex and give me ipTM and PAE so I can rank designs.",
      "expected_output": "Does NOT invoke this skill; defers to alterlab-alphafold. The sequence is novel (no UniProt accession), so there is no precomputed AlphaFold DB entry to look up — the user needs to run a new ColabFold / AlphaFold2-Multimer prediction and read ipTM/PAE from that run.",
      "assertions": [
        { "type": "should_not_trigger", "value": true },
        { "type": "output_contains", "value": "alterlab-alphafold" }
      ]
    }
  ]
}

# AlphaFold Database API Reference

This document provides comprehensive technical documentation for programmatic access to the AlphaFold Protein Structure Database.

## Table of Contents

1. [REST API Endpoints](#rest-api-endpoints)
2. [File Access Patterns](#file-access-patterns)
3. [Data Schemas](#data-schemas)
4. [Bulk Downloads (FTP v6)](#bulk-downloads-ftp-v6)
5. [Google Cloud Access](#google-cloud-access)
6. [BigQuery Schema](#bigquery-schema)
7. [Best Practices](#best-practices)
8. [Error Handling](#error-handling)
9. [Rate Limiting](#rate-limiting)

---

## REST API Endpoints

### Base URL

```
https://alphafold.ebi.ac.uk/api/
```

### 1. Get Predictions by UniProt Accession or Model ID

**Endpoint:** `/prediction/{qualifier}`

**Method:** GET

**Description:** Retrieve AlphaFold prediction metadata for a UniProt accession or a
model ID. Returns a JSON **list** with one record per model: the canonical sequence,
UniProt isoforms (`P00520-2`, …) and, for some accessions, third-party models (e.g.
ColabFold models with `providerId` other than `GDM`).

**Parameters:**
- `qualifier` (path, required): UniProt accession (e.g. `P00520`) or model ID
  (e.g. `AF-P00520-F1`, `AF-0000000365776990`)
- `sequence_checksum` (query, optional): MD5 checksum of the UniProt sequence
- `include_complexes` (query, optional, default `false`): also return complex models

**Example Request:**
```bash
curl https://alphafold.ebi.ac.uk/api/prediction/P00520
```

**Example Response** (canonical record, abridged; live response observed 2026-09):
```json
[
  {
    "modelEntityId": "AF-P00520-F1",
    "entryId": "AF-P00520-F1",
    "providerId": "GDM",
    "toolUsed": "AlphaFold Monomer v2.0 pipeline",
    "entityType": "protein",
    "isComplex": false,
    "chainId": "A",
    "gene": "Abl1",
    "uniprotAccession": "P00520",
    "uniprotId": "ABL1_MOUSE",
    "uniprotDescription": "Tyrosine-protein kinase ABL1",
    "taxId": 10090,
    "organismScientificName": "Mus musculus",
    "sequenceStart": 1,
    "sequenceEnd": 1123,
    "sequence": "MLEIC...",
    "globalMetricValue": 63.44,
    "fractionPlddtVeryHigh": 0.374,
    "modelCreatedDate": "2025-08-01T00:00:00Z",
    "latestVersion": 6,
    "allVersions": [1, 2, 3, 4, 5, 6],
    "cifUrl": "https://alphafold.ebi.ac.uk/files/AF-P00520-F1-model_v6.cif",
    "bcifUrl": "https://alphafold.ebi.ac.uk/files/AF-P00520-F1-model_v6.bcif",
    "pdbUrl": "https://alphafold.ebi.ac.uk/files/AF-P00520-F1-model_v6.pdb",
    "plddtDocUrl": "https://alphafold.ebi.ac.uk/files/AF-P00520-F1-confidence_v6.json",
    "paeDocUrl": "https://alphafold.ebi.ac.uk/files/AF-P00520-F1-predicted_aligned_error_v6.json",
    "msaUrl": "https://alphafold.ebi.ac.uk/files/msa/AF-P00520-F1-msa_v6.a3m"
  },
  { "modelEntityId": "AF-P00520-4-F1", "uniprotAccession": "P00520-4", "...": "..." }
]
```

> **Always read the file URLs from this response** rather than hand-building a
> `_v{N}` suffix: the version moves (now v6) and old `_v4` file URLs return 404.
> **Select the record whose `uniprotAccession` equals your query** — the list also
> contains isoforms, and its order is not documented.

**Response Fields** (selected — the live response includes more; the full schema is
`NewEntrySummary` in https://alphafold.ebi.ac.uk/api/openapi.json):
- `modelEntityId`: model identifier (format `AF-{uniprot}-F{fragment}` for DeepMind monomers)
- `providerId` / `toolUsed`: who produced the model and with what pipeline
- `isComplex`, `chainId`, `entityType`: complex flag and chain/entity info
- `gene`, `uniprotAccession`, `uniprotId`, `uniprotDescription`: UniProt identity
- `taxId`, `organismScientificName`: organism
- `sequenceStart` / `sequenceEnd`: residue range covered; `sequence`: modelled sequence
- `globalMetricValue`: mean pLDDT; `fractionPlddtVeryHigh|Confident|Low|VeryLow`: pLDDT bands
- `modelCreatedDate`: prediction date
- `latestVersion` / `allVersions`: version numbers for this model
- `cifUrl` / `bcifUrl` / `pdbUrl`: structure file download URLs
- `plddtDocUrl`: per-residue confidence (pLDDT) JSON URL
- `paeDocUrl`: PAE data JSON URL
- `msaUrl`: input multiple sequence alignment (A3M), new in v6

**Renamed / deprecated fields (v6 API migration).** EMBL-EBI announced a 9-month
dual-support period ending **2026-06-25**; legacy names may still appear in responses
but should not be relied on:

| Legacy field | Current field |
|--------------|---------------|
| `entryId` | `modelEntityId` |
| `uniprotStart` / `uniprotEnd` | `sequenceStart` / `sequenceEnd` |
| `uniprotSequence` | `sequence` |
| `isReviewed` | `isUniProtReviewed` |
| `isReferenceProteome` | `isUniProtReferenceProteome` |
| `paeImageUrl` | removed — render the PAE yourself from `paeDocUrl` |

Source: https://www.ebi.ac.uk/pdbe/news/breaking-changes-afdb-predictions-api

### Other endpoints (from the OpenAPI spec)

| Endpoint | Purpose |
|----------|---------|
| `GET /complex/{qualifier}` | Complex models for an accession or model ID, with interface metrics (`complexPredictionAccuracy_ipTM`, `_ipSAE`, `_pDockQ`, `_pDockQ2`, `_LIS`), `oligomericState`, `assemblyType`, `complexComposition` |
| `GET /uniprot/summary/{qualifier}.json` | 3D-Beacons-style summary of models for a UniProt residue range |
| `GET /sequence/summary?id=...&type=sequence` | Look up models by sequence or checksum |
| `GET /annotations/{qualifier}.json?type=MUTAGEN` | Residue-level AlphaMissense annotations for a UniProt accession |

### 2. 3D-Beacons Integration

AlphaFold is integrated into the 3D-Beacons network for federated structure access.

**Endpoint:** `https://www.ebi.ac.uk/pdbe/pdbe-kb/3dbeacons/api/uniprot/summary/{uniprot_id}.json`

**Example:**
```python
import requests

uniprot_id = "P00520"
url = f"https://www.ebi.ac.uk/pdbe/pdbe-kb/3dbeacons/api/uniprot/summary/{uniprot_id}.json"
response = requests.get(url)
data = response.json()

# Each entry is {"summary": {...}}; filter for AlphaFold structures
alphafold_structures = [
    s['summary'] for s in data['structures']
    if s['summary']['provider'] == 'AlphaFold DB'
]
```

---

## File Access Patterns

### Direct File Downloads

All AlphaFold files are accessible via direct URLs without authentication.

**URL Pattern:**
```
https://alphafold.ebi.ac.uk/files/{alphafold_id}-{file_type}_{version}.{extension}
```

**Components:**
- `{alphafold_id}`: Entry identifier (e.g., "AF-P00520-F1")
- `{file_type}`: Type of file (see below)
- `{version}`: Database version (currently "v6"). **Prefer the exact URLs from the
  `/prediction/{uniprot}` response over hand-building this** — old `_v4` URLs 404.
- `{extension}`: File format extension

### Available File Types

#### 1. Model Coordinates

**mmCIF Format (Recommended):**
```
https://alphafold.ebi.ac.uk/files/AF-P00520-F1-model_v6.cif
```
- Standard crystallographic format
- Contains full metadata
- Supports large structures
- File size: Variable (100KB - 10MB typical)

**Binary CIF Format:**
```
https://alphafold.ebi.ac.uk/files/AF-P00520-F1-model_v6.bcif
```
- Compressed binary version of mmCIF
- Smaller file size (~70% reduction)
- Faster parsing
- Requires specialized parser

**PDB Format (Legacy):**
```
https://alphafold.ebi.ac.uk/files/AF-P00520-F1-model_v6.pdb
```
- Traditional PDB text format
- Limited to 99,999 atoms
- Widely supported by older tools
- File size: Similar to mmCIF

#### 2. Confidence Metrics

**Per-Residue Confidence (JSON):**
```
https://alphafold.ebi.ac.uk/files/AF-P00520-F1-confidence_v6.json
```

**Structure:**
```json
{
  "residueNumber": [1, 2, 3, ...],
  "confidenceScore": [87.5, 91.2, 93.8, ...],
  "confidenceCategory": ["high", "very_high", "very_high", ...]
}
```

**Fields:**
- `residueNumber`: 1-based residue index, one per residue
- `confidenceScore`: Array of pLDDT values (0-100) for each residue
- `confidenceCategory`: Categorical classification (very_low, low, high, very_high)

#### 3. Predicted Aligned Error (JSON)

```
https://alphafold.ebi.ac.uk/files/AF-P00520-F1-predicted_aligned_error_v6.json
```

**Structure:** a single-element JSON array wrapping one object:
```json
[
  {
    "predicted_aligned_error": [[0, 2.3, 4.5, ...], [2.3, 0, 3.1, ...], ...],
    "max_predicted_aligned_error": 31.75
  }
]
```

**Fields:**
- `predicted_aligned_error`: N×N matrix of PAE values in Ångströms
- `max_predicted_aligned_error`: Maximum PAE value in the matrix

> The response is wrapped in a one-element array, so index `[0]` before the key:
> `pae[0]['predicted_aligned_error']`.

#### 4. PAE Visualization (PNG)

```
https://alphafold.ebi.ac.uk/files/AF-P00520-F1-predicted_aligned_error_v6.png
```
- Pre-rendered PAE heatmap
- Useful for quick visual assessment
- Resolution: Variable based on protein size

### Batch Download Strategy

For downloading multiple files efficiently, use concurrent downloads with proper error handling and rate limiting to respect server resources.

---

## Data Schemas

### Coordinate File (mmCIF) Schema

AlphaFold mmCIF files contain:

**Key Data Categories:**
- `_entry`: Entry-level metadata
- `_struct`: Structure title and description
- `_entity`: Molecular entity information
- `_atom_site`: Atomic coordinates and properties
- `_pdbx_struct_assembly`: Biological assembly info

**Important Fields in `_atom_site`:**
- `group_PDB`: "ATOM" for all records
- `id`: Atom serial number
- `label_atom_id`: Atom name (e.g., "CA", "N", "C")
- `label_comp_id`: Residue name (e.g., "ALA", "GLY")
- `label_seq_id`: Residue sequence number
- `Cartn_x/y/z`: Cartesian coordinates (Ångströms)
- `B_iso_or_equiv`: B-factor (contains pLDDT score)

**pLDDT in B-factor Column:**
AlphaFold stores per-residue confidence (pLDDT) in the B-factor field. This allows standard structure viewers to color by confidence automatically.

### Confidence JSON Schema

```json
{
  "residueNumber": [1, 2, 3, ...],   // 1-based residue index, one per residue
  "confidenceScore": [
    87.5,   // Residue 1 pLDDT
    91.2,   // Residue 2 pLDDT
    93.8    // Residue 3 pLDDT
    // ... one value per residue
  ],
  "confidenceCategory": [
    "high",      // Residue 1 category
    "very_high", // Residue 2 category
    "very_high"  // Residue 3 category
    // ... one category per residue
  ]
}
```

**Confidence Categories:**
- `very_high`: pLDDT > 90
- `high`: 70 < pLDDT ≤ 90
- `low`: 50 < pLDDT ≤ 70
- `very_low`: pLDDT ≤ 50

### PAE JSON Schema

```json
[
  {
    "predicted_aligned_error": [
      [0.0, 2.3, 4.5, ...],     // PAE from residue 1 to all residues
      [2.3, 0.0, 3.1, ...],     // PAE from residue 2 to all residues
      [4.5, 3.1, 0.0, ...]      // PAE from residue 3 to all residues
      // ... N×N matrix for N residues
    ],
    "max_predicted_aligned_error": 31.75
  }
]
```

**Interpretation** (with `pae = pae[0]['predicted_aligned_error']`):
- `pae[i][j]`: Expected position error (Ångströms) of residue j if the predicted and true structures were aligned on residue i
- Lower values indicate more confident relative positioning
- Diagonal is always 0 (residue aligned to itself)
- Matrix is not symmetric: pae[i][j] ≠ pae[j][i]

---

## Bulk Downloads (FTP v6)

EMBL-EBI publishes the current (v6) bulk archives over HTTPS/FTP:

```
https://ftp.ebi.ac.uk/pub/databases/alphafold/
├── latest/                  # v6 tars: 16 model-organism + 30 global-health proteomes,
│                            #   swissprot_cif_v6.tar / swissprot_pdb_v6.tar
├── download_metadata.json   # index: archive_name, species, reference_proteome, size_bytes, type
├── accession_ids.csv        # every accession / model ID in the release
├── sequences.fasta          # all modelled sequences
├── CHANGELOG.txt            # release history
├── v1/ … v6/                # frozen per-version archives
└── collaborations/nvda/     # bulk complex predictions (incl. lower-confidence homo/heterodimers)
```

```bash
# Human reference proteome, v6 (UP000005640, ~23.6k models)
curl -O https://ftp.ebi.ac.uk/pub/databases/alphafold/latest/UP000005640_9606_HUMAN_v6.tar
```

Pick archive names from `download_metadata.json` rather than guessing them. For taxa
that are not in `latest/`, use the per-taxon archives in the Google Cloud bucket
below (v4).

---

## Google Cloud Access

AlphaFold DB is hosted on Google Cloud Platform for bulk access.

> **Note:** The bulk GCS bucket and BigQuery dataset are versioned independently
> of the REST API and currently lag at **v4** (bucket `...-alphafold-v4`, proteome
> archives `..._v4.tar`). The per-protein REST API and the FTP `latest/` directory
> serve **v6**. Use the v4 paths below for GCS access; do not "upgrade" them to v6
> (no `...-alphafold-v6` bucket exists as of 2026-09).

### Cloud Storage Bucket

**Bucket:** `gs://public-datasets-deepmind-alphafold-v4`

**Directory Structure:**
```
gs://public-datasets-deepmind-alphafold-v4/
├── accession_ids.csv              # Index of all entries (13.5 GB)
├── sequences.fasta                # All protein sequences (16.5 GB)
└── proteomes/                     # Grouped by species (1M+ archives)
```

### Installing gsutil

```bash
# Using uv (or pip)
uv pip install gsutil
```

Or install the Google Cloud SDK (which bundles `gsutil`) by following the
official instructions at https://cloud.google.com/sdk/docs/install. Prefer a
package manager or the versioned installer archive, for example:

```bash
# macOS (Homebrew)
brew install --cask google-cloud-sdk

# Debian/Ubuntu (APT repository) — see the install page for the full steps
sudo apt-get install google-cloud-cli
```

> **Caution:** Avoid `curl https://sdk.cloud.google.com | bash` — piping a
> remote script straight into a shell executes unreviewed code. Download the
> installer or use a package manager so you can verify what runs.

### Downloading Proteomes

**By Taxonomy ID:**

```bash
# Download all archives for a species
TAX_ID=9606  # Human
gsutil -m cp gs://public-datasets-deepmind-alphafold-v4/proteomes/proteome-tax_id-${TAX_ID}-*_v4.tar .
```

---

## BigQuery Schema

AlphaFold metadata is available in BigQuery for SQL-based queries.

**Dataset:** `bigquery-public-data.deepmind_alphafold`
**Table:** `metadata`

### Key Fields

| Field | Type | Description |
|-------|------|-------------|
| `entryId` | STRING | AlphaFold entry ID |
| `uniprotAccession` | STRING | UniProt accession |
| `gene` | STRING | Gene symbol |
| `organismScientificName` | STRING | Species scientific name |
| `taxId` | INTEGER | NCBI taxonomy ID |
| `globalMetricValue` | FLOAT | Overall quality metric |
| `fractionPlddtVeryHigh` | FLOAT | Fraction with pLDDT ≥ 90 |
| `isReviewed` | BOOLEAN | Swiss-Prot reviewed status |
| `sequenceLength` | INTEGER | Protein sequence length |

### Example Query

```sql
SELECT
  entryId,
  uniprotAccession,
  gene,
  fractionPlddtVeryHigh
FROM `bigquery-public-data.deepmind_alphafold.metadata`
WHERE
  taxId = 9606  -- Homo sapiens
  AND fractionPlddtVeryHigh > 0.8
  AND isReviewed = TRUE
ORDER BY fractionPlddtVeryHigh DESC
LIMIT 100;
```

---

## Best Practices

### 1. Caching Strategy

Always cache downloaded files locally to avoid repeated downloads.

### 2. Error Handling

Implement robust error handling for API requests with retry logic for transient failures.

### 3. Bulk Processing

For processing many proteins, use concurrent downloads with appropriate rate limiting.

### 4. Version Management

Read file URLs from the `/prediction` response rather than hardcoding a version
suffix. The REST API and FTP `latest/` currently serve **v6**; the GCS/BigQuery
datasets lag at **v4**. Track which version a result came from in your code.

---

## Error Handling

### Common HTTP Status Codes

| Code | Meaning | Action |
|------|---------|--------|
| 200 | Success | Process response normally |
| 404 | Not Found | No AlphaFold prediction for this UniProt ID |
| 429 | Too Many Requests | Implement rate limiting and retry with backoff |
| 500 | Server Error | Retry with exponential backoff |
| 503 | Service Unavailable | Wait and retry later |

---

## Rate Limiting

### Recommendations

- Limit to **10 concurrent requests** maximum
- Add **100-200ms delay** between sequential requests
- Use the FTP archives or Google Cloud for bulk downloads instead of the REST API
- Cache all downloaded data locally

---

## Additional Resources

- **AlphaFold GitHub:** https://github.com/google-deepmind/alphafold
- **Google Cloud Documentation:** https://console.cloud.google.com/marketplace/product/bigquery-public-data/deepmind-alphafold
- **3D-Beacons Documentation:** https://www.ebi.ac.uk/pdbe/pdbe-kb/3dbeacons/docs
- **Biopython Tutorial:** https://biopython.org/docs/latest/api/Bio.PDB.alphafold_db.html

## Version History

The `/prediction` response reports `latestVersion` and `allVersions`; treat those
as the source of truth rather than this list.

Dates below are from the FTP `CHANGELOG.txt` and the EMBL-EBI release notes:

- **v1** (2021-07): Initial release — 21 model-organism proteomes (incl. human), ~365K structures
- **v2** (2021-12 / 2022-01): Added Swiss-Prot, then global-health organisms — ~1M structures
- **v3** (2022-07): UniProt 2021_04 — expanded to ~214M structures; ModelCIF-compliant files
- **v4** (2022-11): Improved accuracy for ~4.4% of predictions; still the version in the
  GCS bucket and BigQuery dataset
- **v6** (2025-09/10): Synced to UniProt 2025_03 — 241,070,489 structures including
  40,054 isoforms; per-entry MSAs (`msaUrl`); API field renames (see above). No
  separate v5 entry appears in the changelog.
- **Complexes** (2026-03, heterodimers extended 2026-05): ~1.7M high-confidence homodimers
  and ~80k high-confidence heterodimers in the web/API, lower-confidence sets bulk-only

## Citation

When using AlphaFold DB in publications, cite:

1. Jumper, J. et al. Highly accurate protein structure prediction with AlphaFold. Nature 596, 583–589 (2021).
2. Varadi, M. et al. AlphaFold Protein Structure Database in 2024: providing structure coverage for over 214 million protein sequences. Nucleic Acids Res. 52, D368–D375 (2024). https://doi.org/10.1093/nar/gkad1011
3. Bertoni, D. et al. AlphaFold Protein Structure Database 2025: a redesigned interface and updated structural coverage. Nucleic Acids Res. 54, D358–D362 (2026). https://doi.org/10.1093/nar/gkaf1226 (cite for v6 data)

# AlphaFold DB — Worked Code Examples

Copy-paste Python recipes for the common AlphaFold DB tasks. For REST endpoint
specs, file schemas, GCP dataset layout, rate limiting, and error handling, see
`api_reference.md`.

## 1. Searching and Retrieving Predictions

### Using Biopython (Recommended)

The Biopython library provides the simplest interface for retrieving AlphaFold structures:

```python
from Bio.PDB import alphafold_db

# Get all predictions for a UniProt accession
predictions = list(alphafold_db.get_predictions("P00520"))

# Download structure file (mmCIF format)
for prediction in predictions:
    cif_file = alphafold_db.download_cif_for(prediction, directory="./structures")
    print(f"Downloaded: {cif_file}")

# Get Structure objects directly
from Bio.PDB import MMCIFParser
structures = list(alphafold_db.get_structural_models_for("P00520"))
```

### Direct API Access

Query predictions using REST endpoints:

```python
import requests

def get_canonical_prediction(uniprot_id):
    """Return the prediction record for exactly this accession.

    /prediction/{id} returns a list that also contains isoform records
    (e.g. P00520-2) and possibly third-party models, in no documented order,
    so match on uniprotAccession instead of taking [0].
    """
    r = requests.get(f"https://alphafold.ebi.ac.uk/api/prediction/{uniprot_id}", timeout=30)
    r.raise_for_status()
    records = r.json()
    for rec in records:
        if rec.get("uniprotAccession") == uniprot_id:
            return rec
    return records[0] if records else None

rec = get_canonical_prediction("P00520")
# modelEntityId is the current field; entryId is the pre-v6 legacy alias.
alphafold_id = rec.get("modelEntityId") or rec.get("entryId")
print(f"AlphaFold model ID: {alphafold_id}")  # AF-P00520-F1
```

### Using UniProt to Find Accessions

Search UniProt to find protein accessions first:

```python
import requests, time

def get_uniprot_ids(query, from_db='PDB', to_db='UniProtKB'):
    """Map IDs to UniProt accessions via the current REST API.

    from_db/to_db must be current DB names, e.g. 'PDB', 'Gene_Name',
    'UniProtKB_AC-ID', 'UniProtKB'.
    Valid values: https://rest.uniprot.org/configure/idmapping/fields
    """
    base = 'https://rest.uniprot.org'
    # 1) submit job
    r = requests.post(f'{base}/idmapping/run',
                      data={'from': from_db, 'to': to_db, 'ids': query})
    r.raise_for_status()
    job_id = r.json()['jobId']
    # 2) poll status
    while True:
        s = requests.get(f'{base}/idmapping/status/{job_id}').json()
        if s.get('jobStatus') in (None, 'FINISHED') or 'results' in s:
            break
        if s.get('jobStatus') in ('ERROR',):
            raise RuntimeError(s)
        time.sleep(1)
    # 3) fetch results
    res = requests.get(f'{base}/idmapping/results/{job_id}').json()
    return [m['to'] for m in res.get('results', [])]

# Example: Find UniProt accessions for a gene name
protein_ids = get_uniprot_ids("HBB", from_db="Gene_Name", to_db="UniProtKB")
```

## 2. Downloading Structure Files

AlphaFold provides multiple file formats for each prediction. **Read the file
URLs from the prediction metadata rather than hand-building a `_v{N}` suffix** —
the DB version advances (currently v6) and old hardcoded `_v4` URLs now 404. The
prediction record carries the exact, version-stamped URLs:

- `cifUrl` / `pdbUrl` / `bcifUrl` — model coordinates (mmCIF / PDB / binary CIF)
- `plddtDocUrl` — per-residue pLDDT confidence JSON (0-100)
- `paeDocUrl` — Predicted Aligned Error JSON

```python
import requests

# Resolve the current file URLs from the prediction metadata
# (get_canonical_prediction from §1 picks the canonical, non-isoform record).
rec = get_canonical_prediction("P00520")
alphafold_id = rec["modelEntityId"]  # e.g. "AF-P00520-F1"

# Model coordinates (mmCIF) — write bytes, never decode/re-encode text.
r = requests.get(rec["cifUrl"])
with open(f"{alphafold_id}.cif", "wb") as f:
    f.write(r.content)

# Confidence scores (JSON)
confidence_data = requests.get(rec["plddtDocUrl"]).json()

# Predicted Aligned Error (JSON)
pae_data = requests.get(rec["paeDocUrl"]).json()
```

**PDB Format (Alternative):**

```python
# Download as PDB format instead of mmCIF
r = requests.get(rec["pdbUrl"])
with open(f"{alphafold_id}.pdb", "wb") as f:
    f.write(r.content)
```

## 3. Working with Confidence Metrics

AlphaFold predictions include confidence estimates critical for interpretation:

**pLDDT (per-residue confidence):**

```python
import requests

# Resolve the confidence-JSON URL from the prediction metadata (version-stamped).
rec = get_canonical_prediction("P00520")
confidence = requests.get(rec["plddtDocUrl"]).json()

# Extract pLDDT scores (keys: residueNumber, confidenceScore, confidenceCategory)
plddt_scores = confidence['confidenceScore']

# Interpret confidence levels
# pLDDT > 90: Very high confidence
# pLDDT 70-90: High confidence
# pLDDT 50-70: Low confidence
# pLDDT < 50: Very low confidence

high_confidence_residues = [i for i, score in enumerate(plddt_scores) if score > 90]
print(f"High confidence residues: {len(high_confidence_residues)}/{len(plddt_scores)}")
```

**PAE (Predicted Aligned Error):**

PAE indicates confidence in relative domain positions:

```python
import numpy as np
import matplotlib.pyplot as plt

# Load PAE matrix (rec from the prediction metadata, as above)
pae = requests.get(rec["paeDocUrl"]).json()

# Visualize PAE matrix.
# The PAE JSON is a single-element array of one object with keys
# 'predicted_aligned_error' (the N×N matrix) and 'max_predicted_aligned_error',
# so index [0] before the key.
pae_matrix = np.array(pae[0]['predicted_aligned_error'])
plt.figure(figsize=(10, 8))
plt.imshow(pae_matrix, cmap='viridis_r', vmin=0, vmax=30)
plt.colorbar(label='PAE (Å)')
plt.title(f'Predicted Aligned Error: {alphafold_id}')
plt.xlabel('Residue')
plt.ylabel('Residue')
plt.savefig(f'{alphafold_id}_pae.png', dpi=300, bbox_inches='tight')

# Low PAE values (<5 Å) indicate confident relative positioning
# High PAE values (>15 Å) suggest uncertain domain arrangements
```

## 4. Bulk Data Access

**EMBL-EBI FTP (current v6 release)** — one tar per model-organism or global-health
proteome, plus Swiss-Prot:

```bash
# Index of archives (archive_name, species, reference_proteome, size_bytes, type)
curl -s https://ftp.ebi.ac.uk/pub/databases/alphafold/download_metadata.json -o download_metadata.json

# Human reference proteome, v6
curl -O https://ftp.ebi.ac.uk/pub/databases/alphafold/latest/UP000005640_9606_HUMAN_v6.tar
```

For any other taxon, fall back to the per-taxon archives on Google Cloud (still v4):

**Google Cloud Storage (v4):**

```bash
# Install gsutil
uv pip install gsutil

# List available data
gsutil ls gs://public-datasets-deepmind-alphafold-v4/

# Download entire proteomes (by taxonomy ID)
gsutil -m cp gs://public-datasets-deepmind-alphafold-v4/proteomes/proteome-tax_id-9606-*.tar .

# Download specific files
gsutil cp gs://public-datasets-deepmind-alphafold-v4/accession_ids.csv .
```

**BigQuery Metadata Access:**

```python
from google.cloud import bigquery

# Initialize client
client = bigquery.Client()

# Query metadata
query = """
SELECT
  entryId,
  uniprotAccession,
  organismScientificName,
  globalMetricValue,
  fractionPlddtVeryHigh
FROM `bigquery-public-data.deepmind_alphafold.metadata`
WHERE organismScientificName = 'Homo sapiens'
  AND fractionPlddtVeryHigh > 0.8
LIMIT 100
"""

results = client.query(query).to_dataframe()
print(f"Found {len(results)} high-confidence human proteins")
```

**Download by Species:**

> ⚠️ **Security Note**: Always invoke `gsutil` via `subprocess.run()` with a list
> of arguments (never `shell=True` with an interpolated string), and validate the
> taxonomy ID is an integer. Both guard against command injection. See
> [Python subprocess security](https://docs.python.org/3/library/subprocess.html#security-considerations).

```python
import os
import subprocess

def download_proteome(taxonomy_id, output_dir="./proteomes"):
    """Download all AlphaFold predictions for a species (bulk GCS, still v4)."""
    # Validate taxonomy_id is an integer to prevent injection
    if not isinstance(taxonomy_id, int):
        raise ValueError("taxonomy_id must be an integer")

    os.makedirs(output_dir, exist_ok=True)
    pattern = f"gs://public-datasets-deepmind-alphafold-v4/proteomes/proteome-tax_id-{taxonomy_id}-*_v4.tar"
    # List form (no shell=True) prevents command injection.
    subprocess.run(["gsutil", "-m", "cp", pattern, f"{output_dir}/"], check=True)

# Download E. coli proteome (tax ID: 83333)
download_proteome(83333)

# Download human proteome (tax ID: 9606)
download_proteome(9606)
```

## 5. Parsing and Analyzing Structures

Work with downloaded AlphaFold structures using BioPython:

```python
from Bio.PDB import MMCIFParser, PDBIO
import numpy as np

# Parse mmCIF file
parser = MMCIFParser(QUIET=True)
structure = parser.get_structure("protein", "AF-P00520-F1-model_v6.cif")

# Extract coordinates
coords = []
for model in structure:
    for chain in model:
        for residue in chain:
            if 'CA' in residue:  # Alpha carbons only
                coords.append(residue['CA'].get_coord())

coords = np.array(coords)
print(f"Structure has {len(coords)} residues")

# Calculate distances
from scipy.spatial.distance import pdist, squareform
distance_matrix = squareform(pdist(coords))

# Identify contacts (< 8 Å)
contacts = np.where((distance_matrix > 0) & (distance_matrix < 8))
print(f"Number of contacts: {len(contacts[0]) // 2}")
```

**Extract B-factors (pLDDT values):**

AlphaFold stores pLDDT scores in the B-factor column:

```python
from Bio.PDB import MMCIFParser

parser = MMCIFParser(QUIET=True)
structure = parser.get_structure("protein", "AF-P00520-F1-model_v6.cif")

# Extract pLDDT from B-factors
plddt_scores = []
for model in structure:
    for chain in model:
        for residue in chain:
            if 'CA' in residue:
                plddt_scores.append(residue['CA'].get_bfactor())

# Identify high-confidence regions
high_conf_regions = [(i, score) for i, score in enumerate(plddt_scores, 1) if score > 90]
print(f"High confidence residues: {len(high_conf_regions)}")
```

## 6. Batch Processing Multiple Proteins

Process multiple predictions efficiently:

```python
import os

import numpy as np
import pandas as pd
import requests

os.makedirs("./batch_structures", exist_ok=True)
uniprot_ids = ["P00520", "P12931", "P04637"]  # Multiple proteins
results = []

for uniprot_id in uniprot_ids:
    try:
        # Get prediction metadata (carries version-stamped file URLs)
        preds = requests.get(
            f"https://alphafold.ebi.ac.uk/api/prediction/{uniprot_id}"
        ).json()

        # Pick the canonical record; the list also carries isoforms.
        rec = next((p for p in preds if p.get('uniprotAccession') == uniprot_id),
                   preds[0] if preds else None)
        if rec:
            alphafold_id = rec['modelEntityId']

            # Download structure coordinates
            cif = requests.get(rec['cifUrl'])
            with open(f"./batch_structures/{alphafold_id}.cif", "wb") as fh:
                fh.write(cif.content)

            # Get confidence data
            conf_data = requests.get(rec['plddtDocUrl']).json()

            # Calculate statistics
            plddt_scores = conf_data['confidenceScore']
            avg_plddt = np.mean(plddt_scores)
            high_conf_fraction = sum(1 for s in plddt_scores if s > 90) / len(plddt_scores)

            results.append({
                'uniprot_id': uniprot_id,
                'alphafold_id': alphafold_id,
                'avg_plddt': avg_plddt,
                'high_conf_fraction': high_conf_fraction,
                'length': len(plddt_scores)
            })
    except Exception as e:
        print(f"Error processing {uniprot_id}: {e}")

# Create summary DataFrame
df = pd.DataFrame(results)
print(df)
```

## 3D-Beacons API Alternative

AlphaFold can also be accessed via the 3D-Beacons federated API:

```python
import requests

# Query via 3D-Beacons
uniprot_id = "P00520"
url = f"https://www.ebi.ac.uk/pdbe/pdbe-kb/3dbeacons/api/uniprot/summary/{uniprot_id}.json"
response = requests.get(url)
data = response.json()

# Each entry is {"summary": {...}}; filter for AlphaFold DB models
af_structures = [
    s['summary'] for s in data['structures']
    if s['summary']['provider'] == 'AlphaFold DB'
]
```

#!/usr/bin/env python3
"""Query the AlphaFold DB public REST API (no API key required).

Endpoints (https://alphafold.ebi.ac.uk/api/):
  - prediction/{uniprot}   -> prediction metadata (modelEntityId, file URLs, sequence)

The prediction metadata carries the exact, version-stamped file URLs
(cifUrl / pdbUrl / bcifUrl / plddtDocUrl / paeDocUrl). This script reads those
URLs from the response rather than hand-building a `_v{N}` suffix, so it keeps
working as the DB version advances (currently v6; old `_v4` file URLs now 404).

The endpoint returns a list that also includes isoform records (e.g. P00520-2)
and possibly third-party models, so the script picks the record whose
uniprotAccession matches the query instead of blindly taking the first one.

Smoke test:
    uv run python query_alphafold.py prediction P00520
    uv run python query_alphafold.py confidence P00520 --summary
    uv run python query_alphafold.py download P00520 --fmt cif -o ./structures
"""
import argparse
import json
import sys

import requests

API = "https://alphafold.ebi.ac.uk/api"

# Map a coordinate format to the metadata key that holds its URL.
_MODEL_URL_KEY = {"cif": "cifUrl", "pdb": "pdbUrl", "bcif": "bcifUrl"}


def get_prediction(uniprot: str) -> list:
    """Return AlphaFold prediction metadata records for a UniProt accession."""
    r = requests.get(f"{API}/prediction/{uniprot}", timeout=30)
    r.raise_for_status()
    return r.json()


def _first_record(uniprot: str) -> dict:
    """Return the record for exactly this accession (canonical, not an isoform)."""
    preds = get_prediction(uniprot)
    if not preds:
        sys.exit(f"No AlphaFold prediction for {uniprot}")
    for rec in preds:
        if rec.get("uniprotAccession") == uniprot or rec.get("modelEntityId") == uniprot:
            return rec
    return preds[0]


def get_confidence(uniprot: str) -> dict:
    """Fetch the per-residue confidence (pLDDT) JSON for a UniProt accession."""
    rec = _first_record(uniprot)
    url = rec["plddtDocUrl"]
    r = requests.get(url, timeout=60)
    r.raise_for_status()
    return r.json()


def download(uniprot: str, fmt: str, outdir: str) -> str:
    """Download a structure file (cif/pdb/bcif) and return the saved path."""
    import os

    rec = _first_record(uniprot)
    url = rec[_MODEL_URL_KEY[fmt]]
    os.makedirs(outdir, exist_ok=True)
    r = requests.get(url, timeout=120)
    r.raise_for_status()
    path = os.path.join(outdir, url.rsplit("/", 1)[-1])
    with open(path, "wb") as fh:
        fh.write(r.content)
    return path


def main() -> None:
    p = argparse.ArgumentParser(description="Query AlphaFold DB (no key required).")
    p.add_argument("action", choices=["prediction", "confidence", "download"])
    p.add_argument("uniprot", help="UniProt accession, e.g. P00520")
    p.add_argument("--fmt", default="cif", choices=["cif", "pdb", "bcif"])
    p.add_argument("-o", "--outdir", default="./structures")
    p.add_argument("--summary", action="store_true",
                   help="For confidence: print mean pLDDT + length instead of raw JSON")
    args = p.parse_args()

    if args.action == "prediction":
        print(json.dumps(get_prediction(args.uniprot), indent=2))
    elif args.action == "confidence":
        conf = get_confidence(args.uniprot)
        if args.summary:
            scores = conf.get("confidenceScore", [])
            mean = sum(scores) / len(scores) if scores else 0.0
            print(json.dumps({"length": len(scores), "mean_plddt": round(mean, 2)}, indent=2))
        else:
            print(json.dumps(conf, indent=2))
    else:
        print(download(args.uniprot, args.fmt, args.outdir))


if __name__ == "__main__":
    main()