Quickstart¶

Installation¶

Get it from PyPI:

pip install rcsbsearchapi

Or, download from GitHub

Getting Started¶

Basic Query Construction¶

Full-text search¶

To perform a “full-text” search for structures associated with the term “Hemoglobin”, you can create a TextQuery:

from rcsbsearchapi import TextQuery

# Search for structures associated with the phrase "Hemoglobin"
query = TextQuery(value="Hemoglobin")

# Execute the query by running it as a function
results = query()

# Results are returned as an iterator of result identifiers.
for rid in results:
    print(rid)

Attribute search¶

To perform a search for specific structure or chemical attributes, you can create an AttributeQuery.

from rcsbsearchapi import AttributeQuery

# Construct a query searching for structures from humans
query = AttributeQuery(
    attribute="rcsb_entity_source_organism.scientific_name",
    operator="exact_match",  # Other operators include "contains_phrase", "exists", and more
    value="Homo sapiens"
)

# Execute query and construct a list from results
results = list(query())
print(results)

Refer to the Search Attributes and Chemical Attributes documentation for a full list of attributes and applicable operators.

Alternatively, you can also construct attribute queries with comparative operators using the rcsb_attributes object (which also allows for names to be tab-completed):

from rcsbsearchapi import rcsb_attributes as attrs

# Search for structures from humans
query = attrs.rcsb_entity_source_organism.scientific_name == "Homo sapiens"

# Run query and construct a list from results
results = list(query())
print(results)

Grouping sub-queries¶

You can combine multiple queries using Python bitwise operators.

from rcsbsearchapi import rcsb_attributes as attrs

# Query for human epidermal growth factor receptor (EGFR) structures (UniProt ID P00533)
#  with investigational or experimental drugs bound
q1 = attrs.rcsb_polymer_entity_container_identifiers.reference_sequence_identifiers.database_accession == "P00533"
q2 = attrs.rcsb_entity_source_organism.scientific_name == "Homo sapiens"
q3 = attrs.drugbank_info.drug_groups == "investigational"
q4 = attrs.drugbank_info.drug_groups == "experimental"

# Structures matching UniProt ID P00533 AND from humans
#  AND (investigational OR experimental drug group)
query = q1 & q2 & (q3 | q4)

# Execute query and print first 10 ids
results = list(query())
print(results[:10])

These examples are in operator syntax. You can also make queries in fluent syntax. Learn more about both syntaxes and implementation details in Constructing and Executing Queries.

Supported Search Services¶

The list of supported search service types are listed in the table below. For more details on their usage, see Search Service Types.

Search service	QueryType
Full-text	`TextQuery()`
Attribute (structure or chemical)	`AttributeQuery()`
Sequence similarity	`SequenceQuery()`
Sequence motif	`SequenceMotifQuery()`
Structure similarity	`StructSimilarityQuery()`
Structure motif	`StructMotifQuery()`
Chemical similarity	`ChemSimilarityQuery()`

Learn more about available search services on the RCSB PDB Search API docs.

Jupyter Notebooks¶

A runnable jupyter notebook is available in notebooks/quickstart.ipynb, or can be run online using Google Colab:

An additional Covid-19 related example is in notebooks/covid.ipynb: