Basic Ontology Interface

class oaklib.interfaces.basic_ontology_interface.BasicOntologyInterface(resource: ~oaklib.resource.OntologyResource | None = None, strict: bool = False, _multilingual: bool | None = None, autosave: bool = <factory>, exclude_owl_top_and_bottom: bool = <factory>, ontology_metamodel_mapper: ~oaklib.mappers.ontology_metadata_mapper.OntologyMetadataMapper | None = None, _converter: ~curies.api.Converter | None = None, auto_relax_axioms: bool | None = None, cache_lookups: bool = False, property_cache: ~oaklib.utilities.keyval_cache.KeyValCache = <factory>, _edge_index: ~oaklib.indexes.edge_index.EdgeIndex | None = None, _entailed_edge_index: ~oaklib.indexes.edge_index.EdgeIndex | None = None, _prefix_map: ~typing.Mapping[str, str] | None = None)[source]

Basic lookup operations on ontologies.

>>> from oaklib import get_adapter
>>> adapter = get_adapter('tests/input/go-nucleus.db')
>>> print(adapter.label("GO:0005634"))
nucleus

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.

For example, BasicOntologyInterface exposes a simple model of synonyms as aliases:

>>> from oaklib import get_adapter
>>> adapter = get_adapter('tests/input/go-nucleus.db')
>>> for alias in sorted(adapter.entity_aliases("GO:0005634")):
...     print(alias)
cell nucleus
horsetail nucleus
nucleus

This omits metadata about the synonym, such as the predicate, source, and type. For this more granular view, the OboGraph Interface can be used.

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

strict: bool = False

Raise exceptions when entities not found in ID-based lookups

autosave: bool

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

exclude_owl_top_and_bottom: bool

Do not include owl:Thing or owl:Nothing

ontology_metamodel_mapper: OntologyMetadataMapper | None = None

An optional mapper that overrides metamodel properties

auto_relax_axioms: bool = None

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

cache_lookups: bool = False

If True, the implementation may choose to cache lookup operations

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

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

>>> from oaklib import get_adapter
>>> adapter = get_adapter('tests/input/go-nucleus.db')
>>> for prefix, expansion in adapter.prefix_map().items():
...     print(prefix, expansion)

...
GO http://purl.obolibrary.org/obo/GO_
...

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

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

Deprecated since version Replaced: by prefix_map

property converter: Converter

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

>>> from oaklib import get_adapter
>>> adapter = get_adapter('tests/input/go-nucleus.db')
>>> converter = adapter.converter
>>> print(converter.compress("http://purl.obolibrary.org/obo/GO_0005634"))
GO:0005634
Returns:

A converter

set_metamodel_mappings(mappings: str | Path | List[Mapping]) None[source]

Sets the ontology metamodel mapper.

Parameters:

mappings – Mappings for predicates such as rdfs:subClassOf

Returns:

curie_to_uri(curie: str, strict: bool = False) str | None[source]

Expands a CURIE to a URI.

>>> from oaklib import get_adapter
>>> adapter = get_adapter('tests/input/go-nucleus.db')
>>> print(adapter.curie_to_uri("GO:0005634"))
http://purl.obolibrary.org/obo/GO_0005634
Parameters:
  • curie

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

Returns:

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

Contracts a URI to a CURIE.

>>> from oaklib import get_adapter
>>> adapter = get_adapter('tests/input/go-nucleus.db')
>>> print(adapter.uri_to_curie("http://purl.obolibrary.org/obo/GO_0005634"))
GO:0005634

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

property edge_index: EdgeIndex

An index of all asserted edges in the ontology.

Note

not all adapters populate this index.

Returns:

index of edges

property entailed_edge_index: EdgeIndex

An index of all entailed edges in the ontology.

Note

not all adapters populate this index.

Returns:

index of entailed edges

property multilingual: bool

Returns True if this ontology interface supports multilingual annotations.

This is by default inferred from the content of the ontology, if more than one language tag is present. This is the case for the international version of the HPO:

>>> from oaklib import get_adapter
>>> adapter = get_adapter('tests/input/hp-international-test.db')
>>> adapter.multilingual
True

If no language tags are present, then this will return False:

>>> from oaklib import get_adapter
>>> adapter = get_adapter('tests/input/go-nucleus.db')
>>> adapter.multilingual
False

Note

currently this is only implemented for the SQL backend.

Returns:

True if multilingual

languages() Iterable[str][source]

Returns a list of languages explicitly supported by this ontology interface.

>>> from oaklib import get_adapter
>>> adapter = get_adapter('tests/input/hp-international-test.db')
>>> for lang in sorted(adapter.languages()):
...    print(lang)
cs
fr
nl
tr
Returns:

iterator of language tags

property default_language: str | None

Returns the default language for this ontology interface.

>>> from oaklib import get_adapter
>>> adapter = get_adapter('tests/input/hp-international-test.db')
>>> adapter.default_language
'en'

Note that here “default” has a particular meaning: it means that lexical elements are MUST NOT be explicitly tagged with this language, and that it MUST be assumed that a blank/empty/null language tag means that the default language is intended.

Returns:

language tag

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.

>>> from oaklib import get_adapter
>>> adapter = get_adapter('tests/input/go-nucleus.owl.ttl')
>>> list(adapter.ontologies())
['go.owl']

Note

The payload for this method may change to return normalized ontology names such as ‘go’

>>> from oaklib import get_adapter
>>> adapter = get_adapter('bioportal:')
>>> for ont in sorted(adapter.ontologies()):
...     print(ont)

...
GO
...
UBERON
...
Returns:

iterator

ontology_curies() Iterable[str][source]

Deprecated since version Replaced: by ontologies()

all_ontology_curies() Iterable[str][source]

Deprecated since version Replaced: by ontology_curies

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

Yields all known entities that are obsolete.

Example:

>>> from oaklib import get_adapter
>>> adapter = get_adapter("sqlite:obo:cob")
>>> for entity in adapter.obsoletes():
...     print(entity)

...
COB:0000014

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

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:

>>> from oaklib import get_adapter
>>> adapter = get_adapter("sqlite:obo:cob")
>>> for entity in adapter.obsoletes(include_merged=False):
...     print(entity)

...
COB:0000014
param include_merged:

If True, merged terms will be included

return:

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:

>>> from oaklib import get_adapter
>>> adapter = get_adapter("sqlite:obo:cob")
>>> for rel in adapter.obsoletes_migration_relationships(adapter.obsoletes()):
...     print(rel)

Obsoletion relationship predicates may be:

  • IAO:0100001 (term replaced by)

  • oboInOwl:consider

  • rdfs:seeAlso

return:

iterator

all_obsolete_curies() Iterable[str][source]

Deprecated since version Replaced: by obsoletes()

dangling(curies: Iterable[str] | None = None) Iterable[str][source]

Yields all known entities in provided set that are dangling.

Example:

This example is over an OBO file with one stanza:

[Term]
id: GO:0012505
name: endomembrane system
is_a: GO:0110165 ! cellular anatomical entity
relationship: has_part GO:0005773 ! vacuole

The two edges point to entities that do not exist in the file.

The following code will show these:

>>> from oaklib import get_adapter
>>> # Note: pronto adapter refuses to parse ontology files with dangling
>>> adapter = get_adapter("simpleobo:tests/input/dangling-node-test.obo")
>>> for entity in sorted(adapter.dangling()):
...     print(entity)
GO:0005773
GO:0110165
param curies:

CURIEs to check for dangling; if empty will check all

return:

iterator over CURIEs

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

Yields all version identifiers for an ontology.

Warning

This method is not yet implemented for all OntologyInterface implementations.

Parameters:

ontology

Returns:

iterator

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

Property-values metadata map with metadata about an ontology.

>>> from oaklib import get_adapter
>>> adapter = get_adapter('tests/input/go-nucleus.db')
>>> for ont in adapter.ontologies():
...     m = adapter.ontology_metadata_map(ont)
...     m.get('schema:url')
['http://purl.obolibrary.org/obo/go.owl']
Parameters:

ontology

Returns:

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

Yields all known entity CURIEs.

>>> from oaklib import get_adapter
>>> adapter = get_adapter('tests/input/go-nucleus.db')
>>> for e in adapter.entities():
...     print(e)

...
GO:0005634
...
>>> from oaklib import get_adapter
>>> from oaklib.datamodels.vocabulary import OWL_OBJECT_PROPERTY
>>> adapter = get_adapter('tests/input/go-nucleus.db')
>>> for e in adapter.entities(owl_type=OWL_OBJECT_PROPERTY):
...     print(e)

...
BFO:0000051
...
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

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

Deprecated since version Replaced: by entities

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

Yields all known OWL types for given entities.

>>> from oaklib import get_adapter
>>> adapter = get_adapter('tests/input/go-nucleus.db')
>>> for e, t in sorted(adapter.owl_types(['GO:0005634', 'BFO:0000050'])):
...     print(e, t)
BFO:0000050 owl:ObjectProperty
BFO:0000050 owl:TransitiveProperty
GO:0005634 owl:Class

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

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

Get the OWL type for a given entity.

>>> from oaklib import get_adapter
>>> adapter = get_adapter('tests/input/go-nucleus.db')
>>> adapter.owl_type('GO:0005634')
['owl:Class']

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

defined_by(entity: str) str | None[source]

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

>>> from oaklib import get_adapter
>>> adapter = get_adapter('tests/input/go-nucleus.db')
>>> adapter.defined_by('GO:0005634')
'GO'
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

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

Yields all entities without a parent.

>>> from oaklib import get_adapter
>>> adapter = get_adapter('tests/input/go-nucleus.db')
>>> for e in sorted(adapter.roots()):
...     print(e)

...
BFO:0000003
...
OBI:0100026
...

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)?

Note also that the release OWL versions of many OBO ontologies may exhibit a certain level of messiness with multiple roots.

>>> from oaklib import get_adapter
>>> adapter = get_adapter('tests/input/go-nucleus.db')
>>> for e in sorted(adapter.roots(id_prefixes=['GO'])):
...     print(e, adapter.label(e))
GO:0003674 molecular_function
GO:0005575 cellular_component
GO:0008150 biological_process

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 (IAO:0000700)

  • id_prefixes – limit search to specific prefixes

Returns:

leafs(predicates: List[str] | None = 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:

singletons(predicates: List[str] | None = 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:

subsets() Iterable[str][source]

Yields all subsets (slims) defined in the ontology.

>>> from oaklib import get_adapter
>>> adapter = get_adapter('tests/input/go-nucleus.db')
>>> for e in sorted(adapter.subsets()):
...     print(e)

...
goslim_drosophila
goslim_flybase_ribbon
goslim_generic
...

All subsets yielded are contracted to their short form.

Returns:

iterator

subset_curies() Iterable[str][source]

Deprecated since version Replaced: by subsets()

all_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.

>>> from oaklib import get_adapter
>>> adapter = get_adapter('tests/input/go-nucleus.db')
>>> for e in sorted(adapter.subset_members('goslim_generic')):
...     print(e, adapter.label(e))

...
GO:0005634 nucleus
GO:0005635 nuclear envelope
GO:0005737 cytoplasm
GO:0005773 vacuole
...
Returns:

iterator

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

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

>>> from oaklib import get_adapter
>>> adapter = get_adapter('tests/input/go-nucleus.db')
>>> for e, subset in sorted(adapter.terms_subsets(['GO:0005634', 'GO:0005635'])):
...     print(subset, e, adapter.label(e))

...
goslim_yeast GO:0005634 nucleus
goslim_chembl GO:0005635 nuclear envelope
goslim_generic GO:0005635 nuclear envelope
...
Returns:

iterator

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

Yields all categories an entity or entities belongs to.

Note

This method is not implemented for all adapters.

Returns:

iterator

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

Deprecated since version Replaced: by subset_members(subset)

label(curie: str, lang: str | None = None) str | None[source]

fetches the unique label for a CURIE.

>>> from oaklib import get_adapter
>>> adapter = get_adapter("tests/input/go-nucleus.owl")
>>> adapter.label("GO:0005634")
'nucleus'

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

>>> from oaklib import get_adapter
>>> adapter = get_adapter("tests/input/go-nucleus.owl")
>>> adapter.label("BFO:0000050")
'part of'

For backends that support internationalization, the lang tag can be used:

>>> from oaklib import get_adapter
>>> adapter = get_adapter('tests/input/hp-international-test.db')
>>> adapter.label('HP:0000118', lang='fr')
'Anomalie phénotypique'

If the argument matches the default language, and the literal is not explicitly language tagged, it is still returned

>>> from oaklib import get_adapter
>>> adapter = get_adapter('tests/input/hp-international-test.db')
>>> adapter.label('HP:0000118', lang='en')
'Phenotypic abnormality'
Parameters:
  • curie

  • lang – [None] language tag

Returns:

label

get_label_by_curie(curie: str) str | None[source]

Deprecated since version Use: label(curie))

labels(curies: Iterable[str], allow_none=True, lang: str | None = None) 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.

>>> from oaklib import get_adapter
>>> adapter = get_adapter("tests/input/go-nucleus.owl")
>>> list(sorted(adapter.labels(["GO:0005634", "GO:0005635"])))
[('GO:0005634', 'nucleus'), ('GO:0005635', 'nuclear envelope')]
Parameters:
  • curies – identifiers to be queried

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

Returns:

iterator over tuples of (curie, label)

multilingual_labels(curies: Iterable[str], allow_none=True, langs: List[str] | None = None) Iterable[Tuple[str, str, str]][source]

Yields entity-label-language tuples for a CURIE or CURIEs.

For example, in the HPO international edition:

>>> from oaklib import get_adapter
>>> adapter = get_adapter('tests/input/hp-international-test.db')
>>> for tuple in sorted(adapter.multilingual_labels(['HP:0000118'], langs=['en', 'nl'])):
...     print(tuple)
('HP:0000118', 'Fenotypische abnormaliteit', 'nl')
('HP:0000118', 'Phenotypic abnormality', None)

Note that the english label is not explicitly tagged with a language tag, but is returned because it matches the default_language.

Parameters:
  • curies – identifiers to be queried

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

  • langs – [None] list of languages to be queried (None means all)

Returns:

iterator over tuples of (curie, label, language)

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

Deprecated since version Use: labels(…)

set_label(curie: str, label: str, lang: str | None = None) bool[source]

Sets the value of a label for a CURIE.

Parameters:
  • curie

  • label

  • lang

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:

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

Deprecated since version Use: curies_by_label(label)

comments(curies: Iterable[str], allow_none=True, lang: str | None = None) Iterable[Tuple[str, str | None]][source]

Yields entity-comment pairs for a CURIE or CURIEs.

>>> from oaklib import get_adapter
>>> adapter = get_adapter("tests/input/go-nucleus.db")
>>> for curie, comment in sorted(adapter.comments(["GO:0016772", "GO:0005634"], allow_none=False)):
...     print(f"{curie} {comment[0:31]}[snip]")
GO:0016772 Note that this term encompasses[snip]

Note in the above query, no tuples for “GO:0005634” were yielded - this is because the test ontology has no comments for this CURIE, and allow_none=False.

If allow_none=True, then a tuple with a None value in the second position will be yielded.

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

Parameters:
  • curies

  • allow_none – [True] if False, only yield entities with comments

  • lang – [None] language tag

Returns:

iterator

relationships(subjects: Iterable[str] | None = None, predicates: Iterable[str] | None = None, objects: Iterable[str] | None = 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.

>>> from oaklib import get_adapter
>>> adapter = get_adapter("tests/input/go-nucleus.db")
>>> for s, p, o in sorted(adapter.relationships(subjects=["GO:0005634"])):
...     print(f"{p} {o} '{adapter.label(o)}'")
RO:0002160 NCBITaxon:2759 'Eukaryota'
rdfs:subClassOf GO:0043231 'intracellular membrane-bounded organelle'
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:

relationships_metadata(relationships: Iterable[Tuple[str, str, str]], **kwargs) Iterator[Tuple[Tuple[str, str, str], List[Tuple[str, Any]]]][source]

given collection of relationships, yield relationships with metadata attached.

>>> from oaklib import get_adapter
>>> adapter = get_adapter("sqlite:obo:mondo")
>>> rels = list(adapter.relationships(["MONDO:0009831"]))
>>> for rel, metadatas in adapter.relationships_metadata(rels):
...     for p, v in metadatas:
...         print(rel, p, v)

...
('MONDO:0009831', 'rdfs:subClassOf', 'MONDO:0002516') oio:source NCIT:C9005
...
Parameters:
  • relationships – collection of subject-predicate-object tuples

  • kwargs

Returns:

yields relationships with property-value metadata

hierarchical_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:

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: List[str] | None = None) Iterator[Tuple[str, str]][source]

Yields relationships where the input curie in the subject.

Parameters:
  • curie

  • predicates – if None, do not filter

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: List[str] | None = None) Iterator[Tuple[str, str]][source]

Returns relationships where curie in the object

Parameters:
  • curie

  • predicates – if None, do not filter

Returns:

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

Yields all known relationships.

Returns:

Deprecated since version Use: relationships()

definition(curie: str, lang: str | None = None) str | None[source]

Lookup the text definition of an entity.

>>> from oaklib import get_adapter
>>> adapter = get_adapter("tests/input/go-nucleus.db")
>>> for curie, defn, meta in adapter.definitions(["GO:0005634", "GO:0005737"], include_metadata=True):
...     print(f"{curie} {defn[0:30]}[snip] [{meta}]")
GO:0005634 A membrane-bounded organelle o[snip] [{'oio:hasDbXref': ['GOC:go_curators']}]
GO:0005737 All of the contents of a cell [snip] [{'oio:hasDbXref': ['ISBN:0198547684']}]
Parameters:
  • curie – entity identifier to be looked up

  • lang – language tag

Returns:

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

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

>>> from oaklib import get_adapter
>>> adapter = get_adapter("tests/input/go-nucleus.db")
>>> for curie, defn, meta in adapter.definitions(["GO:0005634", "GO:0005737"], include_metadata=True):
...     print(f"{curie} {defn[0:30]}[snip] [{meta}]")
GO:0005634 A membrane-bounded organelle o[snip] [{'oio:hasDbXref': ['GOC:go_curators']}]
GO:0005737 All of the contents of a cell [snip] [{'oio:hasDbXref': ['ISBN:0198547684']}]
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

  • lang – language tag

Returns:

iterator over (id, definition, metadata) tuples

get_definition_by_curie(curie: str) str | None[source]

Deprecated since version Use: definition()

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)

Note

For a more sophisticated mapping interface, see MappingProviderInterface

Parameters:

curie – entity identifier to be looked up

Returns:

iterator over predicate-object tuples

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

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

All aliases/synonyms for a given CURIE

This lumps together all synonym categories (scopes)

Parameters:

curie

Returns:

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

Deprecated since version Use: entity_aliases(curie)

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:

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

Deprecated since version Replaced: by alias_map(curie)

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:

entities_metadata_statements(curies: Iterable[str], predicates: List[str] | None = None, include_nested_metadata=False, **kwargs) Iterator[Tuple[str, str, Any, str, Dict[str, List[str]] | None] | Tuple[str, str, str, None, Dict[str, List[str]] | None]][source]

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

Parameters:

curies

Returns:

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:

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

Creates and stores an entity.

Parameters:
  • curie

  • label

  • relationships

  • replace

  • kwargs

Returns:

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

Deletes an entity.

Parameters:
  • curie

  • kwargs

Returns:

query(query: str, syntax: str | None = None, prefixes: List[str] | None = 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

save()[source]

Saves current state.

Returns:

clone(resource: Any) None[source]

Clones the ontology interface to a new resource.

Parameters:

resource

Returns:

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: