Ontology Access Kit (OAK)

Python lib for common ontology operations over a variety of backends.

OAK provides a collection of interfaces for various ontology operations, including:

• look up basic features of an ontology element, such as its label, definition, relationships, or aliases
• search an ontology for a term
• validate an ontology
• modify or delete terms
• generate and visualize subgraphs
• identify lexical matches and export as SSSOM mapping tables
• perform more advanced operations, such as graph traversal, OWL axiom processing, or text annotation

These interfaces are separated from any particular backend, for which there a number of different adapters. This means the same Python API and command line can be used regardless of whether the ontology:

• is served by a remote API such as OLS or BioPortal
• is present locally on the filesystem in owl, obo, obojson, or sqlite formats
• is to be downloaded from a remote repository such as the OBO library
• is queried from a remote database, including SPARQL endpoints (Ontobee/Ubergraph), A SQL database, a Solr/ES endpoint

Documentation:

• incatools.github.io/ontology-access-kit
• Presentations:
  • Using the OAK command line OBO Academy 2023
  • Introduction to OAK OAK workshop 2022

Contributing

See the contribution guidelines at CONTRIBUTING.md. All contributors are expected to uphold our Code of Conduct.

Usage

```python from oaklib import get_adapter

connect to the CL sqlite database adapter

(will first download if not already downloaded)

adapter = get_adapter("sqlite:obo:cl")

NEURON = "CL:0000540"

print('## Basic info') print(f'ID: {NEURON}') print(f'Label: {adapter.label(NEURON)}')

for alias in adapter.entity_aliases(NEURON): print(f'Alias: {alias}')

print('## Relationships (direct)') for relationship in adapter.relationships([NEURON]): print(f' * {relationship.predicate} -> {relationship.object} "{adapter.label(relationship.object)}"')

print('## Ancestors (over ISA and PARTOF)') from oaklib.datamodels.vocabulary import ISA, PARTOF from oaklib.interfaces import OboGraphInterface

if not isinstance(adapter, OboGraphInterface): raise ValueError('This adapter does not support graph operations')

for ancestor in adapter.ancestors(NEURON, predicates=[ISA, PARTOF]): print(f' * ANCESTOR: "{adapter.label(ancestor)}"') ```

For more examples, see

• demo notebook
• tutorial part 2

Command Line

See:

• CLI docs
• [Example notebooks](https://github.com/INCATools/ontology-access-kit/tree/main/notebooks/Commands

Search

Use the pronto backend to fetch and parse an ontology from the OBO library, then use the search command

bash runoak -i obolibrary:pato.obo search osmol

Returns:

PATO:0001655 ! osmolarity PATO:0001656 ! decreased osmolarity PATO:0001657 ! increased osmolarity PATO:0002027 ! osmolality PATO:0002028 ! decreased osmolality PATO:0002029 ! increased osmolality PATO:0045034 ! normal osmolality PATO:0045035 ! normal osmolarity

QC and Validation

Perform validation on PR using sqlite/rdftab instance:

bash runoak -i sqlite:../semantic-sql/db/pr.db validate

List all terms

List all terms obolibrary has for mondo

bash runoak -i obolibrary:mondo.obo terms

Lexical index

Make a lexical index of all terms in Mondo:

bash runoak -i obolibrary:mondo.obo lexmatch -L mondo.index.yaml

Search

Searching over OBO using ontobee:

bash runoak -i ontobee: search tentacle

yields:

http://purl.obolibrary.org/obo/CEPH_0000256 ! tentacle http://purl.obolibrary.org/obo/CEPH_0000257 ! tentacle absence http://purl.obolibrary.org/obo/CEPH_0000258 ! tentacle pad ...

Searching over a broader set of ontologies in bioportal (requires API KEY) (https://www.bioontology.org/wiki/BioPortalHelp#GettinganAPIkey)

bash runoak set-apikey bioportal YOUR-KEY-HERE runoak -i bioportal: search tentacle

yields:

BTO:0001357 ! tentacle http://purl.jp/bio/4/id/200906071014668510 ! tentacle CEPH:0000256 ! tentacle http://www.projecthalo.com/aura#Tentacle ! Tentacle CEPH:0000256 ! tentacle ... Alternatively, you can add "BIOPORTALAPIKEY" to your environment variables.

Searching over more limited set of ontologies in Ubergraph:

bash runoak -v -i ubergraph: search tentacle

yields UBERON:0013206 ! nasal tentacle

Annotating Texts

bash runoak -i bioportal: annotate neuron from CA4 region of hippocampus of mouse

yields:

```yaml objectid: CL:0000540 objectlabel: neuron objectsource: https://data.bioontology.org/ontologies/NIFDYS matchtype: PREF subjectstart: 1 subjectend: 6 subject_label: NEURON

objectid: http://www.co-ode.org/ontologies/galen#Neuron objectlabel: Neuron objectsource: https://data.bioontology.org/ontologies/GALEN matchtype: PREF subjectstart: 1 subjectend: 6 subject_label: NEURON

... ```

Mapping

Create a SSSOM mapping file for a set of ontologies:

bash robot merge -I http://purl.obolibrary.org/obo/hp.owl -I http://purl.obolibrary.org/obo/mp.owl convert --check false -o hp-mp.obo runoak lexmatch -i hp-mp.obo -o hp-mp.sssom.tsv

Visualization of ancestor graphs

Use the sqlite backend to visualize graph up from 'vacuole' using test ontology sqlite:

bash runoak -i sqlite:tests/input/go-nucleus.db viz GO:0005773

Same using ubergraph, restricting to is-a and part-of

bash runoak -i ubergraph: viz GO:0005773 -p i,BFO:0000050

Same using pronto, fetching ontology from obolibrary

bash runoak -i obolibrary:go.obo viz GO:0005773

Configuration

OAK uses pystow for caching. By default, this goes inside ~/.data/, but can be configured following these instructions.