Basic Ontology Interface

Code

class oaklib.interfaces.basic_ontology_interface.BasicOntologyInterface(resource: typing.Optional[oaklib.resource.OntologyResource] = None, strict: bool = False, multilingual: typing.Optional[bool] = None, preferred_language: str = <factory>, autosave: bool = <factory>, exclude_owl_top_and_bottom: bool = <factory>, ontology_metamodel_mapper: typing.Optional[oaklib.mappers.ontology_metadata_mapper.OntologyMetadataMapper] = None, _converter: typing.Optional[curies.api.Converter] = None, auto_relax_axioms: typing.Optional[bool] = None, cache_lookups: bool = False)[source]

Basic lookup operations on ontologies

No Object Model is used - input and payloads are simple scalars, dicts, and lists

This presents an intentionally highly simplistic, lossy view of an ontology. It is intended to fit the “80% of uses” scenario - for more advanced uses, use one of the more specialized subclasses

Basic concepts:

  • An ontology is a collection of entities

  • Entities are typically classes (terms), but they may be other types

  • An entity MUST BE uniquely identifier by a CURIE

  • Each entity SHOULD have a single name

  • Entities may have hierarchical parents and children

  • Entities may have simple relationships to other terms

    • A relationship is a simple triple (in OWL terms, these may represent existential relationships)

    • A CURIE is used for the predicate

  • Entities may have aliases (synonyms)

    • these MAY be typed (scoped)

  • Entities have simple key-value metadata associated with them, where keys are open-ended

Out of scope:

  • Many OWL axioms including:

    • Disjointness

    • Equivalence (including “logical definitions”)

    • Property characteristics

  • All OWL expressions

    • but note that simple SomeValuesFrom expressions are included as relationships

  • Information about specific assignments (“axiom annotations” in OWL terms)

    • this includes attribution for synonyms, definitions, …

  • A fixed datamodel for metadata, beyond core minimal information

CURIEs are used as the default means of identifying entities.

In some cases there may not be a defined CURIE form for an entity, such as an ontology, in which case URIs may be used

add_missing_property_values(curie: str, metadata_map: Dict[str, List[str]]) → None[source]

Add missing property values to a metadata map.

This is a convenience method for implementations that do not have a complete metadata map.

Parameters

  • curie –

  • metadata_map –

Returns

alias_map_by_curie(curie: str) → Dict[str, List[str]][source]

Deprecated since version Replaced: by alias_map(curie)

aliases_by_curie(curie: str) → List[str][source]

Deprecated since version Use: entity_aliases(curie)

all_entity_curies(**kwargs) → Iterable[str][source]

Deprecated since version Replaced: by entities

all_obsolete_curies() → Iterable[str][source]

Deprecated since version Replaced: by obsoletes()

all_ontology_curies() → Iterable[str][source]

Deprecated since version Replaced: by ontology_curies

all_relationships() → Iterable[Tuple[str, str, str]][source]

Yields all known relationships.

Returns

Deprecated since version Use: relationships()

all_subset_curies() → Iterable[str][source]

Deprecated since version Replaced: by subsets()

auto_relax_axioms: bool = None

If True, relax some OWL axioms as per https://robot.obolibrary.org/relax

autosave: bool

For adapters that wrap a transactional source (e.g sqlite), this controls whether results should be auto-committed after each operation

cache_lookups: bool = False

If True, the implementation may choose to cache lookup operations

clone(resource: Any) → None[source]

Clones the ontology interface to a new resource.

Parameters

resource –

Returns

comments(curies: Iterable[str]) → Iterable[Tuple[str, str]][source]

Yields entity-comment pairs for a CURIE or CURIEs.

The CURIE may be for a class, individual, property, or ontology

Parameters

curies –

Returns

property converter: curies.api.Converter

Get a converter for this ontology interface’s prefix map.

Returns

A converter

create_entity(curie: str, label: Optional[str] = None, relationships: Optional[Dict[str, List[str]]] = None, replace=False, **kwargs) → str[source]

Creates and stores an entity.

Parameters

  • curie –

  • label –

  • relationships –

  • replace –

  • kwargs –

Returns

curie_to_uri(curie: str, strict: bool = False) → Optional[str][source]

Expands a CURIE to a URI.

Parameters

  • curie –

  • strict – (Default is False) if True, exceptions will be raised if curie cannot be expanded

Returns

curies_by_label(label: str) → List[str][source]

Fetches all curies with a given label.

This SHOULD return maximum one CURIE but there are circumstances where multiple CURIEs may share a label

Parameters

label –

Returns

curies_by_subset(subset: str) → Iterable[str][source]

Deprecated since version Replaced: by subset_members(subset)

defined_by(entity: str) → Optional[str][source]

Returns the CURIE of the ontology that defines the given entity.

Parameters

entity –

Returns

defined_bys(entities: Iterable[str]) → Iterable[str][source]

Yields all known isDefinedBys for given entities.

This is for determining the ontology that defines a given entity, i.e. which ontology the entity belongs to.

Formally, this should be captured by an rdfs:isDefinedBy triple, but in practice this may not be explicitly stated. In this case, implementations may choose to use heuristic measures, including using the ontology prefix.

Parameters

entities –

Returns

iterator

definition(curie: str) → Optional[str][source]

Lookup the text definition of an entity.

Parameters

curie – entity identifier to be looked up

Returns

definitions(curies: Iterable[str], include_metadata=False, include_missing=False) → Iterator[Tuple[str, str, Dict[str, List[str]]]][source]

Lookup the text definition plus metadata for a list of entities.

Parameters

  • curies – iterable collection of entity identifiers to be looked up

  • include_metadata – if true, include metadata

  • include_missing – if true, include curies with no definition

Returns

delete_entity(curie: str, label: Optional[str] = None, **kwargs) → str[source]

Deletes an entity.

Parameters

  • curie –

  • kwargs –

Returns

entities(filter_obsoletes=True, owl_type=None) → Iterable[str][source]

Yields all known entity CURIEs.

Parameters

  • filter_obsoletes – if True, exclude any obsolete/deprecated element

  • owl_type – CURIE for RDF metaclass for the object, e.g. owl:Class

Returns

iterator

entities_metadata_statements(curies: Iterable[str], predicates: Optional[List[str]] = None) → Iterator[Union[Tuple[str, str, Any, str, Optional[Dict[str, List[str]]]], Tuple[str, str, str, None, Optional[Dict[str, List[str]]]]]][source]

Retrieve metadata statements (entity annotations) for a collection of entities.

Parameters

curies –

Returns

entity_alias_map(curie: str) → Dict[str, List[str]][source]

Returns aliases keyed by alias type (scope in OBO terms)

  • The alias map MUST include rdfs:label annotations

  • The alias map MAY include other properties the implementation deems to serve an alias role

Parameters

curie –

Returns

entity_aliases(curie: str) → List[str][source]

All aliases/synonyms for a given CURIE

This lumps together all synonym categories (scopes)

Parameters

curie –

Returns

entity_metadata_map(curie: str) → Dict[str, List[str]][source]

Lookup basic metadata for a given entity.

Returns a dictionary keyed by property predicate, with a list of zero or more values, where each key corresponds to any of a set of open-ended metadata predicates

This is a simplified version of the metadata model in many ontologies

Parameters

curie –

Returns

exclude_owl_top_and_bottom: bool

Do not include owl:Thing or owl:Nothing

get_curies_by_label(label: str) → List[str][source]

Deprecated since version Use: curies_by_label(label)

get_definition_by_curie(curie: str) → Optional[str][source]

Deprecated since version Use: definition()

get_incoming_relationship_map_by_curie(curie: str) → Dict[str, List[str]][source]

Deprecated since version Use: incoming_relationship_map(curie)

get_incoming_relationships(**kwargs) → Iterator[Tuple[str, str]][source]

Deprecated since version Replaced: by incoming_relationships(…)

get_label_by_curie(curie: str) → Optional[str][source]

Deprecated since version Use: label(curie))

get_labels_for_curies(**kwargs) → Iterable[Tuple[str, str]][source]

Deprecated since version Use: labels(…)

get_outgoing_relationship_map_by_curie(curie: str) → Dict[str, List[str]][source]

Deprecated since version Use: outgoing_relationship_map(curie)

get_outgoing_relationships(curie: str, predicates: Optional[List[str]] = None) → Iterator[Tuple[str, str]][source]

Deprecated since version Use: outgoing_relationships()

get_prefix_map() → Mapping[str, str][source]

Deprecated since version Replaced: by prefix_map

get_relationships(**kwargs) → Iterator[Tuple[str, str, str]][source]

Deprecated since version Use: relationships()

hierararchical_parents(curie: str, isa_only: bool = False) → List[str][source]

Returns all hierarchical parents.

The definition of hierarchical parent depends on the provider. For example, in OLS, this will return part-of parents for GO, as well as is-a

This only returns Named Entities; i.e. if an RDF source is wrapped, this will NOT return blank nodes

To get all relationships, see outgoing_relationships

A fresh map is created each invocation

Parameters

  • curie –

  • isa_only – restrict hierarchical parents to isa only

Returns

incoming_relationship_map(curie: str) → Dict[str, List[str]][source]

Returns a predicate-subjects map with incoming relationships for a node.

See :ref:outgoing_relationship_map:

Parameters

curie –

Returns

incoming_relationships(curie: str, predicates: Optional[List[str]] = None) → Iterator[Tuple[str, str]][source]

Returns relationships where curie in the object

Parameters

  • curie –

  • predicates – if None, do not filter

Returns

label(curie: str) → Optional[str][source]

fetches the unique label for a CURIE.

The CURIE may be for a class, individual, property, or ontology

Parameters

curie –

Returns

labels(curies: Iterable[str], allow_none=True) → Iterable[Tuple[str, str]][source]

Yields entity-label pairs for a CURIE or CURIEs.

The CURIE may be for a class, individual, property, or ontology

Parameters

  • curies – identifiers to be queried

  • allow_none – [True] use None as value if no label found

Returns

leafs(predicates: Optional[List[str]] = None, ignore_owl_nothing=True, filter_obsoletes=True) → Iterable[str][source]

Yields all nodes that have no children.

Note that the concept of a “leaf” in an ontology can be ambiguous:

  • is the (trivial) owl:Nothing included (OWL tautology)?

  • are we asking for the leaf of the is-a graph, or the whole graph?

  • do we include obsolete nodes (which are typically singletons)?

This method will yield entities that are not the object of an edge, considering only edges with a given set of predicates, optionally ignoring owl:Nothing, and optionally constraining to a given set of entity CURIE prefixes.

Parameters

  • predicates – predicates to be considered (default: all)

  • ignore_owl_nothing – do not consider artificial/trivial owl:Nothing when calculating (default=True)

  • filter_obsoletes – do not include obsolete/deprecated nodes in results (default=True)

Returns

multilingual: bool = None

True if the ontology is multilingual, and may provide alterntive primary labels

obsoletes(include_merged=True) → Iterable[str][source]

Yields all known entities that are obsolete.

In OWL, obsolete entities (aka deprecated entities) are those that have an owl:deprecated annotation with value “True”

Example:

>>> for entity in ontology.obsoletes():
...     print(entity)

By default, merged terms are included. Merged terms are entities that are:

    1. obsolete

    1. have a replacement term

    1. have an “obsolescence reason” that is “merged term”

In OBO Format, merged terms do not get their own stanza, but instead show up as alt_id tags on the replacement term.

To exclude merged terms, set include_merged=False:

Example:

>>> for entity in ontology.obsoletes(include_merged=False):
...     print(entity)
Parameters

include_merged – If True, merged terms will be included

Returns

iterator over CURIEs

obsoletes_migration_relationships(entities: Iterable[str]) → Iterable[Tuple[str, str, str]][source]

Yields relationships between an obsolete entity and potential replacements.

Example:

>>> for rel in ontology.obsoletes_migration_relationships(ontology.obsoletes()):
...     print(rel)

Obsoletion relationship predicates may be:

  • IAO:0100001 (term replaced by)

  • oboInOwl:consider

  • rdfs:seeAlso

Returns

iterator

ontologies() → Iterable[str][source]

Yields all known ontology CURIEs.

Many OntologyInterfaces will wrap a single ontology, others will wrap multiple. Even when a single ontology is wrapped, there may be multiple ontologies included as imports

Returns

iterator

ontology_curies() → Iterable[str][source]

Deprecated since version Replaced: by ontologies()

ontology_metadata_map(ontology: str) → Dict[str, List[str]][source]

Property-values metadata map with metadata about an ontology.

Parameters

ontology –

Returns

ontology_metamodel_mapper: Optional[oaklib.mappers.ontology_metadata_mapper.OntologyMetadataMapper] = None

An optional mapper that overrides metamodel properties

ontology_versions(ontology: str) → Iterable[str][source]

Yields all version identifiers for an ontology.

Parameters

ontology –

Returns

iterator

outgoing_relationship_map(curie: str) → Dict[str, List[str]][source]

Returns a predicate-objects map with outgoing relationships for a node.

The return relationship map is keyed by relationship type, where the values are the ‘parents’ or fillers

OWL formulation:

  • is_a: {P : SubClassOf(C P), class(P)}

  • R: {P : SubClassOf(C ObjectSomeValuesFrom( RP), class(P), property(P)}

Parameters

curie – the ‘child’ term

Returns

outgoing_relationships(curie: str, predicates: Optional[List[str]] = None) → Iterator[Tuple[str, str]][source]

Yields relationships where the input curie in the subject.

Parameters

  • curie –

  • predicates – if None, do not filter

Returns

owl_type(entity: str) → List[str][source]

Get the OWL type for a given entity.

Typically each entity will have a single OWL type, but in some cases an entity may have multiple OWL types. This is called “punning”, see Section 8.3<https://www.w3.org/TR/owl2-primer/#Entity_Declarations> of the OWL primer

Parameters

entity –

Returns

CURIE

owl_types(entities: Iterable[str]) → Iterable[Tuple[str, str]][source]

Yields all known OWL types for given entities.

The OWL type must either be the instantiated type as the RDFS level, e.g.

  • owl:Class

  • owl:ObjectProperty

  • owl:DatatypeProperty

  • owl:AnnotationProperty

  • owl:NamedIndividual

Or a vocabulary type for a particular kind of construct, e.g

  • oio:SubsetProperty

  • obo:SynonymTypeProperty

See Section 8.3<https://www.w3.org/TR/owl2-primer/#Entity_Declarations> of the OWL 2 Primer

Parameters

entities –

Returns

iterator

precompute_lookups() → None[source]

Precompute all main lookup operations.

An implementation may choose to use this to do lookups in advance. This may be faster for some operations that involve repeatedly visiting the same entity. :return:

preferred_language: str

The preferred language for labels and other lexical entities

prefix_map() → Mapping[str, str][source]

Return a dictionary mapping all prefixes known to the resource to their URI expansion.

By default, this returns a combination of the OBO Foundry prefix map with the default OAKlib prefix map (see oaklib.datamodels.vocabulary.DEFAULT_PREFIX_MAP).

Returns

prefix map

query(query: str, syntax: Optional[str] = None, prefixes: Optional[List[str]] = None, **kwargs) → Iterator[Any][source]

Executes a query.

The behavior of this operation is entirely adapter-dependent, and is thus not portable.

The intention is for SQL backends to support SQL queries, and for SPARQL backends to support SPARQL queries.

Parameters

  • query –

  • syntax –

  • kwargs –

Returns

an iterator over the results, which can be arbitrary objects

relationships(subjects: Optional[Iterable[str]] = None, predicates: Optional[Iterable[str]] = None, objects: Optional[Iterable[str]] = None, include_tbox: bool = True, include_abox: bool = True, include_entailed: bool = False, exclude_blank: bool = True) → Iterator[Tuple[str, str, str]][source]

Yields all relationships matching query constraints.

Parameters

  • subjects – constrain search to these subjects (i.e outgoing edges)

  • predicates – constrain search to these predicates

  • objects – constrain search to these objects (i.e incoming edges)

  • include_tbox – if true, include class-class relationships (default True)

  • include_abox – if true, include instance-instance/class relationships (default True)

  • include_entailed –

  • exclude_blank – do not include blank nodes/anonymous expressions

Returns

roots(predicates: Optional[List[str]] = None, ignore_owl_thing=True, filter_obsoletes=True, annotated_roots=False, id_prefixes: Optional[List[str]] = None) → Iterable[str][source]

Yields all entities without a parent.

Note that the concept of a “root” in an ontology can be ambiguous:

  • is the (trivial) owl:Thing included (OWL tautology)?

  • are we asking for the root of the is-a graph, or a subset of predicates?

  • do we include parents in imported/merged other ontologies (e.g. BFO)?

  • do we include obsolete nodes (which are typically singletons)?

This method will yield entities that are not the subject of an edge, considering only edges with a given set of predicates, optionally ignoring owl:Thing, and optionally constraining to a given set of entity CURIE prefixes

Parameters

  • predicates – predicates to be considered (default: all)

  • ignore_owl_thing – do not consider artificial/trivial owl:Thing when calculating (default=True)

  • filter_obsoletes – do not include obsolete/deprecated nodes in results (default=True)

  • annotated_roots – use nodes explicitly annotated as root

  • id_prefixes – limit search to specific prefixes

Returns

save()[source]

Saves current state.

Returns

set_label(curie: str, label: str) → bool[source]

Sets the value of a label for a CURIE.

Parameters

  • curie –

  • label –

Returns

set_metamodel_mappings(mappings: Union[str, pathlib.Path, List[Mapping]]) → None[source]

Sets the ontology metamodel mapper.

Parameters

mappings – Mappings for predicates such as rdfs:subClassOf

Returns

simple_mappings(curies: Iterable[str]) → Iterable[Tuple[str, str, str]][source]

Yields simple mappings for a collection of subjects

Parameters

curies – iterable collection of entity identifiers to be looked up

Returns

iterable subject-predicate-object tuples

simple_mappings_by_curie(curie: str) → Iterable[Tuple[str, str]][source]

Yields mappings for a given subject.

Here, each mapping is represented as a simple tuple (predicate, object)

Parameters

curie – entity identifier to be looked up

Returns

iterator over predicate-object tuples

singletons(predicates: Optional[List[str]] = None, filter_obsoletes=True) → Iterable[str][source]

Yields entities that have neither parents nor children.

All singleton nodes, where a singleton has no connections using the specified predicate list

Parameters

  • predicates –

  • ignore_owl_nothing –

  • filter_obsoletes –

Returns

strict: bool = False

Raise exceptions when entities not found in ID-based lookups

subset_curies() → Iterable[str][source]

Deprecated since version Replaced: by subsets()

subset_members(subset: str) → Iterable[str][source]

Yields all entities belonging to the specified subset.

Returns

iterator

subsets() → Iterable[str][source]

Yields all subsets (slims) defined in the ontology.

All subsets yielded are contracted to their short form.

Returns

iterator

terms_categories(curies: Iterable[str]) → Iterable[Tuple[str, str]][source]

Yields all categories an entity or entities belongs to.

Returns

iterator

terms_subsets(curies: Iterable[str]) → Iterable[Tuple[str, str]][source]

Yields entity-subset pairs for the given set of entities.

Returns

iterator

uri_to_curie(uri: str, strict: bool = True, use_uri_fallback=False) → Optional[str][source]

Contracts a URI to a CURIE.

If strict conditions hold, then no URI can map to more than one CURIE (i.e one URI base should not start with another).

Parameters

  • uri – URI

  • strict – Boolean [default: True]

  • use_uri_fallback – if cannot be contracted, use the URI as a CURIE proxy [default: True]

Returns

contracted URI, or original URI if no contraction possible