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.

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

Export interactions.

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 (entity_ids, interaction_types, direction, sign, etc.).	{}

Returns:

Type	Description
Any	A DataFrame of interactions, or an annnet.Graph.

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

Export associations (complexes, pathways, reactions).

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 (parent_entity_ids, member_entity_ids, etc.).	{}

Returns:

Type	Description
Any	A DataFrame of associations, or an annnet.Graph.

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.

interaction_evidence(interaction_id)

Get full evidence for a single interaction.

Parameters:

Name	Type	Description	Default
interaction_id	int	The interaction ID.	required

Returns:

Type	Description
Any	Evidence data as a dict.

association_evidence(association_id)

Get full evidence for a single association.

Parameters:

Name	Type	Description	Default
association_id	int	The association ID.	required

Returns:

Type	Description
Any	Evidence data as a dict.

params(endpoint)

Parameters for an endpoint.

values(endpoint, param)

Allowed values for a parameter on an endpoint.

Module-level functions

Export entities using the default client.

See OmniPath.entities for details.

Export interactions using the default client.

See OmniPath.interactions for details.

Export associations using the default client.

See OmniPath.associations for details.

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.

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 an interactions DataFrame to an annnet Graph.

Maps interaction columns to annnet edge format: member_a_id -> source, member_b_id -> target.

Parameters:

Name	Type	Description	Default
df	Any	An interactions DataFrame (any backend).	required

Returns:

Type	Description
Any	An annnet.Graph instance.

Convert an associations DataFrame to an annnet Graph.

Associations represent parent-member relationships (complexes, pathways, reactions).

Parameters:

Name	Type	Description	Default
df	Any	An associations DataFrame (any backend).	required

Returns:

Type	Description
Any	An annnet.Graph instance.

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.