Command Line

Note

we follow the CLIG guidelines as far as possible

General Guidelines

Note

if you are running this as an internal OAK developer you need to precede the command with poetry shell

The general structure is:

runoak --input HANDLE COMMAND [COMMAND ARGS AND OPTIONS]

The value for --input (which can be shorted to -i) is specified in the Ontology Adapter Selectors documentation.

Examples:

runoak --input ubergraph: COMMAND [COMMAND ARGS AND OPTIONS]
runoak --input fbbt.obo COMMAND [COMMAND ARGS AND OPTIONS]
runoak --input cl.db COMMAND [COMMAND ARGS AND OPTIONS]
runoak --input sqlite:obo:cl COMMAND [COMMAND ARGS AND OPTIONS]

It can be useful to create aliases for individual ontologies. For example, to create an alias for the Uberon ontology:

alias uberon='runoak -i obo:sqlite:uberon'
alias cl='runoak -i obo:sqlite:cl'
alias obi='runoak -i obo:sqlite:obi'

You can specify further implementations with -a which will create an aggregator implementation that wraps multiple implementations. For example, you can multiplex queries over different endpoints.

Common Patterns

Term Lists

Many commands take a term or a list of terms as their primary argument. These are typically one of:

  • a CURIE such as UBERON:0000955

  • a Search Syntax term, which is either:

    • an exact match to a label; for example “limb” or “plasma membrane”

    • a compound search term such as t~limb which finds terms with partial matches to limb

Search terms are expanded to matching CURIEs, and then fed into the command.

For example, (assuming the alias above) the following command will look up two terms using their labels:

uberon info hand foot

This is equivalent to:

uberon info UBERON:0002398 UBERON:0002397

Predicates

Many commands take a --predicates option (shortened to -p). This specifies a list of predicates (aka relationship types, see Predicates) to be used in filtering. The list is specified as a comma-delimited list (no spaces) of CURIEs.

For many biological ontologies, it can be useful to filter on is_a (rdfs:subClassOf) and part_of (BFO:0000050) so the command line interface understands shortcuts for these:

  • i: is-a (i.e rdfs:subClassOf between two named classes)

  • p: part-of

For example, to draw the subgraph of terms starting from “hand” and “foot” and tracing upwards through is_a and part_of relationships:

uberon viz -p i,p hand foot

Commands

The following section is autogenerated from the inline docs. You should get the same results by running:

runoak COMMAND --help

For example, to get help on the viz command:

runoak viz --help