Quickstart
This guide covers the basic usage of omnipath-client.
Setup
High-level helpers
Two helpers, lookup() and related(), fold the common
resolve → fetch → join pattern into a single call. They accept
friendly id-type aliases (name, chebi, hmdb, uniprot,
genesymbol, kegg, pubchem, drugbank, chembl, cas,
inchi, inchikey, smiles, lipidmaps, swisslipids, entrez,
ensembl, iupac, …) that the client maps to the underlying MI/OM
ontology codes. When an entity has several values for the same
id type, the shortest is picked as the representative.
lookup()
Resolve a name (or list of names / primary keys) and pivot the requested IDs into named columns:
op.lookup(
['caffeine', 'metformin', 'glucose'],
id_types=['name', 'chebi', 'hmdb', 'kegg', 'drugbank'],
)
# query entity_pk entity_type name chebi hmdb kegg drugbank
# caffeine 2119890 MI:0328:Small Molecule caffeine 27732 HMDB0001847 C07481 DB00201
# metformin 1568012 MI:0328:Small Molecule metformin 6801 HMDB0001921 C07151 DB00331
# ...
Default id_types is ("name", "chebi", "hmdb", "uniprot",
"genesymbol") — narrow enough to keep output readable, broad enough
for most downstream joins.
related()
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.
Pull a wide, joined relations table around a query in one call:
# Compounds reported in strawberry (FooDB)
op.related(
subject='Strawberry',
sources=['foodb'],
id_types=['name', 'chebi', 'hmdb'],
)
# Drug targets for caffeine (positional argument matches either side
# of the relation; subject= / object= pin a direction)
op.related(
'caffeine',
sources=['bindingdb'],
id_types=['name', 'uniprot', 'genesymbol'],
)
# Pathway members from WikiPathways and Reactome at once
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'],
id_types=['name', 'uniprot'],
)
Filters: sources, predicates, relation_categories,
participant_types. Layout: subject= / object= pin direction,
group_by= reorders rows (handy when one entity appears under several
pathway IDs), limit= truncates the output.
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.
The wrappers are thin — when you need raw tables, paged access, or graph export, reach for the primitives directly.
Resolve identifiers
op.resolve(['caffeine', 'TP53', 'WP253'])
# {'matches': [{'identifier': 'caffeine', 'entityPks': [2119890]}, ...],
# 'entities': [...]}
Entities
# All entities
df = op.entities()
# Filter by organism (NCBI taxonomy ID 9606 = human)
df = op.entities(taxonomy_ids=['9606'])
# Filter by source database
df = op.entities(sources=['hmdb'])
# Lookup by primary key
df = op.entities(entity_pks=['1568012', '8584'])
Relations
# All relations
df = op.relations()
# Filter by source resource
df = op.relations(sources=['signor'])
# Filter by predicate or relation category
df = op.relations(predicates=['interacts_with'])
df = op.relations(relation_categories=['membership'])
# Constrain by entity primary keys
df = op.relations(subject_entity_pks=['2401277']) # outgoing
df = op.relations(object_entity_pks=['2233186']) # incoming
df = op.relations(entity_pks=['2119890']) # either side
Annotations
Paged slices
# Page through entities with free-text search
op.entities_slice(query='glucose', limit=20)
# Same for relations
op.relations_slice(filters={'sources': ['signor']}, limit=50)
Choosing a DataFrame backend
By default, results are returned as polars DataFrames. You can choose a different backend:
# pandas DataFrame
df = op.entities(backend='pandas')
# pyarrow Table
table = op.entities(backend='pyarrow')
To set the default backend for all queries, use the OO client:
Graph conversion
Relations can be returned as annnet graph objects:
Node IDs are entity primary keys. Resolve them through op.entities()
or op.lookup() when you need readable labels.
op.to_annnet builds a graph from any interaction table, so a table you
already hold, or one from another OmniPath service, becomes a graph too:
g = op.to_annnet(df)
g = op.to_annnet(df, source_col='source_genesymbol', target_col='target_genesymbol')
One row is one edge. Two columns name its endpoints, and every other column becomes an attribute of that edge.
op.annotate_nodes gives every node of a graph what OmniPath knows about
it. The annotation archive is downloaded once and read from the cache
after that:
Ontology endpoints
Look up ontology terms, search by name, or build hierarchy trees:
# Batch term lookup
result = op.ontology_terms(['GO:0006915', 'MI:0326'])
# Search terms by name (returns ranked hits across ontologies)
result = op.search_terms(['glycolysis', 'apoptosis'])
# Get a merged hierarchy tree
tree = op.ontology_tree(['GO:0006915'])
# List available ontologies
ontologies = op.ontologies()
Resource catalog
# What sources are available, and what each one contributes
op.resources()
# [{'resource_id': 'bindingdb', 'resource_name': 'BindingDB', 'categories': ['interaction']},
# {'resource_id': 'foodb', 'resource_name': 'FooDB', 'categories': ['membership']},
# ...]
Cache control
Responses are cached on disk by default. Two helpers manage the cache:
# Force a one-shot refresh for everything touched inside the block.
# Subsequent identical requests within the same block are served from
# the freshly populated cache.
with op.fresh():
df = op.related('caffeine', sources=['bindingdb'])
# Wipe the entire on-disk cache (incl. the OpenAPI spec) — useful
# after a server redeploy renames endpoints or changes the schema.
op.cache_clear()
Introspection
Explore available endpoints, parameters, and allowed values:
# All endpoints
op.endpoints()
# Parameters for an endpoint
op.params('exports/relations/parquet')
# Allowed values for a parameter (None when free-form)
op.values('exports/entities/parquet', 'entity_types')
# ['MI:0326:Protein', 'MI:0328:Small Molecule', ...]
Custom API URL
To use a different API server (e.g. a local instance):