hpotk.store package

The hpotk.store package provides OntologyStore - a class for local caching of ontology data.

The ontology store should be configured using hpotk.configure_ontology_store() function:

>>> import hpotk
>>> store = hpotk.configure_ontology_store()

The store can then be used to fetch an ontology with a given release, e.g. v2023-10-09:

>>> hpo = store.load_minimal_hpo(release='v2023-10-09')
>>> hpo.version
'2023-10-09'

or fetch the latest release by omitting the release argument:

>>> latest_hpo = store.load_minimal_hpo()  
>>> latest_hpo.version  
'2024-04-26'

Note

The release 2024-04-26 is the latest release as of June 2024 when this documentation was written.

hpotk.store.configure_ontology_store(store_dir: str | None = None, ontology_release_service: ~hpotk.store._api.OntologyReleaseService = <hpotk.store._github.GitHubOntologyReleaseService object>, remote_ontology_service: ~hpotk.store._api.RemoteOntologyService = <hpotk.store._github.GitHubRemoteOntologyService object>) → OntologyStore[source]

Configure and create the default ontology store.

Parameters:

  • store_dir – a str pointing to an existing directory for caching the ontology files or None if the platform-specific default folder should be used.

  • ontology_release_service – an OntologyReleaseService for fetching the ontology releases.

  • remote_ontology_service – a RemoteOntologyService responsible for fetching the ontology data from a remote location if we do not have the data locally.

Returns:

an OntologyStore.

Raises:

ValueError if something goes wrong.

class hpotk.store.OntologyType(value)[source]

Bases: Enum

Enum with the ontologies supported by the OntologyStore.

HPO = 'HPO'

Human Phenotype Ontology.

MAxO = 'MAxO'

Medical Action Ontology.

MONDO = 'MONDO'

Mondo Disease Ontology.

property identifier: str

Get a str with the ontology identifier (e.g. HP for HPO).

>>> from hpotk.store import OntologyType
>>> OntologyType.HPO.identifier
'HP'
>>> OntologyType.MAxO.identifier
'MAXO'
class hpotk.store.OntologyStore(store_dir: str, ontology_release_service: OntologyReleaseService, remote_ontology_service: RemoteOntologyService)[source]

Bases: object

OntologyStore stores versions of the supported ontologies.

load_minimal_ontology(ontology_type: OntologyType, release: str | None = None, **kwargs) → MinimalOntology[source]

Load a release of a given ontology_type as a minimal ontology.

Parameters:

  • ontology_type – the desired ontology type, see OntologyType for a list of supported ontologies.

  • release – a str with the ontology release tag or None if the latest ontology should be fetched.

  • kwargs – key-value arguments passed to the low-level loader function (currently load_minimal_ontology()).

Returns:

a minimal ontology.

load_ontology(ontology_type: OntologyType, release: str | None = None, **kwargs) → Ontology[source]

Load a release of a given ontology_type as an ontology.

Parameters:

  • ontology_type – the desired ontology type, see OntologyType for a list of supported ontologies.

  • release – a str with the ontology release tag or None if the latest ontology should be fetched.

  • kwargs – key-value arguments passed to the low-level loader function (currently load_ontology()).

Returns:

an ontology.

Raises:

ValueError – if the release corresponds to a non-existing ontology release.

property store_dir: str

Get a str with a platform specific absolute path to the data directory.

The data directory points to $HOME/.hpo-toolkit on UNIX and $HOME/hpo-toolkit on Windows. The folder is created if it does not exist.

load_minimal_hpo(release: str | None = None) → MinimalOntology[source]

A convenience method for loading a specific HPO release.

Parameters:

release – an optional str with the desired HPO release (if None, the latest HPO will be provided).

Returns:

a hpotk.MinimalOntology with the HPO data.

Raises:

ValueError – if the release corresponds to a non-existing HPO release.

load_hpo(release: str | None = None) → Ontology[source]

A convenience method for loading a specific HPO release.

Parameters:

release – an optional str with the desired HPO release (if None, the latest HPO will be provided).

Returns:

a hpotk.Ontology with the HPO data.

Raises:

ValueError – if the release corresponds to a non-existing HPO release.

clear(ontology_type: OntologyType | None = None)[source]

Clear all ontology resources or resources of selected ontology_type.

Parameters:

ontology_type – the ontology to be cleared or None if resources of all ontologies should be cleared.

resolve_store_path(ontology_type: OntologyType, release: str | None = None) → str[source]

Resolve the path of the ontology resource (e.g. HPO hp.json file) within the ontology store.

Note, the path points to the location of the ontology resource in the local filesystem. The path may point to a non-existing file, if the load function has not been run yet.

Example

>>> import hpotk
>>> store = hpotk.configure_ontology_store()
>>> store.resolve_store_path(hpotk.store.OntologyType.HPO, release='v2023-10-09')  
'/home/user/.hpo-toolkit/HP/hp.v2023-10-09.json'
Parameters:

  • ontology_type – the desired ontology type, see OntologyType for a list of supported ontologies.

  • release – an optional str with the desired ontology release (if None, the latest ontology will be provided).

Returns:

a str with path to the ontology resource.

class hpotk.store.RemoteOntologyService[source]

Bases: object

RemoteOntologyService knows how to open a typing.BinaryIO for reading content of an ontology_type of a particular release.

abstract fetch_ontology(ontology_type: OntologyType, release: str) → BufferedIOBase[source]

Open a connection for reading bytes of the ontology_type from a remote resource.

Parameters:

  • ontology_type – the desired ontology kind, e.g. OntologyType.HPO.

  • release – a str with the desired ontology release.

Returns:

a binary IO for reading the ontology data.

class hpotk.store.OntologyReleaseService[source]

Bases: object

OntologyReleaseService knows how to fetch ontology release tags, such as v2023-10-09 for HPO.

abstract fetch_tags(ontology_type: OntologyType) → Iterable[str][source]

Fetch sequence of tags for an ontology.

Parameters:

ontology_type – the target ontology type.

Returns:

class hpotk.store.GitHubRemoteOntologyService(timeout: int = 10, ontology_credentials: Mapping[OntologyType, Mapping[str, str]] = {OntologyType.HPO: {'owner': 'obophenotype', 'repo': 'human-phenotype-ontology'}, OntologyType.MAxO: {'owner': 'monarch-initiative', 'repo': 'MAxO'}, OntologyType.MONDO: {'owner': 'monarch-initiative', 'repo': 'mondo'}})[source]

Bases: RemoteOntologyService

GitHubRemoteOntologyService knows how to fetch ontology data from GitHub.

The Obographs JSON files are fetched and only HPO is supported as of now.

fetch_ontology(ontology_type: OntologyType, release: str) → BufferedIOBase[source]

Open a connection for reading bytes of the ontology_type from a remote resource.

Parameters:

  • ontology_type – the desired ontology kind, e.g. OntologyType.HPO.

  • release – a str with the desired ontology release.

Returns:

a binary IO for reading the ontology data.

class hpotk.store.GitHubOntologyReleaseService(timeout: int = 10, ontology_credentials: Mapping[OntologyType, Mapping[str, str]] = {OntologyType.HPO: {'owner': 'obophenotype', 'repo': 'human-phenotype-ontology'}, OntologyType.MAxO: {'owner': 'monarch-initiative', 'repo': 'MAxO'}, OntologyType.MONDO: {'owner': 'monarch-initiative', 'repo': 'mondo'}})[source]

Bases: OntologyReleaseService

GitHubOntologyReleaseService can fetch the ontology tags from GitHub.

fetch_tags(ontology_type: OntologyType) → Iterable[str][source]

Fetch sequence of tags for an ontology.

Parameters:

ontology_type – the target ontology type.

Returns: