UniProt, RCSB PDB, and AlphaFold DB

The retrieval layer under every structure-based workflow: sequence in, annotation and coordinates out, plus the checks that decide whether those coordinates are worth using.

Services: rest.uniprot.org · search.rcsb.org · data.rcsb.org · files.rcsb.org · alphafold.ebi.ac.uk. All unauthenticated.

Read references/uniprot-api.md for query and field syntax, references/rcsb-search.md for search attributes and the data API, and references/choosing-a-structure.md before committing to a structure — that one is judgement, not syntax.

The four scripts

Script	Answers
uniprot_fetch.py	What is this protein, what is its sequence, where are its sites, what ids does it map to
rcsb_search.py	Which structures exist, and which are worth downloading
fetch_structure.py	Get the coordinates — experimental, assembly, predicted, or ligand
structure_report.py	Is this file actually usable, and what is missing from it

Sequence and annotation

python skills/uniprot-rcsb/scripts/uniprot_fetch.py entry P00533
python skills/uniprot-rcsb/scripts/uniprot_fetch.py search "gene:EGFR AND organism_id:9606 AND reviewed:true"
python skills/uniprot-rcsb/scripts/uniprot_fetch.py fasta P00533 --isoforms
python skills/uniprot-rcsb/scripts/uniprot_fetch.py features P00533 --types Binding,Active,Mutagenesis
python skills/uniprot-rcsb/scripts/uniprot_fetch.py map P00533 P04637 --to PDB

Put reviewed:true in almost every search. UniProtKB is ~0.5 % Swiss-Prot (curated) and ~99.5 % TrEMBL (automatic); without the flag a gene-name search returns fragments and predicted isoforms above the entry you wanted. The script reports the reviewed/unreviewed split and warns when nothing reviewed matched.

Two UniProt behaviours the script absorbs: pagination lives in the HTTP Link header, not the JSON body — read only the body and you silently get the first page of many — and gzip-encoded responses are sometimes doubly wrapped, so one decompression leaves bytes that fail much later as a UnicodeDecodeError on byte 1.

Finding structures

# what does UniProt already cross-reference, with the residue range each covers?
python skills/uniprot-rcsb/scripts/uniprot_fetch.py pdb P00533 --max-resolution 2.0

# search the PDB properly, with ligands and mutations resolved
python skills/uniprot-rcsb/scripts/rcsb_search.py uniprot P00533 \
    --max-resolution 2.0 --has-ligand --exclude-mutants
python skills/uniprot-rcsb/scripts/rcsb_search.py sequence --fasta target.fasta --identity 0.9
python skills/uniprot-rcsb/scripts/rcsb_search.py ligand STI
python skills/uniprot-rcsb/scripts/rcsb_search.py text "SARS-CoV-2 main protease" --max-resolution 1.5

entityId  pdbId  method             resolution  rFree    ligands  uniprotIds  mutations
3POZ_1    3POZ   X-RAY DIFFRACTION  1.5         0.243    03P      P00533
3W32_1    3W32   X-RAY DIFFRACTION  1.8         0.23552  W32      P00533
2RGP_1    2RGP   X-RAY DIFFRACTION  2           0.268    HYZ      P00533

The RCSB search API returns only identifiers and scores — no resolution, no ligands, no method. Every useful question therefore needs a second service, and the script batches that through the data GraphQL endpoint (one request for 25 hits instead of ~60 REST calls).

Two traps it handles: a search with no hits answers HTTP 204 with an empty body, which json.loads turns into a parse error rather than "nothing matched"; and the default results_content_type includes computational models, so an unqualified search quietly mixes AlphaFold predictions into a list that looks like crystal structures. The script pins experimental.

--has-ligand excludes waters, ions, and crystallisation additives (SO4, GOL, EDO, PEG, MPD, …). Without that exclusion, essentially every crystal structure looks holo.

Downloading

python skills/uniprot-rcsb/scripts/fetch_structure.py pdb 1IEP 3POZ --out-dir structures/
python skills/uniprot-rcsb/scripts/fetch_structure.py assembly 4HHB --assembly 1
python skills/uniprot-rcsb/scripts/fetch_structure.py alphafold P00533 --metadata-only
python skills/uniprot-rcsb/scripts/fetch_structure.py ligand STI --out-dir ligands/

Default to mmCIF. Legacy .pdb does not exist for entries that overflow the 80-column format — large complexes and most recent cryo-EM structures — and files.rcsb.org/download/8ETU.pdb is a 404. The script says so explicitly rather than passing the 404 through.

The asymmetric unit is not the biological unit. Deposited coordinates may hold half a dimer or four copies of a monomer. Use assembly when an interface matters.

AlphaFold output reports the confidence bands before you commit:

# AF-P00533-F1 (Epidermal growth factor receptor)   mean pLDDT: 75.94
band               percent
very high (>90)    47.4
confident (70-90)  23.3
low (50-70)        6.5
very low (<50)     22.8

An excellent kinase domain attached to a disordered tail that is 23 % of the model. Trim to the confident region; a full-length model in a simulation box spends most of its atoms on a prediction nobody makes. And note that PAE, not pLDDT, governs domain arrangement — two confident domains can still have a guessed relative orientation.

Checking a structure before you build on it

python skills/uniprot-rcsb/scripts/structure_report.py 3POZ.cif --gaps-near 750,790,858

## ISSUES
- 24 residues unresolved inside the modelled range (A:734-737,748-754,868-874,1004-1009)
- 10 residues present in the construct but not modelled at the chain termini (A:696-700,1018-1022)
- no hydrogens (normal for X-ray) -- add them at your target pH during receptor preparation
- 126 water atoms present -- decide deliberately which to keep
- chain A: residues of interest are UNRESOLVED: [750]

That last line is the point. 3POZ is a 1.5 Å structure, and a residue in the region you asked about has no coordinates at all — your pocket has a hole in one wall, and every docking score computed against it is optimistic. Resolution does not tell you this; nothing tells you this except looking.

The report reads PDB and mmCIF with no parser dependency, and covers chains and numbering gaps, non-polymer ligands with occupancy, waters and additives, alternate conformations, insertion codes, multiple models, and hydrogens. It reads unresolved residues from REMARK 465 / _pdbx_unobs_or_zero_occ_residues, which is the only way to see terminal truncation — those leave no gap in the numbering, so a report built from coordinates alone calls a truncated construct complete.

Numbering will not line up

UniProt numbers the canonical isoform from 1. A PDB entry carries both auth_seq_id (the depositor's numbering) and label_seq_id (a 1-based construct index), and expression tags and deletions shift both. Map explicitly — via rcsb_polymer_entity_align, or by aligning structure_report.py --sequence output against the UniProt sequence. Never assume residue 790 in the paper is residue 790 in the file.

Composing with the rest of the bundle

• open-targets → this skill: its proteinIds are the UniProt accessions to start from.
• This skill → autodock-vina: a checked receptor plus a reference ligand for the box.
• This skill → boltz: sequences for cofolding when no suitable structure exists.
• This skill → molecular-dynamics / diffdock: coordinates, with the gaps known in advance.
• This skill → esm / antibody-engineering: sequences for language models and numbering.
• chembl uses UniProt accessions as its target key, so target_components__accession=P00533 joins the two directly.

Reporting honestly

Name the PDB id and its resolution, or the AlphaFold model version and its pLDDT distribution. Say whether you used the asymmetric unit or an assembly. Say which residues near the site of interest were unresolved. A structure-based result whose provenance is "the EGFR structure" is not reproducible.