obographviz
v0.4.3
Published
Visualize OBO graphs with (Graph)Viz.js.
Downloads
117
Readme
Translate OBO Graphs into Dot/Graphviz
- Input: a OBO Graph JSON object
- Optional: a JSON ontology stylesheet
- Output: a Dot-format / Graphviz file
Requirements
- Node.js ≥ 14.16
Installation
The obographviz
package can be installed via NPM either locally or globally. If you're not familiar with NPM, see the following to get started:
If you intend to primarily use the command line tool provided by this package or you're using a tool like Ontology Access Kit which depends on it, install globally:
npm install -g obographviz
Once installed globally, the og2dot
executable will automatically be added to your PATH
.
Otherwise, if you want to use the package in an existing Node.js project install it locally:
npm install obographviz
Quickstart
Command line
All examples in this README assume obographviz
has been installed globally. If it was installed locally to a project, call og2dot
via npx
or an npm script.
See the examples
directory in this repositories for sample OBO Graph JSON files and stylesheets.
og2dot simple-og.json > test.dot
dot test.dot -Tpng -Grankdir=BT > test.png
API
import { OboGraphViz } from "obographviz";
const obograph = { ... }
const compoundRelations = ['BFO:0000050']
const styleMap = {}
const gv = new OboGraphViz(obograph)
const dot = gv.renderDot(compoundRelations, styleMap)
console.log(dot)
Features
Nesting
One or more predicates can be designated as 'compound', i.e. used for nesting.
On the command line, use -c
. In the API, use compoundRelations
Example:
og2dot -c is_a simple-og.json > test.dot
Generates:
Note only works for subgraphs that exhibit disjointness over this property, acyclicity
Use the -I
option for inverting the containment relation (e.g. to use has part
rather than part of
).
Stylesheets
In the API can be passed using styleMap
. On the command line, by using either -s
(to pass a JSON file) or -S
(to pass stringified JSON object directly on command line)
E.g.
og2dot -s example-style.json -c is_a simple-og.json > test.dot
Stylesheet Standard
This is now documented separately:
Global stylemap properties
These go in the root of the stylemap object
{
"style": "filled",
"fillcolor": "green"
}
this sets all nodes to be filled green
Edge properties by relationship type
Each relationship type can have its own individual style, by passing relationProperties. This is keyed by the CURIE for the relation (or "is_a" for subClassOf):
{
"relationProperties": {
"is_a": {
"color": "black",
"penwith": 3,
"arrowhead": "open",
"label": ""
},
"BFO:0000050": {
"arrowhead": "tee",
"color": "blue"
}
}
}
Node properties by prefix
Pass in prefixProperties to be able to assign individual properties for ontology prefixes. This can be useful when visualization graphs that combine multiple ontologies
{
"prefixProperties": {
"SO": {
"fillcolor": "yellow"
},
"RO": {
"fillcolor": "pink"
},
"BFO": {
"fillcolor": "cyan"
}
}
}
Conditional properties
Arbitrary conditions can be set using conditionalProperties
for example:
{
"conditionalProperties": [
{
"conditions": {
"subset":"efo_slim"
},
"properties": {
"fillcolor": "blue"
}
}
]
}
This will color any node in the efo_slim
subset blue.
Combined Example
The following example uses all subclasses of digit in Uberon, plus their ancestors, which forms a complex lattic structure.
See digit.json for the underlying ontology. See examples/uberon-style.json for the stylesheet.
og2dot -s uberon-style.json digit.json -t png -o digit.png
Renders:
Nesting of Equivalence Sets
Optionally, cliques of classes interconnected with either equivalence axioms or xrefs will be clustered.
The file uberon-zfa-xref-example.json contains a subset of both UBERON, ZFA, and two Allen brain ontologies, with UBERON classes xref-ing equivalent ZFA classes.
og2dot -s uberon-zfa-style.json uberon-zfa-xref-example.json -t png -o uberon-zfa-xref-example.png
Renders:
(Uberon: yellow, ZFA:black, MBA: pink, HBA: grey, black lines = IS_A, blue lines = part_of, equivalence sets as bounding boxes)
The predicates used to build these can be configured in the json style file, e.g.:
"cliqueRelations": [
"xref", "equivalent_to", "same_as"
]
Note: to style the bounding box in a stylesheet, the cliques are considered to be in the ID space %CLIQUE
"prefixProperties": {
"%CLIQUE": {
"fillcolor": "hotpink"
},
"GO": {
"fillcolor": "yellow"
},
}
Rendering anonymous and pseudo-anonymous individuals
E.g. GO-CAM models
{
"nodeFilter" : {
"type": "INDIVIDUAL"
},
"labelFrom": "type"
}
og2dot -c BFO:0000050 -c RO:0002333 -s gocam-style.json lego-example2.json
Integration with other components
Configuring individual nodes or edges
As well as configuring via style sheets, an individual node or edge can configure its display by using an annotation assertion with a property in https://w3id.org/kgviz/
, e.g.:
{
"sub": "GO:0031090",
"pred": "BFO:0000050",
"obj": "GO:0043227",
"meta": {
"basicPropertyValues": [
{
"pred": "https://w3id.org/kgviz/penwidth",
"val": 10
}
]
}
}
Ontology Access Kit
This library is integrated into Ontology Access Kit (OAK) to support its viz
subcommand. For example:
runoak -i ontobee: viz HP:0000787
This proceeds by:
- Using the python oaklib library to extract a subgraph around the specified node
- Write as obographs-json
- Calls og2dot
Use from biolink-api REST
Go to http://api.monarchinitiative.org/api/
See the /ontol/subgraph/
route
This exports obographs which can be fed in to this js lib
TODO - link to demo site
Use with AmiGO
AmiGO uses bbop-graphs; these are similar enough that they can be passed in instead of obographs.
Development
Javascript and TypeScript files in the lib
directory are compiled using tsc
into the dist
directory. To compile once use:
npm run build
To watch for file changes and compile incrementally use:
npm run dev
Before committing changes run the test suite with:
npm test
FAQ
Why Dot/GraphViz?
Why not D3, cytoscape js etc?
These are all very nice and pretty, but GraphViz has some powerful features that I have not found in any other framework (or have been too lazy to find out how to do). In particular:
- Easy to run on command line
- The ability to nest relationships (update: compound graphs in cytoscape.js)
- simple control over box and edge visual attributes
- embedding arbitrary HTML
This is intended to replace blipkit graphviz generation. For some examples, see mondo report