Skip to content

API Reference

Client

Client for the OmniPath web API.

Parameters:

Name Type Description Default
base_url str

Base URL of the OmniPath API.

 DEFAULT_BASE_URL
backend BackendType

Default DataFrame backend.

 'auto'
cache bool

Whether to cache downloaded files.

 True

Attributes

endpoint_registry property

All registered endpoints.

Functions

entities(backend=None, **filters)

Export entities.

Parameters:

Name Type Description Default
backend BackendType | None

Override the default DataFrame backend.

 None
**filters Any

Filter parameters (entity_ids, entity_types, sources, taxonomy_ids, etc.).

 {}

Returns:

Type Description
Any

A DataFrame of entities.

relations(as_graph=False, backend=None, **filters)

Export relations (interactions, memberships, etc.).

Parameters:

Name Type Description Default
as_graph bool

If True, return an annnet.Graph instead of a DataFrame.

 False
backend BackendType | None

Override the default DataFrame backend.

 None
**filters Any

Filter parameters (sources, predicates, interaction_types, relation_categories, subject_entity_pks, object_entity_pks, etc.).

 {}

Returns:

Type Description
Any

A DataFrame of relations, or an annnet.Graph.

annotations(backend=None, **filters)

Export ontology annotations attached to entities.

Parameters:

Name Type Description Default
backend BackendType | None

Override the default DataFrame backend.

 None
**filters Any

Filter parameters (prefixes, ontology_prefixes, entity_pks).

 {}

Returns:

Type Description
Any

A DataFrame of annotations.

resolve(identifiers)

Resolve free-text identifiers to entity primary keys.

Parameters:

Name Type Description Default
identifiers list[str]

List of identifier strings (UniProt accessions, ChEBI IDs, gene symbols, free-text names, etc.).

 required

Returns:

Type Description
Any

A dict with matches (per-input entity_pk lists) and
Any

entities (full entity records).

entities_slice(filters=None, query='', limit=50, offset=0)

Page through entities with filters and free-text search.

Parameters:

Name Type Description Default
filters dict[str, Any] | None

EntityFilters payload (entity_pks, entity_types, sources, taxonomy_ids, ncbi_tax_id).

 None
query str

Free-text search across canonical identifiers and aliases.

 ''
limit int

Maximum number of rows.

 50
offset int

Row offset.

 0

Returns:

Type Description
Any

A dict with rows, total, limit, offset.

relations_slice(filters=None, query='', limit=50, offset=0)

Page through relations with filters and free-text search.

Parameters:

Name Type Description Default
filters dict[str, Any] | None

RelationFilters payload (sources, predicates, relation_categories, subject_entity_pks, etc.).

 None
query str

Free-text search.

 ''
limit int

Maximum number of rows.

 50
offset int

Row offset.

 0

Returns:

Type Description
Any

A dict with rows, total, limit, offset.

resources()

List the resource catalog with build statistics.

Returns:

Type Description
Any

List of resource records (resource_id, resource_name,
Any

categories, entity_count, interaction_count, etc.).

ontology_terms(term_ids)

Batch lookup of ontology terms.

Parameters:

Name Type Description Default
term_ids list[str]

List of term IDs (e.g. ['GO:0006915']).

 required

Returns:

Type Description
Any

A dict with term information.

ontology_tree(term_ids)

Get merged hierarchy tree for terms.

Parameters:

Name Type Description Default
term_ids list[str]

List of term IDs.

 required

Returns:

Type Description
Any

A tree structure dict.

search_terms(queries, limit=10)

Search ontology terms by name or synonym.

Parameters:

Name Type Description Default
queries list[str]

Search strings.

 required
limit int

Maximum number of results per query.

 10

Returns:

Type Description
Any

A dict with search results.

ontologies()

List all available ontologies.

Returns:

Type Description
Any

A dict with ontology information.

relation_evidence(relation_pk)

Get full evidence for a single relation.

Parameters:

Name Type Description Default
relation_pk int

The relation primary key.

 required

Returns:

Type Description
Any

Evidence data as a dict.

lookup(query, id_types=DEFAULT_ID_TYPES, *, keep_canonical=False)

Resolve free-text or PK input and return enriched entity rows.

Wraps resolve() + entities() and pivots the requested id_types into named columns.

Parameters:

Name Type Description Default
query str | int | Sequence[str | int]

A name, accession, or entity_pk; or a list of any combination thereof. Strings are auto-resolved.

 required
id_types Sequence[str]

Aliases (or raw codes) to surface as columns. See omnipath_client._pivot.ID_ALIASES for the full alias map.

 DEFAULT_ID_TYPES
keep_canonical bool

Retain canonical_identifier and the raw identifiers list-column.

 False

Returns:

Type Description
Any

A polars DataFrame with one row per matched entity_pk.

related(query=None, *, subject=None, object=None, sources=None, predicates=None, relation_categories=None, participant_types=None, id_types=DEFAULT_ID_TYPES, group_by=None, limit=None, keep_canonical=False)

Pull joined relations around a query in one call.

Resolves any string inputs, fetches the matching relations, fetches the entity records for every involved PK, and joins them back into a wide DataFrame with subject_* / object_* columns.

Parameters:

Name Type Description Default
query str | int | Sequence[str | int] | None

Positional argument matching the entity on either side of the relation. Use subject= / object= to pin a direction.

 None
subject str | int | Sequence[str | int] | None

Restrict to relations where this entity is the subject.

 None
object str | int | Sequence[str | int] | None

Restrict to relations where this entity is the object.

 None
sources Sequence[str] | None

Resource IDs to include (e.g. ['foodb', 'hmdb']).

 None
predicates Sequence[str] | None

Predicate filter (e.g. ['has_member']).

 None
relation_categories Sequence[str] | None

Category filter (['interaction', 'membership', 'annotation']).

 None
participant_types Sequence[str] | None

Friendly aliases ('protein', 'small_molecule', …) or raw MI codes.

 None
id_types Sequence[str]

Identifier aliases to pivot as subject_<id> and object_<id> columns.

 DEFAULT_ID_TYPES
group_by str | None

Sort the result by this column (e.g. 'object_canonical_id'); useful when the same entity appears under several pathway IDs.

 None
limit int | None

Truncate the output to this many rows.

 None
keep_canonical bool

Retain canonical_identifier / raw identifiers columns.

 False

Returns:

Type Description
Any

A wide polars DataFrame.

cache_clear()

Remove every cached response (incl. the cached OpenAPI spec). Returns the number of entries removed.

fresh()

Context manager that re-downloads any response touched within the block on first use, then serves subsequent identical requests from the freshly populated cache.

Example::

with client.fresh():
    df = client.related('caffeine', sources=['bindingdb'])

params(endpoint)

Parameters for an endpoint.

values(endpoint, param)

Allowed values for a parameter on an endpoint.

Module-level functions

High-level helpers

Resolve and enrich entities using the default client.

See OmniPath.lookup for details.

Pull joined relations around a query using the default client.

See OmniPath.related for details.

Export endpoints

Export entities using the default client.

See OmniPath.entities for details.

Export relations using the default client.

See OmniPath.relations for details.

Export ontology annotations using the default client.

See OmniPath.annotations for details.

Lookup and slice

Resolve identifiers using the default client.

See OmniPath.resolve for details.

Slice entities using the default client.

See OmniPath.entities_slice for details.

Slice relations using the default client.

See OmniPath.relations_slice for details.

List resources catalog using the default client.

See OmniPath.resources for details.

Ontology

Batch lookup of ontology terms using the default client.

See OmniPath.ontology_terms for details.

Get merged hierarchy tree using the default client.

See OmniPath.ontology_tree for details.

Search ontology terms using the default client.

See OmniPath.search_terms for details.

List ontologies using the default client.

See OmniPath.ontologies for details.

Cache control

Clear the on-disk cache for the default client. Returns the number of entries removed.

Context manager that re-downloads any responses touched within the block (first-touch refresh, then served from the freshly populated cache).

Example::

import omnipath_client as oc
with oc.fresh():
    df = oc.related('caffeine', sources=['bindingdb'])

Response parsing

Parse an API response and convert to the requested backend.

Parameters:

Name Type Description Default
source str | Path | BytesIO

Path to a file or an in-memory buffer.

 required
response_format ResponseFormat

The format of the response data.

 'parquet'
backend BackendType

The target DataFrame backend. Use 'auto' to select the first available backend (tries polars, pandas, pyarrow in order).

 'auto'

Returns:

Type Description
Any

A DataFrame in the requested backend format.

Graph conversion

Convert a relations DataFrame to an annnet Graph.

Maps relation columns to annnet edge format: subject_entity_pk -> source, object_entity_pk -> target. Vertex IDs are entity primary keys; resolve them via OmniPath.entities_slice if you need human-readable labels.

Parameters:

Name Type Description Default
df Any

A relations DataFrame (any backend).

 required

Returns:

Type Description
Any

An annnet.Graph instance.

Pivots and aliases

Pivot the long-form identifiers column into wide columns.

For each alias in id_types the entity's matching identifiers are collected, the shortest value is picked as the representative, and a new column is added.

Parameters:

Name Type Description Default
entities_df Any

A polars DataFrame with at least entity_pk and identifiers columns.

 required
id_types Sequence[str]

Aliases (or raw codes) to pivot into columns.

 DEFAULT_ID_TYPES
prefix str

String prefixed to each new column name (e.g. 'subject_').

 ''
keep_canonical bool

If True, retain the raw canonical_identifier and identifiers columns; otherwise drop them.

 False

Returns:

Type Description
Any

A polars DataFrame with one row per input row and one new
Any

column per requested id_type.

Left-join entities to both sides of a relations table.

Produces subject_* and object_* columns for every id_types entry plus subject_entity_type / object_entity_type. The original relation columns (relation_pk, predicate, relation_category, evidence_count, sources) are preserved.

Parameters:

Name Type Description Default
relations_df Any

A polars DataFrame from OmniPath.relations().

 required
entities_df Any

A polars DataFrame from OmniPath.entities() covering every entity_pk that appears as subject or object.

 required
id_types Sequence[str]

Aliases to pivot.

 DEFAULT_ID_TYPES
keep_canonical bool

Whether to retain canonical_identifier / identifiers columns on each side.

 False

Returns:

Type Description
Any

A wide polars DataFrame.

Inventory

Registry of all known API endpoints and parameters.

Fetches the OpenAPI schema from the server and parses it into endpoint definitions. Falls back to static definitions on failure.

Attributes

endpoints property

All registered endpoints.

Functions

load(force_refresh=False)

Load the inventory from the server or static fallback.

Parameters:

Name Type Description Default
force_refresh bool

If True, bypass any cached inventory and re-fetch.

 False

params(endpoint)

Parameters for a given endpoint.

Parameters:

Name Type Description Default
endpoint str

The endpoint key, e.g. 'exports/interactions/parquet'.

 required

Returns:

Type Description
dict[str, ParamDef]

A dict mapping parameter names to ParamDef instances.

allowed_values(endpoint, param)

Allowed values for a parameter on an endpoint.

Parameters:

Name Type Description Default
endpoint str

The endpoint key.

 required
param str

The parameter name.

 required

Returns:

Type Description
list[str] | None

A list of allowed values, or None if unconstrained.

Query

Builds and validates queries against the API inventory.

Functions

build(endpoint, **params)

Build a validated query.

Parameters:

Name Type Description Default
endpoint str

The endpoint key, e.g. 'exports/interactions/parquet'.

 required
**params Any

Query parameters.

 {}

Returns:

Type Description
Query

A validated Query instance.

Raises:

Type Description
UnknownEndpointError

If the endpoint is not in the inventory.
UnknownParameterError

If a parameter is not recognized.
InvalidParameterValueError

If a value is not in the allowed set.

A validated query for an OmniPath API endpoint.

Attributes

url property

Full URL for this query.

json_body property

JSON request body for POST endpoints.

Returns None for GET endpoints.

query_params property

URL query parameters for GET endpoints.

Returns an empty dict for POST endpoints.

path_params property

Path parameters extracted from the query params.

resolved_url property

URL with path parameters substituted.

Data classes

Definition of a single API endpoint.

Definition of a single endpoint parameter.

Exceptions

Exception hierarchy for omnipath-client.

Classes

OmniPathError

Bases: Exception

Base exception for all omnipath-client errors.

OmniPathAPIError

Bases: OmniPathError

Error returned by the OmniPath API (HTTP 4xx/5xx).

OmniPathConnectionError

Bases: OmniPathError

Network or connection error when contacting the API.

QueryValidationError

Bases: OmniPathError

Base for query parameter validation errors.

UnknownEndpointError

Bases: QueryValidationError

The requested endpoint is not in the inventory.

UnknownParameterError

Bases: QueryValidationError

A parameter name is not recognized for the endpoint.

InvalidParameterValueError

Bases: QueryValidationError

A parameter value is not in the set of allowed values.

MissingParameterError

Bases: QueryValidationError

A required parameter was not provided.

BackendNotAvailableError

Bases: OmniPathError

The requested DataFrame backend is not installed.

Utils: ID Translation

Translate a single identifier via the web service.

Translate multiple identifiers, return union.

Translate, return single result.

Batch translate via POST (for large lists).

Translate a DataFrame column via the web service.

Works with pandas, polars, and pyarrow DataFrames via narwhals.

Translate multiple columns.

List all supported ID types.

Utils: Taxonomy

Resolve organism to all name forms.

Convert any organism identifier to NCBI Taxonomy ID.

Convert any organism identifier to common name.

Convert any organism identifier to Latin name.

List all known organisms.

Utils: Orthology

Translate identifiers to orthologs via the web service.

Translate a DataFrame column to orthologs via the web service.

Utils: Reference Lists

Get a reference list.

Get all Swiss-Prot accessions for an organism.

Get all TrEMBL accessions for an organism.

Check if a UniProt accession is in Swiss-Prot.

Utils: Configuration

Set the base URL for the utils service.

Get the current base URL.