Skip to content

Commit

Permalink
Improve the documentation.
Browse files Browse the repository at this point in the history
  • Loading branch information
@ielis
ielis committed Mar 13, 2024
1 parent 251f77e commit 77e512c
Show file tree
Hide file tree
Showing 3 changed files with 140 additions and 110 deletions.
1 change: 1 addition & 0 deletions docs/user-guide/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ This guide includes self-contained tutorials for using HPO toolkit to work with
:caption: Contents:

load-ontology
use-ontology
use-hierarchy
load-hpo-annotations
validate-phenotypic-features
Expand Down
116 changes: 6 additions & 110 deletions docs/user-guide/load-ontology.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -60,9 +60,9 @@ to prevent downloading a HPO release more than once, to save time spent during s

The store will download the ontology file the first time a release (e.g. `v2023-10-09`) is requested, and subsequent
loads will skip the download. The `release` must be a release tag, as defined
on `HPO release page<https://github.com/obophenotype/human-phenotype-ontology/releases>`_.
in the tag section of the `HPO release page <https://github.com/obophenotype/human-phenotype-ontology/tags>`_.

Moreover, `OntologyStore` can get you a latest release by *not* specifying the `release` option.
Moreover, `OntologyStore` will load the *latest* release, if the `release` option is omitted.

.. doctest:: load-minimal-ontology

Expand All @@ -73,112 +73,8 @@ Moreover, `OntologyStore` can get you a latest release by *not* specifying the `
As of the time of this writing, ``2024-03-06`` is the latest HPO release.


Quick overview
**************

Here we provide a quick walkthrough of the basic functionality of an ontology.

Minimal ontology
^^^^^^^^^^^^^^^^

Having `MinimalOntology`, we can do several checks. We can check the HPO version:

.. doctest:: load-minimal-ontology

>>> hpo.version
'2023-10-09'

check that the Oct 9th release has *17,664* terms:

.. doctest:: load-minimal-ontology

>>> len(hpo)
17664

check that `HP:0001250` is/was a valid identifier:

.. doctest:: load-minimal-ontology

>>> 'HP:0001250' in hpo
True

check that `HP:0001250` in fact represents *Seizure*:

.. doctest:: load-minimal-ontology

>>> seizure = hpo.get_term('HP:0001250')
>>> seizure.name
'Seizure'

or print names of its children in alphabetical order:

.. doctest:: load-minimal-ontology

>>> for child in sorted(hpo.get_term_name(child)
... for child in hpo.graph.get_children(seizure)):
... print(child)
Bilateral tonic-clonic seizure
Dialeptic seizure
Focal-onset seizure
Generalized-onset seizure
Infection-related seizure
Maternal seizure
Motor seizure
Neonatal seizure
Nocturnal seizures
Non-motor seizure
Reflex seizure
Status epilepticus
Symptomatic seizures

The terms of :class:`hpotk.ontology.MinimalOntology` are instances of :class:`hpotk.model.MinimalTerm` and contain a subset
of the term metadata such as identifier, labels, and alternative IDs. The simplified are useful for tasks that
use the ontology hierarchy. However, the tasks that need the full term metadata should use `Ontology`.

Ontology
^^^^^^^^

Unsurprisingly, loading ontology is very similar to loading minimal ontology. We use `hpotk.load_ontology`
loader function:

.. testsetup:: load-ontology

import hpotk
url = 'https://github.com/obophenotype/human-phenotype-ontology/releases/download/v2023-10-09/hp.json'

.. doctest:: load-ontology

>>> hpo = hpotk.load_ontology(url)
>>> hpo.version
'2023-10-09'

Same as above, the loader parses the Obographs JSON file and returns an ontology. However, this time
it is an instance :class:`hpotk.ontology.Ontology` with :class:`hpotk.model.Term` - the term with full metadata.

So, now we can access the definition of the seizure:

.. doctest:: load-ontology

>>> seizure = hpo.get_term('HP:0001250')
>>> definition = seizure.definition
>>> definition.definition
'A seizure is an intermittent abnormality of nervous system physiology characterised by a transient occurrence of signs and/or symptoms due to abnormal excessive or synchronous neuronal activity in the brain.'
>>> definition.xrefs
('https://orcid.org/0000-0002-0736-9199', 'PMID:15816939')


or check out seizure's synonyms:

.. doctest:: load-ontology

>>> for synonym in seizure.synonyms:
... print(synonym.name)
Epileptic seizure
Seizures
Epilepsy

.. note::

Since `Ontology` is a subclass of `MinimalOntology`, any function that needs `MinimalOntology` will work just fine
when provided with `Ontology`.
Next steps
**********

Loading an ontology is a prerequisite for doing anything useful with the ontology data. Check out
the :ref:`use-ontology` section for an overview of the functionality.
133 changes: 133 additions & 0 deletions docs/user-guide/use-ontology.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,133 @@
.. _use-ontology:

============
Use ontology
============

HPO toolkit simplifies working with Human Phenotype Ontology from Python by providing APIs
for accessing the ontology data. Here we show how to access the data.

We assume the reader is familiar with loading ontology from an Obographs JSON file as described
in the :ref:`rstload-ontology` section.

HPO toolkit represents the ontology data either as :class:`hpotk.ontology.MinimalOntology`
or as its subclass :class:`hpotk.ontology.Ontology`.
The two classes are mostly equivalent but the `MinimalOntology` terms contain less metadata than the `Ontology` terms.
We recommend using `MinimalOntology` for applications that mostly care about the ontology hierarchy and
`Ontology` is suitable for applications that use definitions, synonyms, or cross-references of the ontology terms,
such as natural language processing applications.


Minimal ontology
^^^^^^^^^^^^^^^^

Let's see what we can do with a `MinimalOntology`.

We start with loading the version `v2023-10-09` using :class:`hpotk.util.store.OntologyStore`:

.. doctest:: load-minimal-ontology

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

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

We can check the HPO version:

.. doctest:: load-minimal-ontology

>>> hpo.version
'2023-10-09'

check that the release has *17,664* terms:

.. doctest:: load-minimal-ontology

>>> len(hpo)
17664

check that `HP:0001250` is/was a valid term id:

.. doctest:: load-minimal-ontology

>>> 'HP:0001250' in hpo
True

check that `HP:0001250` in fact represents *Seizure*:

.. doctest:: load-minimal-ontology

>>> seizure = hpo.get_term('HP:0001250')
>>> seizure.name
'Seizure'

or print the names of its children in alphabetical order:

.. doctest:: load-minimal-ontology

>>> for child in sorted(hpo.get_term_name(child)
... for child in hpo.graph.get_children(seizure)):
... print(child)
Bilateral tonic-clonic seizure
Dialeptic seizure
Focal-onset seizure
Generalized-onset seizure
Infection-related seizure
Maternal seizure
Motor seizure
Neonatal seizure
Nocturnal seizures
Non-motor seizure
Reflex seizure
Status epilepticus
Symptomatic seizures

The terms of :class:`hpotk.ontology.MinimalOntology` are instances of :class:`hpotk.model.MinimalTerm` and contain a subset
of the term metadata such as identifier, labels, and alternative IDs. The simplified are useful for tasks that
use the ontology hierarchy.

Ontology
^^^^^^^^

Unsurprisingly, loading ontology is very similar to loading minimal ontology. Same as above,
we use :class:`hpotk.util.store.OntologyStore`:

.. doctest:: load-ontology

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

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

Same as above, the ontology store will check the local cache for the ontology data file of the requested release
and fetch the file from HPO release page if missing. Then, the file is parsed into :class:`hpotk.ontology.Ontology`,
where the ontology terms are represented as :class:`hpotk.model.Term`.

Thanks to the additional metadata present in a `Term`, we can also access the definition of the *Seizure*:

.. doctest:: load-ontology

>>> seizure = hpo.get_term('HP:0001250')
>>> definition = seizure.definition
>>> definition.definition
'A seizure is an intermittent abnormality of nervous system physiology characterised by a transient occurrence of signs and/or symptoms due to abnormal excessive or synchronous neuronal activity in the brain.'
>>> definition.xrefs
('https://orcid.org/0000-0002-0736-9199', 'PMID:15816939')

or its synonyms:

.. doctest:: load-ontology

>>> for synonym in seizure.synonyms:
... print(synonym.name)
Epileptic seizure
Seizures
Epilepsy

.. note::

Since `Ontology` is a subclass of `MinimalOntology`, any function that needs `MinimalOntology` will work just fine
when provided with `Ontology`.

0 comments on commit 77e512c

Please sign in to comment.