Skip to content

Querying the OmniPath Database

This vignette shows how to use omnipath-client to query the OmniPath molecular biology database for relations, annotations, entity records, and ontology terms.

Setup

pip install omnipath-client

import omnipath_client as op

What's in the catalog?

op.resources()
# [{'resource_id': 'bindingdb', ...}, {'resource_id': 'foodb', ...}, ...]

For most analysis questions you only need these two helpers. They auto-resolve free-text inputs, fetch the matching tables, and pivot the requested identifiers into named columns.

Resolve and enrich

# Free-text query → entity records with the IDs you ask for
op.lookup(
    ['caffeine', 'metformin', 'TP53'],
    id_types=['name', 'chebi', 'hmdb', 'uniprot', 'genesymbol'],
)

Joined relations

Not available at the moment

related(), entities(), relations(), annotations() and the paged slices read bulk export endpoints that the OmniPath database service no longer has. An update of the client for the current service is planned. Until then, use lookup() and the network datasets.

# Drug targets for caffeine — positional arg matches either side
op.related(
    'caffeine',
    sources=['bindingdb'],
    id_types=['name', 'uniprot', 'genesymbol'],
)

# Pin direction with subject= or object=
op.related(
    object=['WP253', 'R-HSA-70171'],
    sources=['wikipathways', 'reactome'],
    relation_categories=['annotation'],
    id_types=['name', 'uniprot', 'chebi'],
    group_by='object_name',
)

# Filter participants by friendly type alias
op.related(
    'metformin',
    sources=['signor'],
    participant_types=['protein'],
)

Lower-level primitives

Not available at the moment

related(), entities(), relations(), annotations() and the paged slices read bulk export endpoints that the OmniPath database service no longer has. An update of the client for the current service is planned. Until then, use lookup() and the network datasets.

When the wrappers don't fit, use the export endpoints directly.

Entities

# All human entities
df = op.entities(taxonomy_ids=['9606'])

# Filter by source
df = op.entities(sources=['hmdb'])

# Lookup by primary key
df = op.entities(entity_pks=['1568012', '8584'])

Relations

# All relations from one source
df = op.relations(sources=['signor'])

# Relations involving a specific entity_pk
df = op.relations(entity_pks=['2119890'])         # either side
df = op.relations(subject_entity_pks=['2401277']) # outgoing
df = op.relations(object_entity_pks=['2233186'])  # incoming

# Filter by predicate or category
df = op.relations(predicates=['interacts_with'])
df = op.relations(relation_categories=['membership'])

Annotations

df = op.annotations(prefixes=['chebi'])

Free-text resolution and paged slices

# Resolve names/aliases to entity_pks
op.resolve(['caffeine', 'TP53', 'WP253'])

# Page through entities with a free-text query
op.entities_slice(query='glucose', limit=20)

Ontology

# Look up ontology terms by ID
df = op.ontology_terms(['GO:0006915', 'GO:0012501'])

# Search ontology terms by name across ontologies
op.search_terms(['glycolysis', 'apoptosis'])

# Hierarchy tree
tree = op.ontology_tree(['GO:0006915'])

Backends

By default, results are returned as polars DataFrames. You can choose pandas or pyarrow:

client = op.OmniPath(backend='pandas')
df = client.relations(sources=['signor'])
# Returns pandas DataFrame

Cache control

# First-touch refresh inside the block; subsequent identical
# requests within the same block hit the freshly cached entry
with op.fresh():
    df = op.related('caffeine', sources=['bindingdb'])

# Wipe the on-disk cache (incl. the OpenAPI spec)
op.cache_clear()

Custom server

client = op.OmniPath(base_url='http://localhost:8082/api')

Further resources