Usage

Client classes for the OLS.

class Client(base_url: str)[source]

A client for an OLS instance.

It wraps the functions to query the OLS such that alternative base URLs can be used.

Initialize the client.

Parameters:

base_url – An optional, custom URL for the OLS API.

get_json(path: str, params: dict[str, Any] | None = None, raise_for_status: bool = True, timeout: float | int | None = None, **kwargs: Any) → Any[source]

Get the response JSON.

get_response(path: str, params: dict[str, Any] | None = None, raise_for_status: bool = True, timeout: float | int | None = None, **kwargs: Any) → Response[source]

Send a GET request the given endpoint.

Parameters:

  • path – The path to query following the base URL, e.g., /ontologies. If this starts with the base URL, it gets stripped.

  • params – Parameters to pass through to requests.get()

  • raise_for_status – If true and the status code isn’t 200, raise an exception

  • timeout – The timeout, defaults to 5 seconds if not given

  • kwargs – Keyword arguments to pass through to requests.get()

Returns:

The response from requests.get()

get_paged(path: str, key: str | None = None, size: int | None = None, sleep: int | None = None, timeout: float | int | None = None) → Iterable[dict[str, Any]][source]

Iterate over all terms, lazily with paging.

Parameters:

  • path – The url to query

  • key – The key to slice from the _embedded field

  • size – The size of each page. Defaults to 500, which is the maximum allowed by the EBI.

  • sleep – The amount of time to sleep between pages. Defaults to none.

  • timeout – The timeout, defaults to 5 seconds if not given. Applied both to initial request and each page

Yields:

A terms in an ontology

Raises:

ValueError – if an invalid size is given

get_ontologies() → Iterable[dict[str, Any]][source]

Get all ontologies.

get_ontology(ontology: str) → dict[str, Any][source]

Get the metadata for a given ontology.

Parameters:

ontology – The name of the ontology

Returns:

The dictionary representing the JSON from the OLS

get_term(ontology: str, iri: str) → dict[str, Any][source]

Get the data for a given term.

Parameters:

  • ontology – The name of the ontology

  • iri – The IRI of a term

Returns:

Results about the term

search(query: str, query_fields: Iterable[str] | None = None, params: dict[str, Any] | None = None) → Any[source]

Search the OLS with the given term.

Parameters:

  • query – The query to search

  • query_fields – Fields to query

  • params – Additional params to pass through to get_json()

Returns:

dict

Returns:

A list of search results

suggest(query: str, ontology: None | str | list[str] = None) → Any[source]

Suggest terms from an optional list of ontologies.

Parameters:

  • query – The query to suggest

  • ontology – The ontology or list of ontologies

Returns:

A list of suggestion results

See also

https://www.ebi.ac.uk/ols/docs/api#_suggest_term

iter_terms(ontology: str, size: int | None = None, sleep: int | None = None, timeout: float | int | None = None) → Iterable[dict[str, Any]][source]

Iterate over all terms, lazily with paging.

Parameters:

  • ontology – The name of the ontology

  • size – The size of each page. Defaults to 500, which is the maximum allowed by the EBI.

  • sleep – The amount of time to sleep between pages. Defaults to 0 seconds.

  • timeout – The timeout, defaults to 5 seconds if not given, applied to each page

Yields:

Terms in the ontology

iter_ancestors(ontology: str, iri: str, size: int | None = None, sleep: int | None = None) → Iterable[dict[str, Any]][source]

Iterate over the ancestors of a given term.

Parameters:

  • ontology – The name of the ontology

  • iri – The IRI of a term

  • size – The size of each page. Defaults to 500, which is the maximum allowed by the EBI.

  • sleep – The amount of time to sleep between pages. Defaults to 0 seconds.

Yields:

the descendants of the given term

iter_hierarchical_ancestors(ontology: str, iri: str, size: int | None = None, sleep: int | None = None) → Iterable[dict[str, Any]][source]

Iterate over the hierarchical of a given term.

Parameters:

  • ontology – The name of the ontology

  • iri – The IRI of a term

  • size – The size of each page. Defaults to 500, which is the maximum allowed by the EBI.

  • sleep – The amount of time to sleep between pages. Defaults to 0 seconds.

Yields:

the descendants of the given term

iter_ancestors_labels(ontology: str, iri: str, size: int | None = None, sleep: int | None = None) → Iterable[str][source]

Iterate over the labels for the descendants of a given term.

Parameters:

  • ontology – The name of the ontology

  • iri – The IRI of a term

  • size – The size of each page. Defaults to 500, which is the maximum allowed by the EBI.

  • sleep – The amount of time to sleep between pages. Defaults to 0 seconds.

Yields:

labels of the descendants of the given term

iter_labels(ontology: str, size: int | None = None, sleep: int | None = None) → Iterable[str][source]

Iterate over the labels of terms in the ontology.

Parameters:

  • ontology – The name of the ontology

  • size – The size of each page. Defaults to 500, which is the maximum allowed by the EBI.

  • sleep – The amount of time to sleep between pages. Defaults to 0 seconds.

Yields:

labels of terms in the ontology

This function automatically wraps the pager returned by the OLS.

iter_hierarchy(ontology: str, size: int | None = None, sleep: int | None = None, timeout: float | int | None = None) → Iterable[tuple[str, str]][source]

Iterate over parent-child relation labels.

Parameters:

  • ontology – The name of the ontology

  • size – The size of each page. Defaults to 500, which is the maximum allowed by the EBI.

  • sleep – The amount of time to sleep between pages. Defaults to 0 seconds.

  • timeout – The timeout, defaults to 5 seconds if not given

Yields:

pairs of parent/child labels

get_description(ontology: str) → str | None[source]

Get the description of a given ontology.

Parameters:

ontology – The name of the ontology

Returns:

The description of the ontology.

get_embedding(ontology: str, iri: str) → list[float][source]

Get the text-based embedding for a term.

class EBIClient[source]

The first-party instance of the OLS.

See also

https://www.ebi.ac.uk/ols4

Initialize the client.

class FraunhoferClient[source]

The Fraunhofer SCAI instance of the OLS.

Warning

Fraunhofer SCAI resources are typically not maintained, do not rely on this.

See also

https://rohan.scai.fraunhofer.de

Initialize the client.

class MonarchClient[source]

The Monarch Initiative instance of the OLS.

See also

https://ols.monarchinitiative.org/

Initialize the client.

class TIBClient[source]

The TIB instance of the OLS.

With its new Terminology Service, TIB Leibniz Information Centre for Science and Technology and University Library provides a single point of access to terminology from domains such as architecture, chemistry, computer science, mathematics and physics.

See also

https://service.tib.eu/ts4tib/

Initialize the client.

class ZBMedClient[source]

The ZB Med instance of the OLS.

See also

https://semanticlookup.zbmed.de/ols

Initialize the client.