Term

class pronto.Term[source]

A term, corresponding to a node in the ontology graph.

Formally a Term frame is equivalent to an owl:Class declaration in OWL2 language. However, some constructs may not be possible to express in both OBO and OWL2.

Term should not be manually instantiated, but obtained from an existing Ontology instance, using either the create_term or the get_term method.

classmethod __class_getitem__(params)

Parameterizes a generic class.

At least, parameterizing a generic class is the main thing this method does. For example, for some generic class Foo, this is called when we do Foo[int] - there, with cls=Foo and params=int.

However, note that this method is also called when defining generic classes in the first place with class Foo(Generic[T]): ....

__eq__(other: Any) bool

Return self==value.

__ge__(other)

Return self>=value.

__gt__(other)

Return self>value.

__hash__()

Return hash(self).

__le__(other)

Return self<=value.

__lt__(other)

Return self<value.

__repr__()

Return repr(self).

add_synonym(description: str, scope: str | None = None, type: SynonymType | None = None, xrefs: Iterable[Xref] | None = None) Synonym

Add a new synonym to the current entity.

Parameters:
  • description (str) – The alternate definition of the entity, or a related human-readable synonym.

  • scope (str or None) – An optional synonym scope. Must be either EXACT, RELATED, BROAD or NARROW if given.

  • type (SynonymType or None) – An optional synonym type. Must be declared in the header of the current ontology.

  • xrefs (iterable of Xref, or None) – A collections of database cross-references backing the origin of the synonym.

Raises:

ValueError – when given an invalid synonym type or scope.

Returns:

Synonym – A new synonym for the terms. The synonym is already added to the Entity.synonyms collection.

property alternate_ids: Set[str]

A set of alternate IDs for this entity.

Type:

set of str

property annotations: Set[PropertyValue]

Annotations relevant to the entity.

Type:

set of PropertyValue

property anonymous: bool

Whether or not the entity has an anonymous id.

Semantics of anonymous entities are the same as B-Nodes in RDF.

Type:

bool

property builtin: bool

Whether or not the entity is built-in to the OBO format.

pronto uses this tag on the is_a relationship, which is the axiomatic to the OBO language but treated as a relationship in the library.

Type:

bool

property comment: str | None

A comment about the current entity.

Comments in comment clauses are guaranteed to be conserved by OBO parsers and serializers, unlike bang comments. A non None comment is semantically equivalent to a rdfs:comment in OWL2. When parsing from OWL, several RDF comments will be merged together into a single comment clause spanning over multiple lines.

Type:

str or None

property consider: _S

A set of potential substitutes for an obsolete term.

An obsolete entity can provide one or more entities which may be appropriate substitutes, but needs to be looked at carefully by a human expert before the replacement is done.

See also

replaced_by, which provides a set of entities suitable for automatic replacement.

Type:

EntitySet

property created_by: str | None

The name of the creator of the entity, if any.

This property gets translated to a dc:creator annotation in OWL2, which has very broad semantics. Some OBO ontologies may instead use other annotation properties such as the ones found in Information Interchange Ontology, which can be accessed in the annotations attribute of the entity, if any.

Type:

str or None

property creation_date: datetime | None

The date the entity was created.

Type:

datetime or None

property definition: Definition | None

The definition of the current entity.

Definitions in OBO are intended to be human-readable text describing the entity, with some additional cross-references if possible.

Example

>>> hp = pronto.Ontology.from_obo_library("hp.obo")
>>> term = hp["HP:0009882"]
>>> term.name
'Short distal phalanx of finger'
>>> str(term.definition)
'Short distance from the end of the finger to the most distal...'
>>> sorted(term.definition.xrefs)
[Xref('HPO:probinson'), Xref('PMID:19125433')]
Type:

Definition or None

property disjoint_from: _S

The entities declared as disjoint from this entity.

Two entities are disjoint if they have no instances in common. Two entities that are disjoint cannot share any subentities, but the opposite is not always true.

Type:

EntitySet

property equivalent_to: _S

The entities declared as equivalent to this entity.

Type:

EntitySet

property id: str

The OBO identifier of the entity.

Identifiers can be either prefixed (e.g. MS:1000031), unprefixed (e.g. part_of) or given as plain URLs. Identifiers cannot be edited.

Type:

str

property name: str | None

The name of the entity.

Names are formally equivalent to rdf:label in OWL2. The OBO format version 1.4 made names optional to improve OWL interoperability, as labels are optional in OWL.

Type:

str or None

property namespace: str | None

The namespace this entity is defined in.

Type:

str or None

property obsolete: bool

Whether or not the entity is obsolete.

Hint

All OBO entities can be made obsolete through a boolean flag, and map to one or several replacements. When querying an obsolete entity, pronto will not attempt to perform any kind of replacement itself

>>> ms = pronto.Ontology.from_obo_library("ms.obo")
>>> term = ms["MS:1001414"]
>>> term
Term('MS:1001414', name='MGF scans')
>>> term.obsolete
True

To always get the up-to-date, non-obsolete entity, you could use the following snippet, going through a term replacement if there is no ambiguity

>>> while term.obsolete:
...     if len(term.replaced_by) != 1:
...         raise ValueError(f"no replacement for {term.id}")
...     term = term.replaced_by.pop()
>>> term
Term('MS:1000797', name='peak list scans')

See also

consider and replaced_by, storing some replacement options for an obsolete entity.

Type:

bool

property relationships: Relationships[_E, _S]

The links from an entity to other entities.

This property returns an object that maps a Relationship to an EntitySet (either a TermSet for Term.relationships, or a RelationshipSet for Relationship.relationships).

Hint

The mapping is mutable, so relationships can be created or removed using the usual interface of a MutableMapping.

Example

Get the MS:1000004 term (sample mass) from the Mass Spectrometry ontology:

>>> ms = pronto.Ontology.from_obo_library("ms.obo")
>>> sample_mass = ms["MS:1000004"]

Then use the relationships property to get the relevant unit from the Unit Ontology:

>>> sorted(sample_mass.relationships.keys())
[Relationship('has_units', name='has_units')]
>>> sample_mass.relationships[ms.get_relationship('has_units')]
TermSet({Term('UO:0000021', name='gram')})
Type:

Relationships

property replaced_by: _S

A set of of replacements for an obsolete term.

An obsolete entity can provide one or more replacement that can safely be used to automatically reassign instances to non-obsolete classes.

See also

consider, which provides a set of entities suitable for replacement but requiring expert curation.

Type:

EntitySet

property subsets: FrozenSet[str]

The subsets containing this entity.

Type:

frozenset of str

property synonyms: FrozenSet[Synonym]

A set of synonyms for this entity.

Type:

frozenset of Synonym

property xrefs: FrozenSet[Xref]

A set of database cross-references.

Xrefs can be used to describe an analogous entity in another vocabulary, such as a database or a semantic knowledge base.

Type:

frozenset of Xref

objects(r: Relationship) Iterator[Term][source]

Iterate over the terms t verifying self · r · t.

Example

>>> go = pronto.Ontology.from_obo_library("go.obo")
>>> go['GO:0048870']
Term('GO:0048870', name='cell motility')
>>> list(go['GO:0048870'].objects(go.get_relationship('part_of')))
[Term('GO:0051674', name='localization of cell')]

Todo

Make Term.objects take in account holds_over_chain and transitive_over values of the relationship it is building an iterator with.

superclasses(distance: int | None = None, with_self: bool = True) SuperclassesHandler[source]

Get an handle over the superclasses of this Term.

In order to follow the semantics of rdf:subClassOf, which in turn respects the mathematical definition of subset inclusion, is_a is defined as a reflexive relationship, and so is its inverse relationship.

Parameters:
  • distance (int, optional) – The maximum distance between this term and the yielded superclass (0 for the term itself, 1 for its immediate superclasses, etc.). Use None to explore transitively the entire directed graph.

  • with_self (bool) – Whether or not to include the current term in the terms being yielded. RDF semantics state that the rdfs:subClassOf property is reflexive, so this is enabled by default, but in most practical cases only the distinct subclasses are desired.

Yields:

Term – Superclasses of the selected term, breadth-first. The first element is always the term itself, use itertools.islice to skip it.

Example

>>> ms = pronto.Ontology.from_obo_library("ms.obo")
>>> sup = iter(ms['MS:1000143'].superclasses())
>>> next(sup)
Term('MS:1000143', name='API 150EX')
>>> next(sup)
Term('MS:1000121', name='SCIEX instrument model')
>>> next(sup)
Term('MS:1000031', name='instrument model')

Note

The time complexity for this algorithm is in \(O(n)\), where \(n\) is the number of subclasses of initial term.

See also

The RDF Schema 1.1 specification, defining the rdfs:subClassOf property, which the is_a relationship is translated to in OWL2 language.

subclasses(distance: int | None = None, with_self: bool = True) SubclassesHandler[source]

Get an handle over the subclasses of this Term.

Parameters:
  • distance (int, optional) – The maximum distance between this term and the yielded subclass (0 for the term itself, 1 for its immediate children, etc.). Use None to explore the entire directed graph transitively.

  • with_self (bool) – Whether or not to include the current term in the terms being yielded. RDF semantics state that the rdfs:subClassOf property is reflexive, so this is enabled by default, but in most practical cases only the distinct subclasses are desired.

Yields:

Term – Subclasses of the selected term, breadth-first. The first element is always the term itself, use itertools.islice to skip it.

Example

>>> ms = pronto.Ontology.from_obo_library("ms.obo")
>>> sub = iter(ms['MS:1000031'].subclasses())
>>> next(sub)
Term('MS:1000031', name='instrument model')
>>> next(sub)
Term('MS:1000121', name='SCIEX instrument model')
>>> next(sub)
Term('MS:1000122', name='Bruker Daltonics instrument model')

Hint

Use the to_set method of the returned iterator to efficiently collect all subclasses into a TermSet.

Note

This method has a runtime that is \(O(n)\) where \(n\) is the number of subclasses of the initial term. While OBO and OWL only explicit the superclassing relationship (equivalent to the rdfs:subClassOf property in RDF), we can build a cache that stores the edges of the resulting knowledge graph in an index accessible by both endpoints of each edge.

is_leaf() bool[source]

Check whether the term is a leaf in the ontology.

We define leaves as nodes in the ontology which do not have subclasses since the subclassing relationship is directed and can be used to create a DAG of all the terms in the ontology.

Example

>>> ms = pronto.Ontology.from_obo_library("ms.obo")
>>> ms['MS:1000031'].is_leaf()   # instrument model
False
>>> ms['MS:1001792'].is_leaf()   # Xevo TQ-S
True

Note

This method has a runtime of \(O(1)\) as Ontology objects internally cache the subclasses of each term.

property intersection_of: FrozenSet[Term | Tuple[Relationship, Term]]

The terms this term is an intersection of.

Type:

frozenset