AlphaFold Database Search Strategies

Q: Are AlphaFold database models experimental structures?

No. They are computational predictions with no experimental evidence about ligands, modifications, or assembly state. Confidence scores indicate where the prediction is reliable but do not convert a prediction into an experimentally determined structure.

By Dr. Zubair Khalid, DVM, MS, PhD · 2026-11-11

By the end of this article you will be able to look up any protein in the AlphaFold database using its UniProt accession, download the coordinates and confidence files for that protein, retrieve hundreds or thousands of structures in bulk through a web server and API, and run structure-similarity searches against the full database when a UniProt ID alone does not answer your question. You will need a UniProt accession for your protein of interest, a terminal with curl or wget installed for the command-line examples, and optionally a Python 3 environment if you want to automate retrieval.

Why the UniProt ID Is the Master Key

The AlphaFold database, hosted by EMBL-EBI, stores predicted structures for nearly every catalogued protein, indexed under stable accession numbers. The single most reliable identifier for pulling a model is the UniProt accession, a six- or ten-character code such as P04637 for human p53 or Q92839 for hyaluronan synthase 1. Research teams routinely anchor their workflows to these accessions. A study of goose astrovirus host proteins identified its candidate receptor through a UniProt database search and then pulled the matching AlphaFold model to build a docking complex [1]. Specialized databases do the same thing behind the scenes, cross-referencing every entry to AlphaFold models so users can retrieve predictions from a single search page [2].

The relationship between UniProt and AlphaFold DB is one-directional and simple. Each AlphaFold entry name embeds the UniProt accession, and each UniProt entry links back to its AlphaFold model when one exists. Once you know the accession, retrieval becomes deterministic, which is why every bulk tool in this article ultimately resolves your input to a UniProt or AlphaFold accession before downloading anything.

What You Need Before You Start

Have the following on hand:

A UniProt accession (for example, P04637). If you only have a gene symbol, protein name, or RefSeq accession, resolve it first at uniprot.org.
A terminal with curl or wget for single downloads.
A molecular viewer such as PyMOL, ChimeraX, or Mol* to inspect what you download.
Python 3 with the requests library if you want a reusable download script.

A note on terminology. The AlphaFold web interface is often called the AlphaFold server in casual usage, but it is a database browser rather than a prediction service. You cannot submit your own sequence there. Prediction runs through ColabFold or AlphaFold itself, while the database serves precomputed models for catalogued proteins.

Understanding AlphaFold DB Entry Names and File Types

Every entry in the database follows a fixed naming pattern:

AF-{UniProt accession}-F{fragment number}-model_v{version}.{extension}

So the human p53 model is AF-P04637-F1-model_v4.pdb. Three details in that pattern matter in practice.

Fragments. Very long protein sequences exceed the model's input capacity, so they are split. Fragment F1 covers the N-terminal portion, F2 the next portion, and so on. Most proteins have only F1, but if you work with large proteins such as titin-scale kinases or giant scaffolds, check for additional fragments.

Versions. The v number tracks the model release. When AlphaFold DB updates its models, the version suffix changes, and old files remain available. For reproducible pipelines, record the version you downloaded in your methods or README.

File types. Each entry offers a PDB file, an mmCIF file, a BinaryCIF file, and a PAE (predicted aligned error) JSON file. The PDB format is the most compatible with legacy tools. mmCIF handles entries that exceed legacy PDB limits. The PAE file is not coordinates at all. It is a matrix of expected positional errors between residue pairs, and it is the file that tells you which parts of the model can be trusted relative to each other.

AlphaFold Database Search by UniProt ID Step by Step

This section is the core alphafold tutorial workflow for single-protein retrieval.

Method 1: The AlphaFold Web Server

Open the AlphaFold DB entry page directly at a URL of the form https://alphafold.ebi.ac.uk/entry/P04637, replacing the accession with yours. This is faster than using the search box because the accession is the primary key.
Alternatively, go to the site and paste the accession into the search bar. The search also accepts gene names and protein names, but exact accessions give unambiguous hits.
On the entry page, inspect the model in the built-in viewer. The structure is colored by per-residue confidence, with high pLDDT (predicted local distance difference test, a 0 to 100 per-residue score) in blue and low confidence in red and orange.
Click the download menu and select the PDB, mmCIF, or PAE JSON file.

Expected result: a file named like AF-P04637-F1-model_v4.pdb, roughly a few hundred kilobytes for a single-chain protein.

Method 2: Direct File URLs with curl

The file server uses predictable URLs, so you can skip the web page entirely.

# Download the coordinates
curl -O https://alphafold.ebi.ac.uk/files/AF-P04637-F1-model_v4.pdb

# Download the PAE file
curl -O https://alphafold.ebi.ac.uk/files/AF-P04637-F1-predicted_aligned_error_v4.json

Expected output:

  % Total    % Received  % Xferd  Average Speed   Time    Time    Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  523k  100  523k    0     0   812k      0 --:--:-- --:--:-- --:--:--  812k

A quick sanity check on the coordinates:

head -3 AF-P04637-F1-model_v4.pdb

You should see ATOM records with the protein name embedded in the header lines. If instead you receive an HTML error page, the accession or version number in the URL is wrong.

Parameter notes. The version suffix is the parameter that breaks most scripted downloads. When a new database release appears, a hardcoded v3 returns 404 errors for newly renumbered entries. Two options handle this. Either query the entry page HTML for the current version, or use the database's documented API endpoints rather than the static file paths. Check the AlphaFold DB documentation for the current API contract before scripting against it.

Method 3: A Minimal Python Retrieval Script

import requests

def fetch_alphafold(uniprot_id, outdir="structures"):
    base = "https://alphafold.ebi.ac.uk/files"
    stem = f"AF-{uniprot_id}-F1"
    files = {
        "pdb": f"{stem}-model_v4.pdb",
        "pae": f"{stem}-predicted_aligned_error_v4.json",
    }
    for kind, fname in files.items():
        r = requests.get(f"{base}/{fname}", timeout=60)
        r.raise_for_status()
        with open(f"{outdir}/{fname}", "wb") as fh:
            fh.write(r.content)
        print(f"saved {fname} ({len(r.content)} bytes)")

fetch_alphafold("P04637")

Expected output:

saved AF-P04637-F1-model_v4.pdb (537214 bytes)
saved AF-P04637-F1-predicted_aligned_error_v4.json (1288410 bytes)

Byte counts will vary by protein and version. The key validation is that both files download without an HTTP error and the PDB opens in your viewer.

Bulk Retrieval for Many Accessions

Single downloads scale poorly past about a dozen proteins, and the standard download paths were not designed for proteome-scale requests limited to a fixed list of organisms. The AlphaFoldDB Structure Extractor was built to close that gap. It is an open-access web server and API that accepts NCBI Taxonomy IDs, RefSeq accessions, old and new locus tags, and UniProt or AlphaFold accessions, then downloads the corresponding structures in PDB, mmCIF, bCIF, PAE JSON, or any combination of those formats [3].

The tool is available at https://project.iith.ac.in/sharmaglab/alphafoldextractor/ [3]. Three design decisions make it useful in real pipelines.

Identifier flexibility. You can paste a list of locus tags straight from an annotation file, and the service resolves them to standard accessions. It generates an accompanying ID mapping file that traces each input identifier back to its standard accession, and reports unmapped IDs separately so you can audit failures rather than discovering silent gaps later [3].
Mapping-only mode. If you only need the accession translation and not the coordinate files, you can run the ID mapping step alone [3].
Programmatic access. An API supports integration into bioinformatics pipelines, so the same bulk retrieval can run inside a Snakemake or Nextflow workflow [3].

The developers validated the tool with randomly selected accessions of every supported type, both individual inputs and batches of up to 5000 input accessions, drawn from NCBI RefSeq and Taxonomy, UniProt, and AlphaFold DB [3]. That gives a practical ceiling for a single submission. For larger jobs, split your list.

A bulk workflow in practice looks like this:

# Prepare one accession per line
cat query_ids.txt
# P04637
# Q92839
# P00533

Submit the list through the extractor web interface or call its API with the list, request PDB plus PAE JSON output, and collect two artifacts: a directory of structure files and a mapping table.

query_ids.txt -> AF-P04637-F1-model_v4.pdb, mapped
query_ids.txt -> AF-Q92839-F1-model_v4.pdb, mapped
query_ids.txt -> no match, listed as unmapped

Any row marked unmapped needs manual follow-up. Common causes are retired accessions and proteins absent from the proteomes covered by the database.

Structure-Based Search Strategies Beyond the UniProt ID

An accession lookup answers a precise question. Many structural questions need the reverse operation: given a structure or a protein, find related folds across the database. Three published tools cover this space, and they complement accession-based retrieval rather than replacing it.

AlphaFind for Whole-Database Similarity Search

AlphaFind is a web-based search engine that indexes the full set of AlphaFold DB structures by tertiary structure alone. It automatically extracts the main 3D features of each protein chain and uses a machine learning model to retrieve the most similar structures, an approach that has scaled to the full database [4]. The searcher accepts any valid UniProt ID, Protein Data Bank ID, or gene symbol, returns similar chains with similarity metrics, and renders 3D superpositions so you can inspect the alignment immediately [4].

This is the fastest route from a UniProt ID to structural neighbors when you suspect remote homology that sequence searches miss. Because the query accepts the same accession you already hold, it slots directly after your accession-based retrieval step.

3D-AF-Surfer for Real-Time Fold Classification

3D-AF-Surfer represents structures with 3D Zernike descriptors, a rotationally invariant mathematical encoding of 3D shapes, and applies a neural network that retrieves proteins of the same fold more accurately than direct descriptor comparison [5]. The infrastructure supports real-time structure-based search across AlphaFold2 models, and the authors used it to classify models and to examine the relationship between model confidence and intrinsically disordered regions [5]. Use it when you want fold-level classification rather than chain-level similarity ranking.

MrParse for Molecular Replacement Workflows

Crystallographers have a different retrieval problem. Before molecular replacement (MR), the phasing method that uses a known homologous structure to solve a new crystal form, you need candidate search models ranked by likelihood of success. MrParse consolidates that decision process by finding homologues in the PDB and in the EBI AlphaFold database in a single run [6]. When reflection data are supplied, MrParse ranks experimental homologues using eLLG, a metric indicating the likelihood that a given search model will solve the structure, and it displays predicted secondary structure, coiled-coil, and transmembrane regions to inform protocol choice [6]. The AlphaFold homologue ranking also serves structural biologists outside crystallography who simply want to know which predicted models resemble their target [6].

Putting Retrieved Models to Work

Retrieval is rarely the end goal. Published pipelines show where the files go next, and each downstream use imposes its own preparation requirements.

Protonation and simulation setup. Before molecular dynamics or any electrostatics calculation, you need residue protonation states appropriate to your pH. The PypKa server computes pKa values, isoelectric points, titration curves, and pH-compatible structures for AMBER, CHARMM, and GROMOS force fields. You can upload a custom structure or submit a UniProtKB identifier, and results for over 200,000 structures from the PDB and AlphaFold DB are precomputed and retrievable without calculation, with API access for pipelines [7]. If your protein of interest is in that precomputed set, the pH-preparation step is already done.

Crosslinking mass spectrometry. AlphaCross-XL automates mapping of cross-linked peptides onto 3D structures at proteome scale. Earlier tools required manual selection of specific PDB structures for each protein, which failed for datasets spanning thousands of proteins, so AlphaCross-XL retrieves structures directly from the AlphaFold Protein Structure Database and maps intraprotein crosslinks and loop links automatically [8]. Its retrieval layer is the same accession-based lookup described above, embedded in a high-throughput pipeline.

Enzyme function annotation. ActSeekN searches for conserved catalytic motifs across a reference database built from AlphaFold-predicted structures, UniProt annotations, and curated catalytic residue information. It transfers function based on local three-dimensional catalytic geometry rather than global sequence similarity, which helps for proteins with low sequence identity or convergent evolutionary histories [9]. The UniProt accession again serves as the join key between your query protein and the structural reference set.

Variant mapping. Clinical and population genetics studies map variants onto AlphaFold models alongside experimental structures. An interactive database of ADAMTS13 variants in congenital thrombotic thrombocytopenic purpura mapped over 300 reported variants onto both X-ray and AlphaFold structures to connect genetic variation with protein structure [10].

Choosing a Strategy: Comparison Table

Strategy	Input accepted	Best for	Output formats	Scale
, -	, -	, -	, -	, -
AlphaFold DB entry page	UniProt accession, gene or protein name	One protein, visual inspection first	PDB, mmCIF, PAE JSON	1
Direct file URL	Accession plus known version	Scripts, reproducible downloads	PDB, mmCIF, PAE JSON	1 to dozens
AlphaFoldDB Structure Extractor	Taxonomy ID, RefSeq, locus tags, UniProt, AlphaFold accessions	Batch retrieval and ID mapping	PDB, mmCIF, bCIF, PAE JSON	Up to thousands per submission [3]
AlphaFind	UniProt ID, PDB ID, gene symbol	Structural similarity search	Ranked similar chains, superpositions	Whole database [4]
3D-AF-Surfer	Structure or model ID	Fold classification	Fold matches and classifications	Whole model set [5]
MrParse	Sequence, optionally reflection data	MR search-model selection	Ranked PDB and AlphaFold homologues	Per target [6]

Reading Confidence: pLDDT and PAE

Two scores govern how you should use any model you retrieve, and both are standard outputs of the AlphaFold method.

pLDDT is a per-residue confidence score from 0 to 100, stored in the B-factor column of the PDB file. Residues above roughly 90 indicate very high local accuracy. Residues below roughly 50 frequently correspond to intrinsically disordered regions, and the fold-classification study using 3D-AF-Surfer examined exactly that correlation between model confidence and intrinsic disorder [5]. In practice, treat low-pLDDT segments as unstructured rather than as a wrong fold.

PAE is a pairwise measure. Each cell of the matrix gives the expected positional error between two residues. High pLDDT with high PAE between two domains means both domains are internally accurate but their relative arrangement is uncertain. This distinction matters most when you interpret multi-domain proteins or interfaces.

A quick extraction of pLDDT values from a downloaded model:

import numpy as np

b_factors = []
with open("AF-P04637-F1-model_v4.pdb") as fh:
    for line in fh:
        if line.startswith("ATOM") and line[12:16].strip() == "CA":
            b_factors.append(float(line[60:66]))

arr = np.array(b_factors)
print(f"mean pLDDT: {arr.mean():.1f}")
print(f"residues below 50: {(arr < 50).sum()} of {len(arr)}")

Expected output for a well-ordered protein is a mean in the high 80s or 90s and only a handful of low-confidence residues, usually at termini.

Common Mistakes and Limitations

These are the errors that most often produce wrong structures, empty results, or misleading interpretations.

Confusing the UniProt accession with the entry name. P53_HUMAN is the mnemonic entry name. P04637 is the accession. AlphaFold DB indexes by accession. A search for the mnemonic may work in the web interface but will fail in direct file URLs and most APIs.
Using an ID from the wrong database. RefSeq accessions (NP_ format) and Ensembl IDs are not UniProt accessions. Direct URL construction fails silently or returns 404. The Structure Extractor solves this by accepting RefSeq accessions and locus tags and mapping them first [3], which is precisely why the mapping file and the separate unmapped-ID report matter for audit trails [3].
Ignoring isoforms. AlphaFold DB models the canonical sequence. If your protein of interest is an isoform with a distinct UniProt accession, the model you retrieve describes a different sequence. Check the F-number and sequence length on the entry page before assuming coverage.
Hardcoding the version number. Scripts that pin model_v3 break when the database releases a new version. Pin deliberately for reproducibility, and update deliberately rather than letting a 404 surprise you mid-project.
Treating predicted structures as experimental ones. An AlphaFold model carries no evidence of ligands, cofactors, post-translational modifications, or oligomeric state. The model describes a single chain in isolation unless a dedicated complex prediction exists.
Skipping protonation preparation before simulations. Default residue protonation states taken straight from a downloaded model often produce incorrect electrostatics in molecular dynamics. Tools such as PypKa exist to assign pH-appropriate states before simulation setup [7].
Over-reading low-confidence regions. A red, floppy tail in the viewer is usually a disordered region, not a modeling failure to be fixed. Re-running or tweaking the model will not make an intrinsically disordered segment adopt a stable fold.
Assuming cross-chain arrangements. Single-chain models say nothing about how chains assemble in a complex. If your question involves a protein-protein interface, a single AlphaFold DB download is not sufficient evidence, and docking or complex prediction is a separate step, as in the astrovirus receptor workflow that combined AlphaFold models with docking tools [1].
Forgetting numbering offsets. Residue numbering in the model corresponds to the mature UniProt sequence. Signal peptides, processing events, and construct boundaries in experimental structures can shift numbering by tens of residues. Always reconcile numbering before mapping variants or mutations, a step the ADAMTS13 variant database handled explicitly by mapping variants onto both structure types [10].
Submitting oversized batches. Bulk services have practical limits. The Structure Extractor was tested up to 5000 input accessions per submission [3], so chunk larger lists rather than assuming unbounded capacity.

One broader limitation deserves a direct statement. AlphaFold DB coverage depends on which proteomes have been processed, so proteins from poorly annotated organisms may be absent even though close orthologs exist. A failed lookup is a coverage question, not usually an identifier error, and the fix is to retrieve the ortholog and model or align back to your sequence.

Resolving Any Identifier to a UniProt Accession Before You Search

The single most common failure point in AlphaFold retrieval is not the database itself. It is the identifier you start with. Because AlphaFold DB indexes every model under a UniProt accession, every other identifier type (gene symbol, protein name, RefSeq accession, Ensembl gene ID, locus tag) must be translated first, and each translation step is a place where you can silently retrieve the wrong protein. This section walks through the translation process for the identifier types you are most likely to encounter, using the three proteins already used as running examples in this article: human p53 (TP53, P04637), hyaluronan synthase 1 (Q92839), and epidermal growth factor receptor (EGFR, P00533).

Gene symbol to accession

Gene symbols are the least reliable starting point because they are not globally unique. The symbol "MMP1" refers to different loci in different organisms, and some symbols collide across species entirely. The safe procedure is:

Go to uniprot.org and search the gene symbol with the organism name appended or selected in the organism filter. Searching "TP53" with "human" restricted as the taxonomy should return the reviewed human entry as the top hit.
Confirm you are looking at a reviewed entry rather than a TrEMBL entry. Reviewed entries carry curated annotations and are the accessions AlphaFold DB models against. TrEMBL accessions for the same gene are usually redundant predictions of the same sequence.
Read the entry's gene and protein names to confirm biological identity. For p53 you should see "Cellular tumor antigen p53" and the TP53 gene name.
Copy the plain accession, in this case P04637, and note whether the page lists a versioned form such as P04637.2. AlphaFold DB uses the plain accession, not the version, so record both but retrieve by the plain form.
Check the isoform list on the entry page. UniProt marks one sequence as canonical; AlphaFold models correspond to that canonical sequence. If your experiment targets an isoform, you need the isoform's own accession, discussed further below.

RefSeq and Ensembl accessions to accession

RefSeq protein accessions in NP_ format and Ensembl protein IDs (ENSP format) are legitimate, stable identifiers, but they are not UniProt accessions and will not work in direct AlphaFold file URLs or the entry page URL. Two paths handle them.

The first path is manual. Open the RefSeq or Ensembl entry, find the cross-reference or external links section, and follow the link to UniProt. Then confirm that the UniProt entry you land on matches your expectation for organism and protein length, because database cross-links occasionally point to unreviewed or fragmentary entries.

The second path is programmatic and scales better. The AlphaFoldDB Structure Extractor accepts RefSeq accessions directly alongside UniProt and AlphaFold accessions, resolves them to standard accessions before downloading anything, and returns a mapping file plus a separate report of unmapped inputs [3]. For a single protein this may feel like overkill, but for a list of thirty RefSeq accessions pulled from an RNA-seq differential expression table it is the difference between an auditable retrieval and a manual afternoon of cross-referencing.

Locus tags and genome annotation IDs

If your starting point is a genome annotation file, for example a GFF from a newly sequenced organism, your identifiers are locus tags such as those assigned by Prokka or NCBI's prokaryotic genome annotation pipeline. These tags mean nothing to AlphaFold DB directly. The extractor's acceptance of old and new locus tags, and its explicit separation of mapped and unmapped inputs, exists precisely because this identifier class is common in microbial genomics and awkward to resolve by hand [3]. When you submit locus tags, keep the mapping file in your project directory alongside the downloaded structures. Six months from now, a collaborator will ask which structure file corresponds to which locus tag, and the mapping file is the only reliable answer.

Protein names and text searches

Searching the AlphaFold web interface by protein name works, but treat it as a browsing operation rather than a retrieval operation. Name searches can return multiple hits, and the top hit is not guaranteed to be the ortholog or species you intend. The reliable habit is to use text search to find a candidate, click through to the UniProt entry linked from the AlphaFold page, confirm the organism and sequence there, and only then record the accession as your retrieval key.

A worked resolution: three identifiers, three paths

Consider a realistic intake list containing "TP53", "NP_000537", and "EGFR". The three identifiers take three different paths:

"TP53" is a gene symbol. Resolve it at uniprot.org with the human organism filter, confirm the reviewed entry, and arrive at P04637.
"NP_000537" is a RefSeq accession. Either follow the cross-reference manually or submit it to the Structure Extractor, which maps it to its UniProt equivalent before downloading [3].
"EGFR" is a gene symbol like TP53, resolved the same way, arriving at P00533.

All three then converge on the same retrieval mechanics. The point of the exercise is that the convergence is only guaranteed if you force every identifier through an explicit resolution step. A pipeline that passes mixed identifier types directly to a URL constructor will fail unpredictably, and the failures will be silent in exactly the cases where the identifier resembles a UniProt accession but is not one.

A Closer Walkthrough of the AlphaFold Web Entry Page

The entry page is the fastest way to inspect a model before committing to a download, and most people underuse it. Treat the page as a pre-flight check that saves you from downloading and opening files you will immediately discard.

What to check, in order

Sequence length and fragment count. The entry page displays the modeled sequence length. Compare it against the canonical sequence length on the linked UniProt entry. If they match, the model spans the full canonical chain (subject to any splitting into multiple fragments for very long proteins). If the UniProt entry lists additional fragments F2, F3, and beyond, note them now, because a single F1 download does not describe the whole protein for fragmented entries.

The confidence coloring. The built-in viewer colors the ribbon by pLDDT, with blue at the confident end and red and orange at the low-confidence end [the coloring scheme is described in the step-by-step section above]. Before downloading, scroll through the structure and note where the confident core sits. For a well-behaved enzyme you will usually see a continuous blue and cyan fold with red termini. For a signaling protein you may see confident domains connected by long red or orange stretches. That visual survey tells you immediately which regions can support downstream analysis.

Domain boundaries in context. If you have domain annotations from UniProt or InterPro, open them in a second tab and relate them to the colored structure. The pairing of annotation boundaries with confidence coloring is the fastest way to decide, for example, whether a kinase domain is modeled well enough for docking while the regulatory tail is not.

The linked UniProt entry. Every AlphaFold page links back to UniProt. Click through and skim the annotations: known active sites, variants, PTMs, and subcellular localization all color your later interpretation. Remember that the model itself carries none of this information. The prediction is a chain of coordinates and a confidence estimate, nothing more.

When to skip the page entirely

If you are running a script, do not scrape the entry page. Direct file URLs, the extractor API, or the database's documented API endpoints are the correct programmatic interfaces. Check the AlphaFold DB documentation for the current API contract before scripting against it, because interfaces are updated and scraping HTML is fragile. The entry page is for humans and for the one-time visual check; scripts should talk to endpoints.

Parsing and Using the PAE File in Practice

The PAE JSON file is the most valuable and most neglected download. Most users grab the PDB, never open the JSON, and then wonder why two domains that look individually excellent sit in an orientation that docking or mutagenesis data contradict. This section makes the PAE file concrete.

What is inside the file

The PAE JSON for a single-chain model contains a matrix of predicted positional errors between residue pairs, plus a maximum error value as metadata. The matrix is square, with one row and column per modeled residue, and it is symmetric in interpretation: the expected error at position (i, j) reflects how precisely the relative placement of residue i and residue j is predicted. Low values mean the two residues' relative positions are well determined. High values mean the model is effectively uncertain about how those two residues relate in space.

A minimal parsing script

import json
import numpy as np

with open("AF-P04637-F1-predicted_aligned_error_v4.json") as fh:
    data = json.load(fh)

# The matrix lives under the predicted_aligned_error key in the
# standard single-chain format; verify against the current
# documentation because the schema has changed between releases.
if "predicted_aligned_error" in data:
    pae = np.array(data["predicted_aligned_error"])
else:
    raise KeyError(
        "PAE matrix key not found; check the AlphaFold DB "
        "documentation for the current JSON schema."
    )

print(f"matrix shape: {pae.shape}")
print(f"overall mean PAE: {pae.mean():.2f}")

Expected output is a square matrix whose dimension equals the modeled residue count, with a mean whose value depends entirely on the protein. A small, single-domain protein will show a low overall mean. A large multi-domain protein will show a low mean contributed by confident domain cores, pulled upward by uncertain inter-domain blocks.

Reading the block structure

The most informative view of a PAE matrix is visual. Plot it as a heatmap, residues in order along both axes:

import matplotlib.pyplot as plt

plt.imshow(pae, cmap="viridis_r", origin="upper")
plt.xlabel("residue index")
plt.ylabel("residue index")
plt.colorbar(label="PAE")
plt.tight_layout()
plt.savefig("pae_heatmap.png", dpi=200)

In a typical multi-domain protein you will see dark blocks along the diagonal, one per domain, separated by brighter bands off the diagonal. Each dark block is a domain whose internal geometry is well predicted. Bright off-diagonal regions mean the model is uncertain about the relative orientation of those domains. The practical reading rule, stated in the confidence section above, bears repeating in operational terms: high pLDDT within two domains combined with high PAE between them means you can trust each domain's fold but should not over-interpret the hinge angle or interface the model happens to show.

Deciding what the PAE authorizes you to do

Use the PAE matrix to make three concrete decisions:

Can I dock a ligand into this region? If the pocket-forming residues show low PAE against each other, the pocket geometry is internally consistent and docking into it is reasonable, with the standing caveat that a predicted model carries no ligand or cofactor evidence.
Can I trust the inter-domain arrangement for building a complex? If the PAE between the relevant domains is high, treat the displayed orientation as one plausible sample rather than a determined structure, and consider whether your downstream method tolerates that uncertainty.
Can I map a variant or mutation into a structural context? If the mutated residue's row in the PAE matrix shows low values against the residues you claim it interacts with, the interaction geometry is well determined and the mapping is defensible. This is exactly the kind of judgment the ADAMTS13 variant database had to apply when placing over 300 reported variants onto structural models [10].

Handling Fragments, Isoforms, and Sequence Mismatches

Fragments in detail

The fragment number in AF-{accession}-F{n} exists because very long sequences exceed the model's input capacity and are split into consecutive pieces. Most entries you will touch have only F1. The failure mode to guard against is working with a genuinely large protein, downloading F1 out of habit, and analyzing an incomplete structure without noticing. Hyaluronan synthase 1 (Q92839) is a membrane enzyme at the large end of typical single-chain modeling, and entries at that scale and beyond are the ones where you should check the entry page for multiple fragments before scripting anything.

A robust download function should not assume F1 is the only fragment. The safe pattern is to attempt F1, and for proteins where you suspect fragmentation, check the entry page or the API for the complete fragment list, then download each fragment file you need. Record which fragments you retrieved, because analyses that silently concatenate nonadjacent fragments produce chimeric coordinates.

Isoforms

AlphaFold DB models the canonical UniProt sequence. If your protein of interest is an isoform with its own distinct accession, the model you retrieve describes a different sequence, and any residue numbering you carry over from the model will be wrong for the isoform unless you align the two sequences first. The workflow is:

Identify the isoform accession on the UniProt entry page.
Align the isoform sequence to the canonical sequence with any standard pairwise aligner.
Translate coordinates between the two numbering schemes, inserting gap adjustments where the isoform contains an insertion relative to the canonical sequence.
Reuse the canonical model as a structural approximation for conserved regions, while stating clearly in your methods that the model corresponds to the canonical sequence, not the isoform.

This approximation is acceptable for conserved folded regions and unacceptable where the isoform's unique exon changes the local fold. Say which case applies in your write-up.

Verifying the model matches your sequence

Before building an analysis on a downloaded model, verify that its sequence is the one you think it is. Extract the residue sequence directly from the coordinates:

three_to_one = {
    "ALA": "A", "ARG": "R", "ASN": "N", "ASP": "D", "CYS": "C",
    "GLN": "Q", "GLU": "E", "GLY": "G", "HIS": "H", "ILE": "I",
    "LEU": "L", "LYS": "K", "MET": "M", "PHE": "F", "PRO": "P",
    "SER": "S", "THR": "T", "TRP": "W", "TYR": "Y", "VAL": "V",
    "MSE": "M",  # selenomethionine, occasionally present
}

seq = []
with open("AF-P04637-F1-model_v4.pdb") as fh:
    for line in fh:
        if line.startswith("ATOM") and line[12:16].strip() == "CA":
            resname = line[17:20].strip()
            if resname in three_to_one:
                seq.append(three_to_one[resname])

model_seq = "".join(seq)
print(f"model length: {len(model_seq)}")
print(model_seq[:60])

Then compare the extracted sequence against the canonical FASTA from the UniProt entry, which you can copy from the uniprot.org page or fetch through UniProt's documented REST service. For a canonical full-length model the two sequences should match in length and content. A mismatch means one of three things: you downloaded the wrong entry, you downloaded a fragment of a fragmented entry, or the database version you retrieved corresponds to a different canonical sequence than the one you expected after a UniProt update. All three are worth catching before they contaminate a residue-mapping analysis.

Building a Reproducible Bulk Download Pipeline

For anything beyond a one-off download, treat retrieval as a small pipeline with logging, checkpointing, and verification. The following script extends the minimal retrieval script above into something you can rerun after interruption without redownloading everything.

import csv
import json
import requests
import time
from pathlib import Path

BASE = "https://alphafold.ebi.ac.uk/files"
VERSION = "v4"  # pin deliberately; change deliberately

def fetch_one(uniprot_id, outdir, session, retries=3):
    stem = f"AF-{uniprot_id}-F1"
    targets = {
        "pdb": f"{stem}-model_{VERSION}.pdb",
        "pae": f"{stem}-predicted_aligned_error_{VERSION}.json",
    }
    record = {"uniprot_id": uniprot_id, "version": VERSION}
    for kind, fname in targets.items():
        outpath = Path(outdir) / fname
        if outpath.exists() and outpath.stat().st_size > 0:
            record[f"{kind}_status"] = "cached"
            continue
        for attempt in range(retries):
            try:
                r = session.get(f"{BASE}/{fname}", timeout=60)
                if r.status_code == 404:
                    record[f"{kind}_status"] = "not_found"
                    break
                r.raise_for_status()
                outpath.write_bytes(r.content)
                record[f"{kind}_status"] = f"downloaded_{len(r.content)}b"
                break
            except requests.RequestException as exc:
                record[f"{kind}_status"] = f"error_{attempt}"
                time.sleep(2 ** attempt)
        else:
            continue
    return record

def run_batch(ids, outdir="structures", manifest="manifest.csv"):
    Path(outdir).mkdir(exist_ok=True)
    session = requests.Session()
    records = []
    with open(manifest, "a", newline="") as fh:
        writer = csv.DictWriter(
            fh,
            fieldnames=["uniprot_id", "version",
                        "pdb_status", "pae_status"],
        )
        for uid in ids:
            rec = fetch_one(uid, outdir, session)
            records.append(rec)
            writer.writerow(rec)
            fh.flush()
    return records

if __name__ == "__main__":
    ids = [line.strip() for line in open("query_ids.txt")
           if line.strip()]
    results = run_batch(ids)
    failed = [r for r in results
              if r.get("pdb_status") in ("not_found",)
              or r.get("pdb_status", "").startswith("error")]
    print(f"{len(results)} processed, {len(failed)} need review")

Why each design choice matters

The manifest file. Every run appends a row per accession with the version and the per-file outcome. This is your reproducibility record. When a reviewer or collaborator asks which database version your structures came from, the manifest answers it, and when a new release renames files, the manifest tells you exactly which of your analyses used which version.

Caching. The existence check means a rerun after interruption only downloads what is missing. Without it, a network failure at accession 400 of 900 costs you the entire batch.

Distinguishing 404 from transient errors. A 404 for a given version usually means the accession is invalid, the entry is fragmented differently than you assumed, or the version is stale. A connection error is transient. Treating them identically, which most naive scripts do, either burns retries on permanent failures or gives up on temporary ones.

Rate courtesy. The exponential backoff on exceptions prevents your script from hammering the service during an outage. When you scale to many thousands of accessions, remember that the dedicated bulk service exists precisely because the standard download paths were not designed for proteome-scale requests [3], and the extractor's tested ceiling of 5000 inputs per submission [3] gives you a chunking target: split any list larger than that into multiple submissions.

Cross-checking the two approaches

A useful hygiene step is to retrieve a handful of accessions by both paths, the direct file URLs and the bulk service, and diff the results. The files should be identical byte for byte or at least identical in content. If they are not, one of your version assumptions is wrong. This two-minute check catches the majority of silent version mismatches before they propagate through a project.

Troubleshooting Failed Lookups: A Diagnostic Workflow

When a retrieval fails, resist the urge to try random variations of the identifier. Work through the following diagnostic sequence, which covers the failure modes in rough order of frequency.

Symptom: 404 on a direct file URL. Causes, in order: the version suffix is stale, the accession is not a UniProt accession (a RefSeq or Ensembl ID pasted by mistake), the accession is retired or merged, or the protein lies outside the proteomes the database covers. Fix each in turn: check the entry page to see the current version; verify the identifier resolves at uniprot.org; follow merge instructions if UniProt shows the accession as merged into another; and only conclude a coverage gap after all three checks pass.

Symptom: the entry page loads but the file URL fails. This combination almost always means a fragmented entry where you requested a fragment that does not exist, or a version mismatch between what the page shows and what your URL pins. Read the exact filename pattern on the entry page's download menu and copy it verbatim.

Symptom: the web search finds nothing but the UniProt entry clearly exists. First check that you searched the accession rather than the mnemonic entry name, since direct indexing is by accession. Then check organism coverage. The database's coverage depends on which proteomes have been processed, so a protein from a poorly annotated organism can be absent while close orthologs exist. The fix for a coverage gap is to retrieve the ortholog's model and work through an alignment back to your sequence, not to keep retrying the lookup.

Symptom: the bulk service reports unmapped IDs. Read the unmapped report rather than assuming the service failed. Common causes are retired accessions, locus tags from an annotation version different from the one the service indexes, and proteins genuinely absent from covered proteomes [3]. The unmapped report is an audit artifact; treat it as part of your results, not as noise.

Symptom: the PDB downloads but will not open in your viewer. Check the first bytes of the file. If you see HTML rather than ATOM records, your download captured an error page, usually from a malformed URL or an intermediate proxy. Delete the file, fix the URL, and redownload.

Symptom: everything downloads but downstream tools reject the structure. Very long chains exceed legacy PDB format limits, which is why mmCIF exists. Switch the downstream tool to read mmCIF, or use the BinaryCIF option for viewers that support it, rather than trying to repair a PDB file that is hitting a format ceiling.

Superposing AlphaFold Models with Experimental Structures

A frequent task after retrieval is comparing the predicted model with an experimental structure of the same or a homologous protein, to see where they agree and where the prediction diverges from experiment. The comparison requires care, because a predicted model and an experimental structure differ in kind, not just in quality.

Superposition in PyMOL

Load both structures and align on a confident region rather than on everything:

# In PyMOL's command line
load AF-P04637-F1-model_v4.pdb, model
load 2OCJ.pdb, exp
# Align using only well-predicted core residues, for example
# residues 100 to 300 of the model
align model and resi 100-300 and name CA, exp and name CA
zoom model and resi 100-300

The align command superimposes using an iterative fitting on the residue selection you give it. Restricting the alignment to a high-pLDDT, low-PAE core region gives you an honest answer about whether the fold agrees, rather than an RMSD dominated by a floppy terminus that neither structure determines well.

Superposition in ChimeraX

# In ChimeraX
open AF-P04637-F1-model_v4.pdb
open 2OCJ.pdb
mmaker #1 to #2

The matchmaker command performs sequence-based superposition and reports the RMSD over matched residues. As with PyMOL, restrict or at least inspect the matched residue set; a per-residue deviation plot tells you which regions agree and which do not.

Interpreting the comparison honestly

Three caveats govern interpretation. First, agreement in the core and divergence at flexible regions is the expected pattern, not a red flag. Second, a conformational difference between model and experiment may reflect a genuine conformational change captured by the experiment, such as a ligand-bound state, rather than a prediction error. Third, remember the standing limitation that the model describes a single chain in isolation, so any interface visible in the experimental structure's oligomeric assembly has no counterpart in the retrieved model. When your actual need is to find which predicted models resemble a target, MrParse's ranking of homologues in the PDB and in the EBI AlphaFold database in a single run performs exactly this comparison at scale [6].

From Downloaded Model to Analysis: Three Mini-Workflows

Retrieval earns its keep only when the files feed an analysis. The following three workflows show the full path from accession to result, each anchored to a published pipeline described earlier in this article.

Workflow 1: Mapping patient variants onto a predicted structure

Retrieve the model by UniProt accession and confirm the canonical sequence matches your reference transcript's protein product, reconciling any numbering offsets introduced by signal peptides or processing events, the same reconciliation the ADAMTS13 variant database handled explicitly when mapping variants onto X-ray and AlphaFold structures [10].
Extract pLDDT for every variant position using the B-factor parsing approach shown earlier.
Extract PAE rows for each variant position against the residues implicated by your functional hypothesis.
Classify variants into those falling in confident, well-determined structural contexts and those falling in low-confidence or high-PAE regions where structural interpretation is weak.
Report both the mapping and the confidence context. A variant "in a helix" means something different at pLDDT 95 than at pLDDT 45, and a paper that reports the mapping without the confidence context overstates what the structure supports.

Workflow 2: Protonation and simulation setup

Download the model and any PAE file for confidence-aware region selection.
Check whether your protein's pKa values, titration curve, and pH-prepared structure are already precomputed: PypKa provides precomputed results for over 200,000 structures from the PDB and AlphaFold DB, retrievable without recalculation and accessible through an API [7].
If your structure is in the precomputed set, retrieve the pH-appropriate protonation states for your force field of the supported set (AMBER, CHARMM, GROMOS) [7].
Use the low-confidence regions of the model, identified by pLDDT, to decide which segments to cap, restrain, or model separately in your simulation setup, since disordered tails straight from the database are not meaningful starting coordinates for a stable simulation.
Document the model version and the protonation pH in your methods.

Workflow 3: Retrieval inside a crosslinking mass spectrometry pipeline

Start from your list of crosslinked protein identifiers, however they are formatted in your proteomics results.
Resolve every identifier to a UniProt accession, using the mapping capability of the bulk extractor where necessary [3].
Retrieve structures for the mapped accessions; this retrieval layer is the same accession-based lookup described throughout this article, and AlphaCross-XL embeds it to fetch structures directly from the database at proteome scale, replacing the older practice of manually selecting a PDB structure per protein [8].
Map intraprotein crosslinks and loop links onto the retrieved coordinates, and use the pLDDT and PAE context for each crosslink when judging whether a violated distance restraint indicates a modeling artifact or a genuine structural feature.

Workflow 4: Building a docking complex from a receptor lookup

The goose astrovirus study illustrates the pattern for host-pathogen work: identify the candidate receptor through a UniProt database search, pull the matching AlphaFold model, and combine it with docking tools to build the complex [1]. The steps generalize:

Resolve your ligand protein and candidate receptor to accessions.
Retrieve both models, and inspect the confidence of the surfaces you intend to dock.
Prepare each monomer separately, including protonation where electrostatics matter to the docking score.
Dock, and treat the single-chain provenance of both models as a stated limitation: neither model contains evidence about the oligomeric state or conformational changes that docking assumes.

Common Misconceptions About Predicted Models

Beyond the operational mistakes listed earlier, several conceptual misconceptions recur in practice, and each one distorts how results are presented.

"The database is a server that predicts my structure." The AlphaFold web interface is a database browser, not a prediction service. You cannot submit your own sequence there. Prediction runs through ColabFold or AlphaFold itself, as noted in the terminology section above. If your protein is not in the database, retrieval cannot help you; prediction is the separate step.

"High average pLDDT means the whole model is trustworthy." Averages hide distributions. A model can carry a strong mean pLDDT while one domain linker sits in the danger zone. Always look at the per-residue profile and the PAE block structure, never the single number.

"The model shows how the protein acts in the cell." The model describes one chain, one sequence, one conformational sample, with no ligands, no membrane context unless the fold itself embeds one, no PTMs, and no binding partners. Every cellular interpretation layered onto the model comes from annotations you join to it, such as the catalytic-geometry function transfer that ActSeekN performs by joining AlphaFold structures with UniProt annotations and curated catalytic residue information [9], or the cross-references that specialized databases maintain so a single search page can surface the matching AlphaFold predictions [2].

"A low pLDDT region is an error I should fix." Low pLDDT frequently corresponds to intrinsic disorder. The 3D-AF-Surfer study examined the relationship between model confidence and intrinsically disordered regions precisely because that correlation is real and informative [5]. Re-running the prediction will not fold an unstructured segment.

"If AlphaFold and the experiment disagree, one of them is wrong." Often both are right about different things. The experiment captures one conformation under specific conditions; the prediction samples the ensemble implied by sequence. Disagreement at a hinge or an activation loop is an invitation to think about conformational states, not an automatic error report.

"Finding a structurally similar protein means they are homologs." Structure similarity search tools such as AlphaFind retrieve the most structurally similar chains across the full database using extracted 3D features and a machine-learned similarity model [4]. Structural similarity can arise through remote homology or through convergent evolution. Similarity results are hypotheses about relationships, and sequence-based evidence or fold-level classification, as 3D-AF-Surfer provides through its rotationally invariant Zernike descriptor representation and neural network retrieval [5], is the complementary check.

When to Retrieve and When to Predict

Retrieval and prediction answer different questions, and choosing correctly saves days.

Retrieve when the protein is catalogued, when you need results immediately, when you want consistency with other database users studying the same protein, and when your downstream tools expect the standard database files. Retrieval also gives you the versioned, citable artifact that the whole field shares, which matters for reproducibility.

Predict, through ColabFold or a local AlphaFold installation, when your sequence is not in the database, when you need a specific isoform or a construct with mutations rather than the canonical sequence, when you need a predicted complex rather than a single chain, or when you need to sample multiple models to explore conformational uncertainty around a flexible region.

A common and sensible hybrid: retrieve the database model for the canonical chain to anchor your analysis, then predict variants or isoforms locally, using the database model as a reference point for validating your local setup. If a locally predicted model of the canonical sequence broadly reproduces the database model, your local configuration is behaving sensibly, and you can extend it to the sequences the database does not cover with more confidence.

Whichever path you choose, the retrieval skills in this article remain the backbone. Every prediction you make locally still needs the same handling afterward: confidence interpretation, fragment and numbering bookkeeping, and honest separation between what the coordinates support and what your annotations supply.

Frequently Asked Questions

Can I search the AlphaFold database directly by UniProt ID?

Yes. Paste the UniProt accession into the search bar or construct the entry URL as https://alphafold.ebi.ac.uk/entry/{accession}. The accession is the primary key, so exact accessions give immediate unambiguous results.

Why does my UniProt ID return no AlphaFold structure?

The most common causes are a retired or merged accession, an ID from a different database such as RefSeq, or a protein outside the proteomes covered by the database. Verify the accession at uniprot.org, and use a tool that maps alternative identifier types before concluding the structure does not exist.

What is the difference between the PDB and mmCIF downloads?

Both contain the same coordinates. PDB is the legacy text format compatible with nearly every older tool, while mmCIF handles large entries and carries richer metadata. Download PDB for compatibility and mmCIF for large or metadata-heavy work.

What is the PAE JSON file and do I need it?

The PAE file stores predicted aligned errors between every residue pair. You need it when interpreting relative domain orientations, interfaces, or multi-domain flexibility. For a simple visualization of a well-ordered single-domain protein you can skip it.

How do I get an AlphaFold model for an entire proteome rather than one protein?

Use a bulk retrieval service that accepts a taxonomy ID and resolves every protein in that organism to its AlphaFold entry. The AlphaFoldDB Structure Extractor supports taxonomy ID input and downloads structures in the format you specify, with a mapping file to keep the bookkeeping straight.

Can I search by structure instead of by identifier?

Yes. AlphaFind accepts a UniProt ID, PDB ID, or gene symbol and returns structurally similar chains from across the entire database with similarity metrics and superposition views. 3D-AF-Surfer offers real-time fold-level classification using 3D Zernike descriptors.

Are AlphaFold database models experimental structures?

No. They are computational predictions with no associated experimental evidence about ligands, modifications, or assembly state. Confidence scores tell you where the prediction is reliable, but they do not convert a prediction into an experimentally determined structure.

Which confidence score should I check first when I open a model?

Check per-residue pLDDT first, since it is color-coded in the viewer and stored in the B-factor column. High values indicate locally accurate structure. Then check PAE between domains before drawing conclusions about how those domains sit relative to each other.