OAK Guide

Overview

OAK is a powerful command line library for accessing ontologies. It can be installed via:

• uv add oaklib
• pip install oaklib

The main command is runoak

When to use

OAK is generally to be used for more complex operations.

• if you want to do basic search over external ontologies, you should favor the OLS MCP over OAK
• if you are working with local obo files, then hacky obo tools like obo-grep.pl may be better

Adapters

You typically want to use the sqlite adapter. This gives you fast access to any ontology in OBO, plus a number of other commonly used ontologies, found in semantic-sql.

Example:

runoak -i sqlite:obo:cl COMMAND COMMAND-OPTS ARGS

Note the -i comes (before) the command-specific opts

You can also access any ontology in OLS or BioPortal:

• runoak -i bioportal:snomedct relationships SNOMEDCT:128351009
• runoak -i bioportal:efo tree -p i EFO:0004200

But some OAK commands may not be implemented.

With OLS or BioPortal you can also do searches over all ontologies:

• runoak -i bioportal: info l~NovaSeq
• runoak -i ols: info l~NovaSeq

To work with local obo files:

• runoak -i impleobo:my_ont.obo info MY:1234 -O obo

Common Operations

You can find a list of all commands with runoak --help. oak is highly fully featured, and you are encouraged to explore to find the functionality you need. We provide some examples below.

We use info for many examples, but note that many options and arguments work across different commands

• Lookup
  • By exact label: runoak -i sqlite:obo:cl info neuron (returns CL:0000540 ! neuron)
  • By exact label (multiple): runoak -i sqlite:obo:uberon info finger toe
  • Search (any match): runoak -i sqlite:obo:cl info 'l~T cell'
  • Search (starts with): runoak -i sqlite:obo:cl info l^neuron
• Fetching detailed info
  • OBO format: runoak -i sqlite:obo:cl info CL:0000540 -O obo
  • relationships: runoak -i sqlite:obo:cl relationships --direction both CL:0000540
  • mappings: runoak -i sqlite:obo:mondo mappings 'Marfan syndrome'
  • tree (is-a only): runoak -i sqlite:obo:cl tree -p i CL:0000540
  • metadata: runoak -i sqlite:obo:chebi term-metdata CHEBI:35235
• Complex queries
  • subclasses: runoak -i sqlite:obo:cl info .sub CL:0000540 | head
  • disjunctions (OR): runoak -i sqlite:obo:cl info .sub neuron .sub 'T cell' | tail
  • conjunctions: runoak -i sqlite:obo:cl info .sub neuron .and .desc//p=i,p forebrain (neurons and is-a/part-of the forebrain)
  • minus: runoak -i sqlite:obo:cl info .sub neuron .minus .desc//p=i,p forebrain (neurons and NOT is-a/part-of the forebrain)
• Visualization
  • cl viz -p i,p,RO:0002215 'dopaminergic neuron' -o /tmp/dn.png - subgraph from a CL term.
  • note that graphviz requires installing og2dot
• Subsets
  • list subsets: runoak -i sqlite:obo:go subsets - list all subsets (goslim_prokaryote etc)
  • terms in subsets: runoak -i sqlite:obo:go info .in goslim_generic - all terms in a subset
  • terms in subsets: runoak -i sqlite:obo:go info .in goslim_generic .minus .in goslim_prokaryote - all terms in a subset not in another
• Other
  • runoak lexmatch --help for aligning ontologies
  • runoak statistics --help for summary stats

Common Options and Idioms

Graphs

OAK is very graph oriented, following ontologies like GO, CL

Typically for graph operations you want to operate over only is-a and part-of, so use -p i,p

You can also specify RO/BFO ids.

E.g.

runoak -i sqlite:obo:ro info 'capable of'
RO:0002215 ! capable of

cl relationships -p RO:0002215 'dopaminergic neuron'
subject	predicate	object	subject_label	predicate_label	object_label
CL:0000700	RO:0002215	GO:0061527	dopaminergic neuron	capable of	dopamine secretion, neurotransmission