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.).

`interactions(filters=None, attributes=None, collapse=None, by_resource=None, view=None, order_by=None, limit=50, offset=0, cursor=None, exact_total=False, include_outofscope_signdir=False)`

Query the interactions, collapsed for the scope asked for.

The summary on every row — source count, references, sign and direction flags — describes the scope this call states, not the whole build. Restricting to one resource therefore changes the counts, which is the point.

Parameters:

Name	Type	Description	Default
`filters`	`dict[str, Any] \| None`	The scope. Accepts `resources`, `exclude_resources`, `interaction_classes`, `organisms`, `datasets`, `license`, `entities`, `entity_annotations` and `attribute_filters`. An unknown resource or dataset name is refused rather than silently ignored.	`None`
`attributes`	`str \| list[str] \| None`	Extra per-interaction attributes to project.	`None`
`collapse`	`str \| None`	Group key for the collapse; `'endpoints'` by default.	`None`
`by_resource`	`str \| None`	Emit a per-resource block on each row.	`None`
`view`	`str \| None`	`'gene'` (default) or `'protein'`; picks which identifiers the endpoint columns carry.	`None`
`order_by`	`str \| None`	Sort key. Sorting on a collapsed value is refused, because it would collapse the whole scope first.	`None`
`limit`	`int`	Rows per page.	`50`
`offset`	`int`	Row offset. Deep offsets are refused; page with `cursor` instead.	`0`
`cursor`	`str \| None`	The `cursor` a previous page returned.	`None`
`exact_total`	`bool`	Count the scope exactly instead of estimating it.	`False`
`include_outofscope_signdir`	`bool`	Also set the sign and direction flags from resources outside the scope, leaving every count describing the scope.	`False`

Returns:

Type	Description
`Any`	A dict with `interactions`, `total`,
`Any`	`total_is_estimate` and, when the page filled,
`Any`	`cursor`.

`interaction_dataset(dataset, **params)`

One registered dataset's interactions.

Sugar for interactions(filters={'datasets': dataset}). The datasets a build carries are listed by interaction_parameters().

Parameters:

Name	Type	Description	Default
`dataset`	`str`	Registered dataset name, e.g. `'liana'` or `'metalinksdb'`.	required
`**params`	`Any`	`resources`, `interaction_classes`, `organism`, `attributes`, `collapse`, `by_resource`, `view`, `limit`, `offset`, `cursor`.	`{}`

Returns:

Type	Description
`Any`	The same page shape as `interactions`.

`interactions_compose(components=None, **payload)`

Assemble a dataset from components, and price the result.

Parameters:

Name	Type	Description	Default
`components`	`list[dict[str, Any]] \| None`	The parameter sets to combine.	`None`
`**payload`	`Any`	The rest of the composition, such as `operation` and `steps`, plus the paging and shape parameters `interactions` accepts.	`{}`

Returns:

Type	Description
`Any`	The same page shape as `interactions`.

`interaction_parameters(**scope)`

The values each query parameter can still take under a scope.

Reachable means reachable: narrowing to one resource leaves the classes that resource publishes, not every class the build knows. Returns no interactions.

Parameters:

Name	Type	Description	Default
`**scope`	`Any`	The same scope parameters `interactions` filters on, passed flat: `resources`, `exclude_resources`, `interaction_classes`, `organism`, `datasets`, `license`, `entities`, `entity_types`, `entity_annotations`, `curation_flags`.	`{}`

Returns:

Type	Description
`Any`	A dict with `parameters`, `parameter_groups`,
`Any`	`folded_columns` and the resolved `scope`.

`interaction_stats(exact_total=False, **scope)`

How much a scope holds, without returning any of it.

Parameters:

Name	Type	Description	Default
`exact_total`	`bool`	Count the scope exactly. Without it the total is the cost governor's estimate, and `total_is_estimate` says which one was answered.	`False`
`**scope`	`Any`	The scope parameters, as for `interaction_parameters`.	`{}`

Returns:

Type	Description
`Any`	A dict with `total`, `total_is_estimate`,
`Any`	`by_resource` and the resolved `scope`.

`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.

Interactions

Query interactions using the default client.

See OmniPath.interactions for details.

One dataset's interactions using the default client.

See OmniPath.interaction_dataset for details.

Compose a dataset using the default client.

See OmniPath.interactions_compose for details.

Reachable parameter values using the default client.

See OmniPath.interaction_parameters for details.

Scope statistics using the default client.

See OmniPath.interaction_stats for details.

Network datasets

The registered datasets, one attribute each.

datasets.liana and datasets.metalinksdb are not written down anywhere in this module. A dataset is a row in the service's registry, so the names are read from the service and turned into attributes here -- which means a build that registers a new dataset serves it through this module without the client being changed or reinstalled.

>>> import omnipath_client as op
>>> op.set_base_url('https://dev3.omnipathdb.org/api')
>>> op.datasets.names()
['liana', 'metalinksdb']
>>> op.datasets.liana.get(limit=100)   # a DataFrame
>>> op.datasets.liana.info()           # what it is made of
>>> op.datasets.liana.stats()          # how much of it there is

Each accessor is a thin view of the general interactions API: get is interaction_dataset, stats is interaction_stats scoped to the one name, and info is that name's row of interaction_parameters. Anything the dataset accessors do not reach -- composing two datasets, excluding a resource, filtering on an annotation -- is reached through those functions directly.

Classes

`Dataset`

One registered dataset, and the three questions asked of it.

Parameters:

Name	Type	Description	Default
`name`	`str`	The name the service registers this dataset under. It is not checked here: the service holds the registry, and it answers for a name it does not know.	required

Functions

`get(backend='auto', limit=50, **params)`

This dataset's interactions, as a DataFrame.

See omnipath_client.datasets.get for the arguments.

`info()`

What this dataset is made of.

Returns:

Type	Description
`dict[str, Any]`	Its registry row: contributing resources, the interaction
`dict[str, Any]`	classes it is restricted to, the attributes it projects by
`dict[str, Any]`	default and the ones it always carries, its collapse mode,
`dict[str, Any]`	and -- for an assembled dataset -- the composition it is
`dict[str, Any]`	built by.

`stats(**scope)`

How much this dataset holds, without fetching any of it.

Parameters:

Name	Type	Description	Default
`**scope`	`Any`	Further restrictions, as `interaction_stats` takes them. Without any, the whole dataset is described.	`{}`

Returns:

Type	Description
`dict[str, Any]`	A dict with `total`, `total_is_estimate` and
`dict[str, Any]`	`by_resource`.

`resources()`

The resources contributing to this dataset.

Returns:

Type	Description
`list[str]`	Their names, as the registry lists them.

`attributes()`

The attributes this dataset projects.

Returns:

Type	Description
`list[str]`	The default attributes together with the ones the dataset
`list[str]`	always carries.

Functions

`names()`

The datasets this service registers.

Returns:

Type	Description
`list[str]`	The registered names, in the order the service reports them.

`info(dataset=None)`

What a dataset is made of, as the registry declares it.

Parameters:

Name	Type	Description	Default
`dataset`	`str \| None`	A dataset name. Without one, every registered dataset is described.	`None`

Returns:

Type	Description
`Any`	The registry row for that dataset, or a list of every row.

Raises:

Type	Description
`OmniPathError`	If the service registers no dataset under this name.

`get(dataset, backend='auto', limit=50, **params)`

One dataset's interactions, as a DataFrame.

Parameters:

Name	Type	Description	Default
`dataset`	`str`	A registered dataset name.	required
`backend`	`BackendType`	DataFrame backend, or `'auto'` for the first installed.	`'auto'`
`limit`	`int`	Rows to fetch. The service pages, so a large number is a large request rather than a stream.	`50`
`**params`	`Any`	Anything else `interaction_dataset` accepts, such as `organism`, `resources`, `view` or `cursor`.	`{}`

Returns:

Type	Description
`Any`	A DataFrame of the interactions on that page.

`getattr(name)`

Serve a registered dataset name as an attribute of this module.

Parameters:

Name	Type	Description	Default
`name`	`str`	The attribute asked for.	required

Returns:

Type	Description
`Dataset`	The dataset of that name.

Raises:

Type	Description
`AttributeError`	If the service registers no such dataset. The message lists what it does register, because the usual cause is a name this build does not carry rather than a typo.

`dir()`

List the datasets alongside this module's own names.

Returns:

Type	Description
`list[str]`	The names, so that tab completion offers the datasets the
`list[str]`	service actually carries.

Configuration

Point the module-level functions at an API.

The service a build is served from is a deployment detail, not a property of the client, so it is set here rather than passed to every call. A development or preview deployment is reached this way, and so is a local one.

The endpoint inventory belongs to the service, so this builds a new default client rather than re-pointing the old one: the parameters each endpoint accepts are read from the service now being addressed.

OMNIPATH_BASE_URL in the environment does the same thing without a call, for a script that should not name a deployment in its source.

Parameters:

Name	Type	Description	Default
`base_url`	`str`	Base URL of the API, e.g. `'https://dev3.omnipathdb.org/api'`.	required

Returns:

Type	Description
`OmniPath`	The new default client, for a caller that wants to hold on to it.

The API the module-level functions currently address.

Returns:

Type	Description
`str`	The base URL in use.

Graph conversion

Build an AnnNet graph from an OmniPath table.

One row is one edge. Two columns name its endpoints, and every other column becomes an attribute of that edge unless edge_attr_cols says otherwise.

Parameters:

Name	Type	Description	Default
`df`	`Any`	Any table narwhals reads: polars, pandas or pyarrow. The relations export and the interaction tables are both read without options, because the column names of each are known.	required
`source_col`	`str \| None`	Which column names the source endpoint. Worked out from the column names when it is not given.	`None`
`target_col`	`str \| None`	Which column names the target endpoint. Worked out from the column names when it is not given.	`None`
`directed_col`	`str \| None`	Which column says whether an edge is directed. A row that says nothing takes `directed`.	`None`
`weight_col`	`str \| None`	Which column carries the weight of an edge. A row that says nothing weighs one.	`None`
`edge_id_col`	`str \| None`	Which column names an edge. The graph names the edge itself when no column does.	`None`
`slice_col`	`str \| None`	Which column places an edge in a slice, for a table that carries more than one condition.	`None`
`slice`	`str \| None`	The slice every edge goes into, where `slice_col` says nothing.	`None`
`directed`	`bool`	The direction an edge takes when the table does not state one.	`True`
`edge_attr_cols`	`list[str] \| None`	Which columns become attributes of an edge. Every column that names no structure, by default.	`None`
`dropna`	`bool`	Skip a row that names no endpoint. Raise on one instead when False.	`True`
`**graph_kwargs`	`Any`	Passed to the AnnNet constructor.	`{}`

Returns:

Type	Description
`AnnNet`	An `annnet.AnnNet`.

Raises:

Type	Description
`ImportError`	If annnet is not installed.
`ValueError`	If the endpoint columns cannot be worked out.

Example::

import omnipath_client as oc

graph = oc.to_annnet(oc.relations(interaction_types='post_translational'))
graph.ncount(), graph.ecount()

Give every node of a graph the annotations OmniPath holds for it.

One node carries one value per source:label pair. A pair with several values carries them joined by a semicolon, in sorted order, so the value is the same however the rows arrived.

Parameters:

Name	Type	Description	Default
`graph`	`AnnNet`	The graph to annotate, changed in place and returned.	required
`annotations`	`Any`	The annotation table to read. Downloaded and cached when not given.	`None`
`sources`	`list[str] \| None`	Which annotation resources to read. Every one, by default.	`None`
`cache_dir`	`str \| None`	Where to keep the downloaded archive.	`None`

Returns:

Type	Description
`AnnNet`	The same graph.

Raises:

Type	Description
`ImportError`	If polars is not installed.

Example::

import omnipath_client as oc

graph = oc.to_annnet(oc.relations())
oc.annotate_nodes(graph, sources=['HGNC', 'UniProt_location'])

Return the OmniPath node annotation archive as a table.

The archive is one large file. It is downloaded once and read from the cache after that, through the same download manager every other request of this package goes through.

Parameters:

Name	Type	Description	Default
`cache_dir`	`str \| None`	Where to keep the archive. The cache of this package, by default.	`None`

Returns:

Type	Description
`Any`	A polars `LazyFrame` over the archive, with the columns
`Any`	`genesymbol`, `source`, `label` and `value`.

Raises:

Type	Description
`ImportError`	If polars is not installed.

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.

Turn a list of JSON records into a DataFrame.

The JSON endpoints answer with records rather than Parquet, so this is the counterpart of _read_parquet for them. Nested values -- the endpoint arrays, the participant list, the attribute document -- are handed to the backend as they are, rather than flattened or stringified, so nothing is lost on the way into the frame.

Parameters:

Name	Type	Description	Default
`records`	`list[dict[str, Any]]`	The records, as the API returned them.	required
`backend`	`BackendType`	Target backend, or `'auto'` to take the first installed.	`'auto'`

Returns:

Type	Description
`Any`	A DataFrame in that backend. An empty record list still gives a
`Any`	frame, so a caller can chain on the result of a query that
`Any`	matched nothing.

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.

full_uniprot controls use of the comprehensive full-UniProt table (all organisms): 'fallback' (default — curated first, full-UniProt only for unresolved IDs), 'never', 'both', 'only'.

Translate multiple identifiers, return union.

Translate, return single result.

Batch translate via POST (for large lists).

full_uniprot controls use of the comprehensive full-UniProt table: 'fallback' (default), 'never', 'both', 'only'.

Translate a DataFrame column via the web service.

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

If the column holds lists of identifiers (one cell = several names, as in a moleculeNames column), every name is translated and the new column holds, per row, the sorted list of unique targets — or, with as_dict=True, a {source: [targets]} dict so you can see which target came from which source. Row count is preserved (expand is ignored for list columns). Scalar columns keep the original behaviour.

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 (overrides the environment).

Return the current base URL for the utils service.

Resolution order: an explicit :func:set_utils_url, the OMNIPATH_UTILS_URL environment variable, then the built-in default (https://utils.omnipathdb.org).

API Reference

Client

Attributes

endpoint_registry property

Functions

entities(backend=None, **filters)

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

annotations(backend=None, **filters)

resolve(identifiers)

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

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

resources()

interactions(filters=None, attributes=None, collapse=None, by_resource=None, view=None, order_by=None, limit=50, offset=0, cursor=None, exact_total=False, include_outofscope_signdir=False)

interaction_dataset(dataset, **params)

interactions_compose(components=None, **payload)

interaction_parameters(**scope)

interaction_stats(exact_total=False, **scope)

ontology_terms(term_ids)

ontology_tree(term_ids)

search_terms(queries, limit=10)

ontologies()

relation_evidence(relation_pk)

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

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)

cache_clear()

fresh()

params(endpoint)

values(endpoint, param)

Module-level functions

High-level helpers

Export endpoints

Interactions

Network datasets

Classes

Dataset

Functions

get(backend='auto', limit=50, **params)

info()

stats(**scope)

resources()

attributes()

Functions

names()

info(dataset=None)

get(dataset, backend='auto', limit=50, **params)

__getattr__(name)

__dir__()

Configuration

Graph conversion

Lookup and slice

Ontology

Cache control

Response parsing

Pivots and aliases

Inventory

Attributes

endpoints property

Functions

load(force_refresh=False)

params(endpoint)

allowed_values(endpoint, param)

Query

Functions

build(endpoint, **params)

Attributes

url property

json_body property

query_params property

path_params property

resolved_url property

Data classes

Exceptions

Classes

OmniPathError

OmniPathAPIError

OmniPathConnectionError

QueryValidationError

UnknownEndpointError

UnknownParameterError

InvalidParameterValueError

`endpoint_registry` `property`

`entities(backend=None, **filters)`

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

`annotations(backend=None, **filters)`

`resolve(identifiers)`

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

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

`resources()`

`interactions(filters=None, attributes=None, collapse=None, by_resource=None, view=None, order_by=None, limit=50, offset=0, cursor=None, exact_total=False, include_outofscope_signdir=False)`

`interaction_dataset(dataset, **params)`

`interactions_compose(components=None, **payload)`

`interaction_parameters(**scope)`

`interaction_stats(exact_total=False, **scope)`

`ontology_terms(term_ids)`

`ontology_tree(term_ids)`

`search_terms(queries, limit=10)`

`ontologies()`

`relation_evidence(relation_pk)`

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

`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)`

`cache_clear()`

`fresh()`

`params(endpoint)`

`values(endpoint, param)`

`Dataset`

`get(backend='auto', limit=50, **params)`

`info()`

`stats(**scope)`

`resources()`

`attributes()`

`names()`

`info(dataset=None)`

`get(dataset, backend='auto', limit=50, **params)`

`getattr(name)`

`dir()`

`endpoints` `property`

`load(force_refresh=False)`

`params(endpoint)`

`allowed_values(endpoint, param)`

`build(endpoint, **params)`

`url` `property`

`json_body` `property`

`query_params` `property`

`path_params` `property`

`resolved_url` `property`

`OmniPathError`

`OmniPathAPIError`

`OmniPathConnectionError`

`QueryValidationError`

`UnknownEndpointError`

`UnknownParameterError`

`InvalidParameterValueError`

`MissingParameterError`

`BackendNotAvailableError`