protein-quest

Python package to search/retrieve/filter proteins and protein structures.

It uses

Uniprot Sparql endpoint to search for proteins and their measured or predicted 3D structures.
3D beacon network is used to search for any experimentally determined and predicted structure
Uniprot taxonomy to search for taxonomy.
QuickGO to search for Gene Ontology terms.
gemmi to work with macromolecular models.
dask-distributed to compute in parallel.
cyclopts for command line interface
rocrate-action-recorder for provenance tracking.

The package is used by

protein-detective

An example workflow:

graph TB;
    taxonomy[/Search taxon/] -. taxon_ids .-> searchuniprot[/Search UniprotKB/]
    goterm[/Search GO term/] -. go_ids .-> searchuniprot[/Search UniprotKB/]
    searchuniprot --> |uniprot_accessions|searchpdbe[/Search PDBe/]
    searchuniprot -. uniprot_accessions .-> searchstructures[/Search structures/]
    searchuniprot --> |uniprot_accessions|searchaf[/Search Alphafold/]
    searchuniprot -. uniprot_accessions .-> searchemdb[/Search EMDB/]
    searchuniprot -. uniprot_accessions .-> searchuniprotdetails[/Search UniProt details/]
    searchintactionpartners[/Search interaction partners/] -.-x |uniprot_accessions|searchuniprot
    searchcomplexes[/Search complexes/]
    searchpdbe -. pdb_ids .-> searchpdbequality[Search PDBe quality]
    searchpdbe -->|pdb_ids|fetchpdbe[Retrieve PDBe]
    searchstructures -. pdb_ids .-> fetchpdbe
    searchstructures -. af_ids .-> fetchad
    searchaf --> |uniprot_accessions|fetchad(Retrieve AlphaFold)
    searchemdb -. emdb_ids .->fetchemdb[Retrieve EMDB]
    fetchpdbe -->|mmcif_files| chainfilter{{Filter on chain of uniprot}}
    chainfilter --> |mmcif_files| residuefilter{{Filter on nr of residues}}
    residuefilter -. mmcif_files .-> qualityfilter
    residuefilter --> |mmcif_files| resolutionfilter{{Filter on best resolution per UniProt}}
    fetchad -->|mmcif_files| confidencefilter{{Filter out low confidence}}
    confidencefilter --> |mmcif_files| ssfilter{{Filter on secondary structure}}
    resolutionfilter --> |mmcif_files| ssfilter
    ssfilter -. mmcif_files .-> convert2cif([Convert to cif])
    ssfilter -. mmcif_files .-> convert2uniprot_accessions([Convert to UniProt accessions])
    ssfilter -. mmcif_files .-> convert2clusters([Convert to clusters by UniProt overlap])
    searchpdbequality -. pdb_quality.-> qualityfilter{{Filter on PDBe quality}}
    qualityfilter -. mmcif_files .-> ssfilter
    classDef dashedBorder stroke-dasharray: 5 5;
    goterm:::dashedBorder
    taxonomy:::dashedBorder
    searchemdb:::dashedBorder
    fetchemdb:::dashedBorder
    searchstructures:::dashedBorder
    searchintactionpartners:::dashedBorder
    searchcomplexes:::dashedBorder
    searchuniprotdetails:::dashedBorder
    searchpdbequality:::dashedBorder
    qualityfilter:::dashedBorder
    convert2cif:::dashedBorder
    convert2uniprot_accessions:::dashedBorder
    convert2clusters:::dashedBorder

(Dotted nodes and edges are side-quests.)

Install

pip install protein-quest

Or to use the latest development version:

pip install git+https://github.com/haddocking/protein-quest.git

Usage

The main entry point is the protein-quest command line tool which has multiple subcommands to perform actions.

To use programmaticly, see the Jupyter notebooks and API documentation.

While downloading or copying files it uses a global cache (located at ~/.cache/protein-quest) and hardlinks to save disk space and improve speed. This behavior can be customized with the --no-cache, --cache-dir, and --copy-method command line arguments.

Search Uniprot accessions

protein-quest search uniprot \
    --taxon-id 9606 \
    --reviewed \
    --subcellular-location-uniprot "nucleus" \
    --subcellular-location-go GO:0005634 \
    --molecular-function-go GO:0003677 \
    --limit 100 \
    uniprot_accs.txt

(GO:0005634 is "Nucleus" and GO:0003677 is "DNA binding")

Search for PDBe structures of uniprot accessions

protein-quest search pdbe uniprot_accs.txt pdbe.csv

pdbe.csv file is written containing the the PDB id and chain of each uniprot accession.

Search for Alphafold structures of uniprot accessions

protein-quest search alphafold uniprot_accs.txt alphafold.csv

Search for any structures of uniprot accessions

Use 3D beacon network to search for any type of structure (measured or predicted) of given uniprot accessions.

protein-quest search structure uniprot_accs.txt structures.csv

Or to select sources

protein-quest --prov search structure --raw structures.json \
--source alphafill --source alphafold --source ped --source isoformio \
uniprot_accs.txt structures.txt

Search for EMDB structures of uniprot accessions

protein-quest search emdb uniprot_accs.txt emdbs.csv

To retrieve PDB structure files

protein-quest retrieve pdbe pdbe.csv downloads-pdbe/

To retrieve AlphaFold structure files

protein-quest retrieve alphafold alphafold.csv downloads-af/

For each entry downloads the cif file.

To retrieve structures from `search structure` output

protein-quest retrieve structure structures.csv downloads-structure/

To retrieve EMDB volume files

protein-quest retrieve emdb emdbs.csv downloads-emdb/

To filter AlphaFold structures on confidence

Filter AlphaFoldDB structures based on confidence (pLDDT). Keeps entries with requested number of residues which have a confidence score above the threshold. Also writes pdb files with only those residues.

protein-quest filter confidence \
    --confidence 50 \
    --min-residues 100 \
    --max-residues 1000 \
    ./downloads-af ./filtered

To filter PDBe files on chain of uniprot accession

Make PDBe files smaller by only keeping first chain of found uniprot entry and renaming to chain A.

protein-quest filter chain \
    pdbe.csv \
    ./downloads-pdbe ./filtered-chains

To filter PDBe files on nr of residues

protein-quest filter residue  \
    --min-residues 100 \
    --max-residues 1000 \
    ./filtered-chains ./filtered

To filter structures by best resolution per UniProt accession

protein-quest filter resolution \
  --top 3 \
  ./filtered-chains ./filtered-resolution

Results in 3 lowest resolution structures per UniProt accession copied to ./filtered-resolution directory.

To filter on secondary structure

To filter on structure being mostly alpha helices and have no beta sheets. See the following notebook to determine the ratio of secondary structure elements.

protein-quest filter secondary-structure \
    --ratio-min-helix-residues 0.5 \
    --ratio-max-sheet-residues 0.0 \
    --write-stats filtered-ss-stats.csv \
    ./filtered-chains ./filtered-ss

Search Taxonomy

protein-quest search taxonomy "Homo sapiens" -

Search Gene Ontology (GO)

You might not know what the identifier of a Gene Ontology term is at protein-quest search uniprot. You can use following command to search for a Gene Ontology (GO) term.

protein-quest search go --limit 5 --aspect cellular_component apoptosome -

Search for interaction partners

Use https://www.ebi.ac.uk/complexportal to find interaction partners of given UniProt accession.

protein-quest search interaction-partners Q05471 interaction-partners-of-Q05471.txt

The interaction-partners-of-Q05471.txt file contains uniprot accessions (one per line).

Search for complexes

Given Uniprot accessions search for macromolecular complexes at https://www.ebi.ac.uk/complexportal and return the complex entries and their members.

echo Q05471 | protein-quest search complexes - complexes.csv

The complexes.csv looks like

query_protein,complex_id,complex_url,complex_title,members
Q05471,CPX-2122,https://www.ebi.ac.uk/complexportal/complex/CPX-2122,Swr1 chromatin remodelling complex,P31376;P35817;P38326;P53201;P53930;P60010;P80428;Q03388;Q03433;Q03940;Q05471;Q06707;Q12464;Q12509

Search for UniProt details

To get details (like protein name, sequence length, organism) for a list of UniProt accessions.

protein-quest search uniprot-details uniprot_accs.txt uniprot_details.csv

The uniprot_details.csv looks like:

uniprot_accession,uniprot_id,sequence_length,reviewed,protein_name,taxon_id,taxon_name
A0A087WUV0,ZN892_HUMAN,522,True,Zinc finger protein 892,9606,Homo sapiens

Search and filter for PDBe quality scores

The protein-quest filter resolution command does not work on structures without a resolution (for example those made using NMR). With protein-quest search pdbe-quality we can fetch the quality scores from the wwPDB validation reports and then we can filter on quality with protein-quest filter pdbe-quality.

protein-quest search pdbe-quality ./pdbe.csv ./pdbe.quality.json
protein-quest filter pdbe-quality ./filtered-chains ./pdbe.quality.json ./filtered-quality

Convert structure files to .cif format

Some tools (for example powerfit) only work with .cif files and not *.cif.gz or *.bcif files.

protein-quest convert structures --output-format .cif --output-dir ./filtered-ss-as-cif ./filtered-ss

Or to inject Uniprot accessions into structure files use

protein-quest convert structures --uniprots pdbe.csv --output-dir ./filtered-ss-with-uniprots ./filtered-ss

Convert structure files to UniProt accessions

After running some filters you might want to know which UniProt accessions are still present in the filtered structures.

protein-quest convert uniprot ./filtered-ss uniprot_accs.filtered.txt

Convert structures to clusters

Generate clusters based on UniProt protein residue overlap.

protein-quest convert clusters ./filtered-chains clusters.csv
# Or for more details
protein-quest convert clusters ./filtered-chains clusters.csv --stats stats.csv --condensed-distances distances.csv --linkage-matrix linkage.csv --dendrogram dendrograms

Provenance

You can use protein-quest --prov ... to store provenance information of your CLI invocations in a Research Object crate file called ro-crate-metadata.json.

Model Context Protocol (MCP) server

Protein quest can also help LLMs like Claude Sonnet 4 by providing a set of tools for protein structures.

Protein Quest MCP workflow

To run mcp server you have to install the mcp extra with:

pip install protein-quest[mcp]

The server can be started with:

protein-quest mcp

The mcp server contains an prompt template to search/retrieve/filter candidate structures.

Shell completion

The protein-quest command line tool supports shell completion (tab completion) for bash, zsh, and fish shells using cyclopts.

Initialize shell completion with:

protein-quest --install-completion

This will automatically install completion scripts to the appropriate locations for your shell:

Bash: ~/.local/share/bash-completion/completions/protein-quest
Zsh: ~/.zsh/completions/_protein-quest
Fish: ~/.config/fish/completions/protein-quest.fish

After installation, restart your shell or source your shell configuration file.

Contributing

For development information and contribution guidelines, please see CONTRIBUTING.md.