Command line interface¶
This Jupyter notebook gives an overview of the command line interface (CLI) that comes with the Python package mevis after installation with pip. The .ipynb file can be found here.
Show the help text¶
[1]:
!mevis -h
usage: mevis [-h] -i input_filepath [-o output_filepath] [-f] [-v]
[-b backend] [-l layout_method] [-cd capture_delay]
[-ft filter_target] [-fc filter_context] [-fm filter_mode] [-gua]
[-gud] [-nl node_label] [-nc node_color] [-no node_opacity]
[-ns node_size] [-nsh node_shape] [-nbc node_border_color]
[-nbs node_border_size] [-nlc node_label_color]
[-nls node_label_size] [-nh node_hover] [-ncl node_click]
[-ni node_image] [-np node_properties] [-el edge_label]
[-ec edge_color] [-eo edge_opacity] [-es edge_size]
[-elc edge_label_color] [-els edge_label_size] [-eh edge_hover]
[-ecl edge_click] [--kwargs [KWARGS [KWARGS ...]]]
Visualize an OpenCog Atomspace as graph with two kinds of vertices.
optional arguments:
-h, --help show this help message and exit
-i input_filepath path of input file (.scm) containing an Atomspace
-o output_filepath path of output file, with following cases
- none create plot and display it in webbrowser
- .html create plot and export it to a HTML file
- .jpg create plot and export it to a JPG file
- .png create plot and export it to a PNG file
- .svg create plot and export it to a SVG file
works only with backend d3
- .gml create graph and export it to GML file
- .gml.gz same but file is compressed with gzip
- .gml.bz2 same but file is compressed with bzip2
-f, --force overwrite output_filepath if it already exists
-v, --verbose print messages about intermediary results
-b backend backend library for graph visualization
"d3" = d3.js
"vis" = vis-network.js
"three" = 3d-force-directed.js using three.js
-l layout_method layout method to calculate node coordinates
- "dot"
- "neato"
- "twopi"
- "circo"
- "fdp"
- "sfdp"
- "bipartite"
- "circular"
- "kamada_kawai"
- "planar"
- "random"
- "shell"
- "spring"
- "spectral"
- "spiral"
-cd capture_delay delay in seconds when capturing a static image
for JPG/PNG/SVG export. Default: 3.5
-ft filter_target filter target to select Atoms
-fc filter_context filter context to expaned selected atoms to
- "atom" = selected Atoms
- "in" = selection + incoming neighbors
- "out" = selection + outgoing neighbors
- "both" = selection + incoming and outgoing
neighbors
- "in-tree" = selection + repeated incoming
neighbors
- "out-tree" = selection + repeated outgoing
neighbors
- "('in', n)" = selection + incoming neighbors
within distance n
- "('out', n)" = selection + outgoing neighbors
within distance n
- "('both', n)" = selection + incoming and outgoing
neighbors within distance n
-fm filter_mode filter mode deciding how to use the selection
- "include" = include selected Atoms to output
- "exclude" = exclude selected Atoms from output
-gua graph is unannotated, no properties are added
-gud graph is undirected, no arrows are drawn
-nl node_label text shown below node
-nc node_color
-no node_opacity
-ns node_size
-nsh node_shape
-nbc node_border_color
-nbs node_border_size
-nlc node_label_color
-nls node_label_size
-nh node_hover text shown when hovering with mouse over a node
-ncl node_click text shown in div below plot when clicking on a node
-ni node_image image drawn inside node, URL or data URL
-np node_properties other annotations for a node given as key/val dict
-el edge_label text shown in midpoint of edge
-ec edge_color
-eo edge_opacity
-es edge_size
-elc edge_label_color
-els edge_label_size
-eh edge_hover text shown when hovering with mouse over an edge
-ecl edge_click text shown in div below plot when clicking on an edge
--kwargs [KWARGS [KWARGS ...]]
optional keyword arguments forwarded to plot function
Use it minimalistically¶
-i: An input file (.scm) to load an AtomSpace from.-o: An optional output file.
Following three cases are possible.
No output file: Creates a graph visualization and displays it in the default webbrowser.
[2]:
!mevis -i moses.scm
Output file ending with
.html: Creates a graph visualization and stores it to a HTML file.
[3]:
!mevis -i moses.scm -o moses.html
argparse.ArgumentTypeError: The provided output_filepath "moses.html" already exists. You can use --force to overwrite it.
Output file ending with
.gml,.gml.gzor.gml.bz2: Creates a graph representation and stores it to a GML file that can be compressed with gzip or bzip2 to considerably reduce size.
[4]:
!mevis -i moses.scm -o moses.gml
!mevis -i moses.scm -o moses.gml.gz
!mevis -i moses.scm -o moses.gml.bz2
Show status messages and overwrite existing files¶
--verbose: If provided, messages are printed about individual steps and their intermediate results.--force: If provided, output files are overwritten if they already exist.
[5]:
!mevis -i moses.scm -o moses.html --force --verbose
Importing an Atomspace from file "moses.scm".
Done. It contains 16 Atoms.
Converting the AtomSpace to a graph
Done. It contains 16 vertices and 21 edges.
Storing a visualization as HTML file to "moses.html".
Done. It has a file size of 646834 bytes.
Choose another backend¶
-b: If provided, the chosen backend is used to create the visualization. For available options, please look at the help text.
[6]:
!mevis -i moses.scm -o moses_d3.html -b d3
!mevis -i moses.scm -o moses_three.html -b three
!mevis -i moses.scm -o moses_vis.html -b vis
Calculate a layout¶
-l: If provided, the chosen method is used for calculating x and y coordinates for nodes. For available options, please look at the help text.
[7]:
!mevis -i moses.scm -o moses_layout1.html -l dot --verbose
Importing an Atomspace from file "moses.scm".
Done. It contains 16 Atoms.
Converting the AtomSpace to a graph
Done. It contains 16 vertices and 21 edges.
Calculating a layout with "dot".
Done.
Storing a visualization as HTML file to "moses_layout1.html".
Done. It has a file size of 647318 bytes.
[8]:
!mevis -i moses.scm -o moses_layout2.html -l neato
!mevis -i moses.scm -o moses_layout3.html -l twopi
!mevis -i moses.scm -o moses_layout4.html -l bipartite
!mevis -i moses.scm -o moses_layout5.html -l shell
Filter the AtomSpace¶
-t: Filter target which selects Atoms. There are three options on the command line:Name that is compared against Atom name and type name.
List of multiple names
Lambda function that gets an Atom as input and must return True or False to select or deselect it.
-c: Filter context which can expand the selection.-m: Filter mode which decides whether the selection is included or excluded from the result
Some possible targets
[9]:
!mevis -i moses.scm -o moses_filtered1.html -ft PredicateNode --verbose
!mevis -i moses.scm -o moses_filtered2.html -ft "['AndLink', 'OrLink', 'NotLink']"
!mevis -i moses.scm -o moses_filtered3.html -ft "lambda atom: atom.is_link()"
Importing an Atomspace from file "moses.scm".
Done. It contains 16 Atoms.
Filtering the AtomSpace
Done. It contains 5 remaining Atoms.
Converting the AtomSpace to a graph
Done. It contains 5 vertices and 0 edges.
Storing a visualization as HTML file to "moses_filtered1.html".
Done. It has a file size of 642835 bytes.
Some possible contexts
[10]:
!mevis -i moses.scm -o moses_filtered4.html -ft PredicateNode -fc both
!mevis -i moses.scm -o moses_filtered5.html -ft PredicateNode -fc "('in', 2)"
!mevis -i moses.scm -o moses_filtered6.html -ft OrLink -fc "out-tree"
Two possible modes
[11]:
!mevis -i moses.scm -o moses_filtered7.html -ft PredicateNode -fc both -fm include
!mevis -i moses.scm -o moses_filtered8.html -ft PredicateNode -fc both -fm exclude
Annotate the graph to modify visual elements¶
[12]:
# Create an unannotated graph
!mevis -i moses.scm -o moses_unannotated.html -gua
[13]:
# Create an undirected graph and set its node color, node size, edge color, edge size with constants
!mevis -i moses.scm -o moses_annotated1.html -gud -nc blue -ns 20 -ec blue -es 4
[14]:
# Set node color, node size, edge color, edge size with lambda functions
!mevis -i moses.scm -o moses_annotated2.html \
-nc "lambda atom: '#33339a' if atom.is_link() else 'green'" \
-ec "lambda atom1, atom2: '#33339a' if atom2.is_link() else 'green'" \
-ns "lambda atom: 12 if atom.is_node() else 18" \
-es "lambda atom1, atom2: 1 if atom2.is_node() else 3"
[15]:
# Adjust all possible annotations (see advanced.ipynb for the same example in Python instead of Bash)
!mevis -i moses.scm -o moses_annotated3.html -f \
-b d3 \
-gud \
-nl "lambda atom: atom.name if atom.is_node() else atom.type_name.replace('Link', '')" \
-nc "lambda atom: 'red' if atom.is_node() \
else 'blue' if atom.type_name == 'AndLink' \
else 'green' if atom.type_name == 'OrLink' \
else 'orange'" \
-no 0.9 \
-ns "lambda atom: 20 if atom.type_name in ['AndLink', 'OrLink'] else 12" \
-nsh "lambda atom: 'rectangle' if atom.type_name == 'AndLink' \
else 'hexagon' if atom.type_name == 'OrLink' \
else 'circle'" \
-nbc white \
-nbs 2.0 \
-nlc "lambda atom: 'red' if atom.is_node() \
else 'blue' if atom.type_name == 'AndLink' \
else 'green' if atom.type_name == 'OrLink' \
else 'orange'" \
-nls 12.0 \
-nh "lambda atom: 'A {} with Atomese code:\n{}'.format(atom.type_name, atom.short_string())" \
-ncl "lambda atom: atom.short_string()" \
-np "lambda atom: dict(x=-300) if atom.is_node() else dict(x=-300+200*len(atom.out))"\
-el "lambda atom1, atom2: '{}{}'.format(atom1.type_name[0], atom2.type_name[0])" \
-ec "lambda atom1, atom2: 'lightgray' if atom2.is_node() \
else 'red' if atom1.is_node() \
else 'blue' if atom1.type_name == 'AndLink' \
else 'green' if atom1.type_name == 'OrLink' \
else 'orange'" \
-eo 0.5 \
-es "lambda atom1, atom2: 5 if atom2.is_node() else 2.5" \
-elc "lambda atom1, atom2: 'red' if atom1.is_node() \
else 'blue' if atom1.type_name == 'AndLink' \
else 'green' if atom1.type_name == 'OrLink' \
else 'orange'" \
-els 8 \
-eh "lambda atom1, atom2: '{} to {}'.format(atom1.type_name, atom2.type_name)" \
-ecl "lambda atom1, atom2: 'Edge connects {} with {}'.format(atom1.type_name, atom2.type_name)" \
--kwargs edge_curvature=0.2 show_edge_label=True many_body_force_strength=-1000