Skip to main content

Ontology Access Kit (OAK)

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

PyPI version badge Downloads DOI Contributor Covenant

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:

Contributing

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

Usage

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 IS_A and PART_OF)')
from oaklib.datamodels.vocabulary import IS_A, PART_OF
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=[IS_A, PART_OF]):
    print(f' * ANCESTOR: "{adapter.label(ancestor)}"')

For more examples, see

Command Line

See:

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

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:

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

List all terms

List all terms obolibrary has for mondo

runoak -i obolibrary:mondo.obo terms 

Lexical index

Make a lexical index of all terms in Mondo:

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

Search

Searching over OBO using ontobee:

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/BioPortal_Help#Getting_an_API_key)

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 "BIOPORTAL_API_KEY" to your environment variables.

Searching over more limited set of ontologies in Ubergraph:

runoak -v -i ubergraph: search tentacle

yields

UBERON:0013206 ! nasal tentacle

Annotating Texts

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

yields:

object_id: CL:0000540
object_label: neuron
object_source: https://data.bioontology.org/ontologies/NIFDYS
match_type: PREF
subject_start: 1
subject_end: 6
subject_label: NEURON

object_id: http://www.co-ode.org/ontologies/galen#Neuron
object_label: Neuron
object_source: https://data.bioontology.org/ontologies/GALEN
match_type: PREF
subject_start: 1
subject_end: 6
subject_label: NEURON

...

Mapping

Create a SSSOM mapping file for a set of ontologies:

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:

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

img

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

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

Same using pronto, fetching ontology from obolibrary

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.

Metadata

Release files for oaklib 0.7.5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for oaklib 0.7.5
File Size Uploaded Provenance Actions
oaklib-0.7.5.tar.gz 31.7 MB With provenance Details for oaklib-0.7.5.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for oaklib 0.7.5
File Interpreter ABI Platform Actions
oaklib-0.7.5-py3-none-any.whl Python 3 none any Details for oaklib-0.7.5-py3-none-any.whl

Total release size: 32.5 MB

Release files / oaklib-0.7.5.tar.gz

Download URL oaklib-0.7.5.tar.gz
Size 31.7 MB
Tags Source
SHA-256 checksum
How to use checksums
9f35702786da29ca4bc8189a10d38c3a5ae50cf07527cb9ac6377e3c71c918f1
BLAKE2b-256 checksum
How to use checksums
b2f014c59ea1c18420992430489f3971b51ecae9ba010ae10a871b5df73837fa
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / oaklib-0.7.5-py3-none-any.whl

Download URL oaklib-0.7.5-py3-none-any.whl
Size 739.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
69ba75efb2f7840662a615b4673764841aacbb7729357816e4064f2de18b31b2
BLAKE2b-256 checksum
How to use checksums
57d903372484c303d12e1ce9de049d7569457cbb98f7eb4d6ed10b3f58a19d32
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Security for oaklib 0.7.5

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for oaklib-0.7.5.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.7.5 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page