mevis

Welcome! You have found the documentation of the Python 3 package mevis.

What is this package?

Its name stands for metagraph visualization and its purpose is to support the OpenCog project with some additional filtering, conversion, layouting and plotting capabilities. OpenCog uses a knowledge representation called AtomSpace, which is named after atomic formulae in logic. In mathematical terms an AtomSpace is a generalized hypergraph, also referred to as metagraph. The following lists some relationships between graphs, hypergraphs and metagraphs that allow AtomSpaces to be transformed to graphs and then plotted with existing graph visualization methods such as those provided by gravis, which this package builds upon.

  • A graph consists of vertices and edges, also known as nodes and links. Each edge can connect exactly two vertices.

  • A hypergraph consists of vertices and generalized edges or hyperedges. Each hyperedge can connect an arbitrary number of vertices.

  • A metagraph consists of vertices and generalized hyperedges. Each generalized hyperedge can connect an arbitrary number of vertices but may also point to other edges and by transitivity to entire subgraphs.

  • A hypergraph can be converted to an equivalent bipartite graph, which is a graph with two disjoint and independent sets of vertices, one representing the original vertices and the other representing the hyperedges.

  • A metagraph can be converted in a similar fashion, but the resulting graph is not bipartite, because the two disjoint sets of vertices are not independent, since edges may connect vertices of the same kind.

OpenCog uses a metagraph to enable the integration of various data sources into one knowledge representation. This allows different machine learning and reasoning algorithms to operate together on a shared ground, with the aim to overcome their individual bottlenecks by cooperation and achievement of cognitive synergy. For further background information, there are accessible explanations of these concepts in interviews with Ben Goertzel on the Lex Fridman podcast and Towards Data Science podcast, as well as an in-depth article by Linas Vepstas that motivates the use of a metagraph representation in detail. Beyond that, there are numerous articles on the OpenCog Wiki and academic publications by Ben Goertzel, Linas Vepstas and their colleagues. There are also recorded talks that were given at OpenCogCon and various AGI conferences.

How can it be used?

To get a first impression of the package in action, here is a small code example. More comprehensive examples are available on separate pages.

import mevis as mv

atomspace = mv.load('moses.scm')
mv.plot(atomspace, 'vis', 'dot').export_html('moses_vis.html')
mv.plot(atomspace, 'three', 'neato').export_html('moses_three.html')
mv.plot(atomspace, 'd3', 'bipartite', edge_curvature=0.4).export_html('moses_d3.html')

atomspace = mv.load('rocca.scm')
atoms = mv.filter(atomspace, target=['SLink', 'MemberLink'], mode='exclude')
graph = mv.convert(atoms, node_size=lambda atom: 30 if atom.type_name == 'SchemaNode' else 8)
graph = mv.layout(graph, 'twopi', scale_x=2.0, scale_y=2.0)
fig = mv.plot(graph, 'vis')
fig.export_html('rocca_vis.html')

Results: This script generates the files moses_vis.html, moses_three.html, moses_d3.html and rocca_vis.html. These are self-contained HTML files, which means that they render without loading any external resources and can be shared easily. The package also allows to embed visualizations directly into Jupyter notebooks or open them in a webbrowser window instead of creating standalone HTML files.

Interpretation: An AtomSpace consists of Atoms, which can be divided into Nodes and Links. They are represented in this graph visualization by red and black nodes, respectively. Link-to-Node connections are represented by red edges and Link-to-Link connections by black edges. Hovering over a node shows its Atomese code.

Why is it relevant?

During the development of OpenCog different requirements for AtomSpace visualizations have appeared and at least eight visualization attempts were created to meet some of them, but most have become obsolete by now. This package is yet another attempt to fulfill some requirements and be of help in certain situations described below. Its tight integration with Jupyter notebooks is perhaps its most distinguishing feature in comparison to other approaches.

When should it be used?

  • Small graphs in Jupyter notebooks: mevis is most useful for quick and interactive explorations of AtomSpaces below 1000 Atoms in Jupyter notebooks. Larger AtomSpaces can also be explored with some patience during rendering, but better by filtering them first so that the number of remaining Atoms is in a lower range. Notebooks can be exported as HTML files and shared with others, because the visualizations do not depend on external resources such as local files.

  • Small graphs in HTML files or as HTML text: mevis can export plots as HTML files, which can also be shared with others, e.g. by embedding them into static websites such as this documentation. Another option is to read the HTML text of a plot and serve it as response to HTTP requests in a web app (e.g. with Flask or Django).

  • Large graphs in external programs: mevis can convert AtomSpaces to annotated NetworkX graphs and export them in GML format or better in its compressed variants. This also works well with large AtomSpaces. The resulting .gml, .gml.gz or .gml.bz2 files can be read directly by external programs such as Cytoscape, Gephi or Tulip, which are able to visualize very large graphs, though layout calculation may take quite a while.

  • Command line interface: After installing this Python package with pip, the command mevis should be available in the shell, which offers usage via CLI. It allows to load an AtomSpace from a .scm file, optionally filter it, convert it to a graph, optionally calculate a layout, and finally export the annotated graph to a GML file or create a plot of it, which can be displayed in a browser or exported to a HTML file. Thus the CLI allows to use most features of the package without having to write any Python code.

Who can benefit from it?

  • OpenCog developers: Quick visual feedback can help when new data sources are integrated into a single AtomSpace or when algorithms operating on AtomSpaces are developed and tested.

  • OpenCog users: Simple visualization of AtomSpaces can help new arrivals but also experienced users by providing broad overviews or filtered perspectives of what is going on in a metagraph.

  • General audience: OpenCog concepts such as knowledge representation with metagraphs, expression of both data and programs in Atomese, cognitive synergy of algorithms that can act on the same data, and similar ideas can be explained more vividly with accompanying visualizations and thereby might become more palpable to a diverse audience.

How can you get started?

  • The installation guide explains how to download and install the package and its dependencies.

  • The examples provide an easy way to get started with using the package.

  • The API documentation is the single source of truth for all details about each available function.

Where is everything located?

The package reference page contains links to all parts of this project, including source code (with tests, docs, examples), packaged code (for distribution via PyPI and pip) and this documentation website.

Table of website contents