INCATools / INCATools/ontology-access-kit

Define general patterns for CLI commands

Open
#145 2 comments 1 reaction 0 assignees View on GitHub
design
Dominant language
Python
Stars
198
Forks
35
Avg merge
3d 4h
Merged PRs (30d)
1

Description

I like how robot has a very predictable pattern for commands/operations, with most named as a single verb

This is the current set of commands:

|command|desc|
|---|---|
|add-taxon-constraints|Test candidate taxon constraints
|aliases|List all aliases in the ontology
|all-obsoletes|Shows all obsolete nodes
|all-similarity|All by all similarity
|all-subsets|Shows all subsets
|ancestors|List all ancestors
|annotate|Annotate a piece of text using a Named Entity...
|axioms|List all axioms
|check-definitions|Check definitions
|combine|Perform set-wise combination operation on two...
|descendants|List all descendants of a term
|diff-ontologies|EXPERIMENTAL
|diff-terms|EXPERIMENTAL
|dump|Exports an ontology
|extract-subset|Extracts a subset
|extract-triples|Extracts a subontology as triples
|filter-axioms|Filters axioms
|info|Show info on terms
|leafs|List all leaf nodes in the ontology
|lexmatch|Generates lexical index and mappings
|list-subset|Shows IDs in a given subset
|mappings|List all SSSOM mappings in the ontology
|migrate-curies|Rewires an ontology replacing all instances of...
|ontologies|Shows ontologies
|ontology-metadata|Shows ontology metadata
|ontology-versions|Shows ontology versions
|relationships|Show all relationships for a term or terms
|roots|List all root in the ontology
|search|Searches ontology for entities that have a...
|set-apikey|Sets an API key
|set-obsolete|Sets an ontology element to be obsolete
|siblings|List all siblings
|similarity|Determine pairwise similarity between two terms...
|subset-rollups|For each subset provide a mapping of each term...
|taxon-constraints|List all taxon constraints for a term or terms
|term-mappings|List all SSSOM mappings for a term or terms
|term-metadata|Shows term metadata
|terms|List all terms in the ontology
|tree|Display an ancestor graph as an ascii/markdown tree
|validate|Validate an ontology against ontology metadata
|validate-multiple|Validate multiple ontologies against ontology...
|viz|Visualizing an ancestor graph using obographviz

(this may change, to get the current list go to https://incatools.github.io/ontology-access-kit/cli.html)

There are a few redundancies that will be tidied up before the 0.2.0 milestone. There is a general unifying theme to all these commands

With a few exceptions (e.g. set-apikey) these take as arguments **term lists** which are lists of CURIEs or search terms or directives or boolean combinators of these. They always evaluate to a **list of ontology element curies**, e.g list of classes, and the command operates on these.

E.g. to see info on all terms matching a union of search terms:

```
cl info t~neuron t~brain
```

or to intersect these:

```
cl info t~neuron .and t~brain
```

`.all` is also a valid search term that yields all terms, so to list every term:

```
cl info .all
```

you can also explode things like this (NOT RECOMMENDED):

```
cl viz .all
```

This search language will be the subject of another ticket. This ticket is about harmonizing the commands themselves

Previously there was more redundancy - e.g. we had `relationships` which took terms as arguments and showed relationships for all these terms and also `all-relationships` which listed every edge in an ontology.

This has since been unified to a single `relationships` command, if this is passed without any arguments then it will show all relationships, otherwise it will show all relationships where any of the input terms is a subject

This suggests a general pattern that can be used, with the name of the command being some kind of *statement type*, with the default behavior being to show all statements of this type, or just statements for the input terms

E.g. to see a table of all ID-label tuples:

```
foodon labels
```

(note most commands also allow selection of different output types but this is not covered here)

or just the labels for specific terms:

```
foodon labels FOODON:03309463 FOODON:03306622
```

the general pattern applies for: aliases, definitions, ancestors, relationships, descendants, (arbitrary) owl axioms, ...

It can also apply to computed n-ary relationships, e.g. similarity

If we follow this we can get rid of the remaining `all-X` commands and unify in an `X` command

Then the only hyphenated commands should be **do** commands - apply a change, make a term obsolete, set an API key

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the current CLI command list at the linked cli.html documentation and compare the existing statement-oriented and do commands. Define the consistent statement-type naming and argument behavior described in the issue, then identify the redundant all-X commands and verify that only change operations retain hyphenated names.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
cli
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
20/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.