hpotk.model package

The hpotk.model package provides data structures for working with ontology data.

class hpotk.model.TermId[source]

Bases: object

TermId is an identifier of an ontology concept.

TermId consists of a prefix and id that are separated by a delimiter:

>>> term_id = TermId.from_curie('HP:0001250')
>>> assert term_id.prefix == 'HP'
>>> assert term_id.id == '0001250'

The TermId has a natural ordering which compares two IDs first based on prefix and then value. Both comparisons are lexicographic.

static from_curie(curie: str)[source]

Create a TermId from a compact URI (CURIE).

The prefix and id of a TermId must be separated either by a colon : or an underscore _.

>>> term_id = TermId.from_curie('HP:0001250')
>>> term_id.value
'HP:0001250'

The parsing will forget the original delimiter. The value always joins the prefix and id with :.

>>> ncit = TermId.from_curie('NCIT_C3117')
>>> ncit.value
'NCIT:C3117'

The : has higher priority than _, and it will be used as delimiter.

>>> snomed = TermId.from_curie('SNOMEDCT_US:128613002')
>>> snomed.prefix
'SNOMEDCT_US'
>>> snomed.id
'128613002'
Parameters:

curie – a CURIE str to be parsed.

Returns:

the created TermId.

Raises:

ValueError if the value is mis-formatted.

abstract property id: str

Get id of the ontology concept.

>>> term_id = TermId.from_curie('HP:1234567')
>>> term_id.id
'1234567'
abstract property prefix: str

Get prefix of the ontology concept.

>>> term_id = TermId.from_curie('HP:1234567')
>>> term_id.prefix
'HP'
property value: str

Get concept value consisting of self.prefix and self.value.

>>> term_id = TermId.from_curie('HP:1234567')
>>> term_id.value
'HP:1234567'
class hpotk.model.MinimalTerm[source]

Bases: Identified, Named

MinimalTerm is a data object with the minimal useful information about an ontology concept.

Each term has:

  • identifier - a TermId of the term (thanks to inheriting from Identified)

  • name - a human-friendly name of the term (thanks to inheriting from Named)

  • alt_term_ids - a sequence of alternate identifiers (IDs of obsolete terms that should be replaced by this term)

  • is_obsolete - the obsoletion status

Most of the time, you should get terms from an hpotk.ontology.MinimalOntology. However, MinimalTerm can also be created from scratch using create_minimal_term() if you must do that from whatever reason.

abstract property alt_term_ids: Sequence[TermId]

Get a sequence of identifiers of the ontology concepts that were obsoleted and should be replaced by the concept represented by this Term.

static create_minimal_term(term_id: TermId | str, name: str, alt_term_ids: Iterable[TermId | str], is_obsolete: bool)[source]

Create MinimalTerm from the components.

>>> seizure = MinimalTerm.create_minimal_term(term_id='HP:0001250', name='Seizure',
...                                           alt_term_ids=('HP:0002279', 'HP:0002391'),
...                                           is_obsolete=False)
Parameters:

  • term_id – a TermId or a CURIE str (e.g. ‘HP:0001250’).

  • name – term name (e.g. Seizure) .

  • alt_term_ids – an iterable with term IDs that represent the alternative IDs of the term.

  • is_obsolete – True if the MinimalTerm has been obsoleted, or False otherwise.

Returns:

the created term.

property is_current: bool

Return True if the term is current (not obsolete) and False otherwise.

abstract property is_obsolete: bool

Return True if the term is obsolete (not current) and False otherwise.

class hpotk.model.Term[source]

Bases: MinimalTerm

A comprehensive representation of an ontology concept.

Term has all attributes of the MinimalTerm plus the following:

  • definition - an optional definition of the term, including a comprehensive description and cross-references

  • comment - an optional comment

  • synonyms - an optional sequence of term synonyms

  • cross-references - an optional sequence of cross-references

Most of the time, you should be getting terms from hpotk.ontology.Ontology. However, if you absolutely must craft a term or two by hand, use create_term() function.

abstract property comment: str | None

Get the comment string of the ontology concept.

static create_term(identifier: TermId | str, name: str, alt_term_ids: Iterable[TermId | str], is_obsolete: bool, definition: Definition | str | None, comment: str | None, synonyms: Iterable[Synonym] | None, xrefs: Iterable[TermId] | None)[source]

Create a MinimalTerm from the components.

Parameters:

  • identifier – a TermId or a CURIE (e.g. ‘HP:0001250’).

  • name – term name (e.g. Seizure).

  • alt_term_ids – an iterable with term IDs that represent the alternative IDs of the term.

  • is_obsolete – True if the MinimalTerm has been obsoleted, or False otherwise.

  • definition – an optional str with a definition of the term or a Definition with the full info.

  • comment – an optional comment of the term.

  • synonyms – an optional iterable with all synonyms of the term.

  • xrefs – an optional iterable with all the cross-references.

Returns:

the created term.

current_synonyms() → Iterable[Synonym][source]

Get an iterable with current synonyms of the ontology concept.

The iterable is empty if the concept has no current synonyms.

abstract property definition: Definition | None

Get the definition of the ontology concept.

obsolete_synonyms() → Iterable[Synonym][source]

Get an iterable with obsolete synonyms of the ontology concept.

The iterable is empty if the concept has no obsolete synonyms.

abstract property synonyms: Sequence[Synonym] | None

Get a sequence of all synonyms (including obsolete) of the ontology concept or None if the concept has no synonyms.

abstract property xrefs: Sequence[TermId] | None

Get a sequence of the cross-references of the ontology concept.

class hpotk.model.Identified[source]

Bases: object

A mixin for entities that have an identifier in form of a TermId.

abstract property identifier: TermId

Get the identifier.

class hpotk.model.ObservableFeature[source]

Bases: object

ObservableFeature represents a feature that can be either in a present or an excluded state in the investigated item(s).

The simplest case is the presence or absence of a phenotypic feature, such as hexadactyly, in a study subject.

property is_absent: bool

Test if the feature is excluded.

Deprecated since version 0.2.1: Use is_excluded() instead.

property is_excluded: bool

Test if the feature was not observed in any of the items.

Returns:

True if the feature was observed in none of the annotated item(s), and was, therefore, excluded.

abstract property is_present: bool

Test if the feature was observed in one or more items.

Returns:

True if the feature was observed in one or more items.

class hpotk.model.FrequencyAwareFeature[source]

Bases: ObservableFeature

FrequencyAwareFeature entities describe the frequency of a feature in one or more annotated items.

This is on top of the dichotomous state of ObservableFeature, where the feature is present or excluded.

For instance, we can represent the feature frequency in a collection of items, such as presence of a phenotypic feature, such as hexadactyly, in a cohort.

The absolute counts are accessible via numerator and denominator properties.

IMPORTANT: the implementor must ensure the following invariants:

  • the numerator must be a non-negative int

  • the denominator must be a positive int

Use the convenience static method check_numerator_and_denominator() to check the invariants.

static check_numerator_and_denominator(numerator: int, denominator: int) → None[source]

Check if the numerator and denominator satisfy the requirements described in FrequencyAwareFeature.

Returns:

None if the check passes or raises a ValueError if the numerator or denominator contain invalid values.

abstract property denominator: int

Get the denominator, a positive int representing the total count of annotated items investigated for presence/absence of an annotation.

frequency() → float[source]

Get a float in range \([0, 1]\) representing the ratio of the annotation in the annotated item(s).

property is_excluded: bool

Test if the feature was not observed in any of the items.

Returns:

True if the feature was observed in none of the annotated item(s), and was, therefore, excluded.

property is_present: bool

Test if the feature was observed in one or more items.

Returns:

True if the feature was observed in one or more items.

abstract property numerator: int

Get the numerator, a non-negative int representing the count of annotated items where the annotation was present.

class hpotk.model.Named[source]

Bases: object

A mixin for entities that have human-readable name or a label.

abstract property name: str

Get the label.

class hpotk.model.Versioned[source]

Bases: object

A mixin for entities that may have version.

abstract property version: str | None

Get a version str or None if the version is not available.

class hpotk.model.MetadataAware[source]

Bases: object

A mixin for entities that have metadata.

abstract property metadata: MutableMapping[str, str]

Get a mapping with entity metadata.

static metadata_from_str(value: str) → Mapping[str, str][source]

Load the metadata from str created by metadata_to_str().

metadata_to_str() → str[source]

Dump the metadata to a str.

class hpotk.model.Synonym(name: str, synonym_category: SynonymCategory | None = None, synonym_type: SynonymType | None = None, xrefs: Sequence[TermId] | None = None)[source]

Bases: Named

Synonym represents the information regarding a synonym of an ontology concept.

property category: SynonymCategory | None

Get the synonym category - an instance of SynonymCategory or None.

property name: str

Get the name of the synonym

property synonym_type: SynonymType | None

Get synonym type - an instance of SynonymType or None.

property xrefs: Sequence[TermId] | None

Get a sequence of identifiers of the cross-references of the ontology concept or None if there are none.

class hpotk.model.SynonymType(*values)[source]

Bases: Enum

An enumeration of the synonym types, as provided by Obographs.

is_obsolete() → bool[source]

Returns True if the synonym is obsolete (not current) and False otherwise.

is_current() → bool[source]

Returns True if the synonym is current (not obsolete) and False otherwise.

LAYPERSON_TERM = 1
ABBREVIATION = 2
UK_SPELLING = 3
OBSOLETE_SYNONYM = 4
PLURAL_FORM = 5
ALLELIC_REQUIREMENT = 6
class hpotk.model.SynonymCategory(*values)[source]

Bases: Enum

An enumeration of the synonym categories.

EXACT = 1
RELATED = 2
BROAD = 3
NARROW = 4
class hpotk.model.Definition(definition: str, xrefs: Iterable[str])[source]

Bases: object

Definition includes a definition and the cross-references.

Parameters:

  • definition – a definition, e.g. Abnormally long and slender fingers (“spider fingers”). for Arachnodactyly.

  • xrefs – an iterable with definition cross-references, e.g. (‘https://orcid.org/0000-0002-0736-9199’,) for Arachnodactyly.

property definition: str

Get a str with the term definition.

For instance, Abnormally long and slender fingers (“spider fingers”). for Arachnodactyly.

property xrefs: Sequence[str]

Get definition of cross-references of a definition.

For instance, (‘https://orcid.org/0000-0002-0736-9199’,) for Arachnodactyly.