INCATools / INCATools/ontology-access-kit
Define general patterns for CLI commands
- 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
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