TensorFlow-Models/syntaxnet/dragnn/viz

DRAGNN trace visualizer

This mini project builds an interactive JavaScript-based visualization for DRAGNN traces.

Using the visualizer

We'll check in a pre-compiled version of the visualization, once it isn't changing much. Then you can just inject it in an IPython notebook; given a JSON trace string master_trace_json, and the pre-compiled Javascript in library_js, the following Python code will display the visualization,

from IPython.display import HTML

HTML("""
<div id="{elt_id}" style="width: 100%; min-width: 200px; height: 700px;">
</div>
<script type='text/javascript'>
{library_js}

visualizeToDiv({json}, "{elt_id}");
</script>
""".format(library_js=library_js, json=master_trace_json, elt_id="foo-123"))

Development

Running the development server

To run the development server, first install Docker, then run the develop.sh script in this directory. Then, open http://127.0.0.1:9000/; you should see a sample graph. Whenever you edit one of the .js or .jsx files, the browser should auto-refresh. If your code has an error, it should display in the development console (press ctrl+shift+j to open it in Chrome).

If you need to add a new package, it's recommended to add a line like

RUN npm-install my-new-package --save-dev

to the Dockerfile. If you immediately modify package.json, by contrast, Node will go re-download everything (this is more a function of Docker caching than Node). Please make sure that the new package's license is compatible with DRAGNN's license.

Modifying packages or the Webpack configuration will require a restart of the development server. Simply send SIGINT (ctrl+c in a shell), and re-run develop.sh.

General library use and code structure

Most of the visualization is currently based on cytoscape.js. On the downside, Cytoscape does not render edges as beautifully as GraphViz (the latter is great at minimizing edge crossings). However, its interactivity may be an advantage for visualizing larger graphs.

Element layout uses Preact, a React-style templating language. It claims to be small, modern, and high-performing. To style elements, we directly attach their styles using Preact code. This avoids CSS namespace pollution, which is very important because our graphs are expected to cohabit with other elements in an IPython notebook or such.

Main invocation

The base script is visualize.js, and its main function is visualizeToDiv (client usage is demonstrated in the "Using the visualizer" section).

Layout

Most complexity is currently in the layout. Currently, we attempt to communicate ordering of step nodes within each component, and also arrange the components in a way that looks sensible. Currently, this is done by running an initial layout, then running Cytoscape's spring solver ("cose") to determine the best ordering of components and directionality of steps within each component, and finally running the fancier layout engine.

In the future, it would probably be nice to remove the spring solver (and initial layout). We should pass through the master specification, so the layout has information about which components are left-to-right vs. right-to-left. We can determine the order of components by looking at the number of edges from one component to the other.