Graph Visualization & Python: Integrating KeyLines with Jupyter

8th January, 2018

Enriching Jupyter Notebooks with Graph Visualization

Sharing intelligence is a key part of every graph analysis workflow. Once your connected data has been explored, filtered, SNA’d, combo’d, and generally understood by an analyst, their next step is to share their new-found insight with colleagues.

There’s already KeyLines functionality to facilitate that – serialise, export as PNG, etc – but how about integrating with the tools your analysts already use?

The beauty of KeyLines as a library is that integrating with other technologies is usually simple. In this blog, we’ll see how KeyLines can plug into the Jupyter Notebook.

What is Jupyter Notebook?

To quote the Jupyter website: “The Jupyter Notebook is an open-source web application that allows you to create and share documents that contain live code, equations, visualizations and narrative text.”

It’s an app that gives analysts a single place to clean, model, analyse and visualize their data. You can embed other tools and technologies, and multiple analysts can work together on a single notebook. We’ve found it’s especially popular with data scientists in domains like intelligence and cyber security where collaboration and insight sharing is critical.

Historically, Jupyter Notebook was for sharing and prototyping in Python – that’s where the ‘py’ in Jupyter comes from. These days you can use many other languages, including (crucially for KeyLines) JavaScript.

Why integrate KeyLines and Jupyter?

Within a single notebook you could have multiple languages (Python, Haskell, JavaScript, etc.,) each one held in its own ‘cell’, passing data to the next cell. Add in visualization libraries and a notebook becomes a powerful tool to manipulate and understand datasets.

Clearly, if you’re working with connected data inside Jupyter, embedding KeyLines will be very useful. Happily it’s also very straightforward…

Embedding KeyLines in Jupyter Notebook

In this article, I’m using Jupyter Notebook version 4.3.0. We haven’t tested it with other versions, and can’t guarantee these steps will work for all future versions. That said, if you do have any problems our excellent support team is on hand to help.

Step 1: Set up the directories

The first thing to do is download your KeyLines files from the SDK site (request a trial account here if you don’t already have one).

Next, create a new directory for the notebook. In this directory, place the ‘assets’ folder that comes with KeyLines. It contains the images needed for your chart navigation controls.

Then, make the keylines.js file accessible to your notebook. The easiest way to do this is to move it to your nbextensions folder, which is created by default when you install Jupyter Notebook. On my Mac machine, this global directory can be found at: ~/.ipython/nbextensions.

Step 2: Create a new notebook

Now create a notebook in the same directory as the assets folder, and load it to see your blank starting point.

Step 3: Set to JavaScript and configure settings

The default language for your notebook will probably be Python. To start writing JavaScript in a new cell, at the top of the cell, enter:

%%javascript

By default, there are two JavaScript libraries available for us to use without having to do a manual import: jQuery and require.js. Both of these will be useful for our KeyLines integration.

We start our integration by making sure that on subsequent runs of our notebook/cell the keylines div is cleared from the page. To do this we use jquery:

$('#kl').remove();

Jupyter also has a global variable called ‘element’. This is the DOM element in which we can render the results of our cell (appearing below the cell). In our next line of JavaScript, let’s append a div for KeyLines to use:

element.append('<div id="kl"style="width:200px;height:200px"></div>');

We could change the width/height of our chart, but this default is fine.

Step 4: Get the KeyLines library

Now let’s use require.js to get the KeyLines library we previously installed in the nbextensions directory. Within the callback of require, we now have complete access to the KeyLines API.

require(["nbextensions/keylines"], function (KeyLines) {
  // We can use the KeyLines API as normal in here
});

Now you just need to click ‘run’ on the notebook or cell and that’s it! By this point, you should have a KeyLines chart sitting inside your Jupyter Notebook. The full code for this example would look something like this:

%%javascript
$('#kl').remove();
// element is a special global top level element in jupyter notebooks
element.append('<div id="kl" style="width:200px;height:200px"></div>');
require(["nbextensions/keylines"], function (KeyLines) {
    KeyLines.promisify();
    KeyLines.create({type: 'chart', id: 'kl'}).then(chart => {
        chart.load({
            type: 'LinkChart',
            items: [{
            id: 'a',
            type: 'node',
            c: 'blue',
            t: 'a'
            },{
            id: 'b',
            type: 'node',
            c: 'blue',
            t: 'b'
            },{
            type: 'link',
            id: 'a-b',
            id1: 'a',
            id2: 'b'
        }]
        }).then(() => {
            chart.zoom('fit');
        }).then(() => {
            chart.layout();
        })
    })
});
Our basic KeyLines chart running inside Jupyter
Our basic KeyLines chart running inside Jupyter

Step 5: Interop with Python (optional)

We can take this integration one step further and add a Python connector. This lets us pass processed data from a Python cell to your KeyLines JavaScript cell, with the help of an iPython library.

First we serialize some data into KeyLines JSON, and assign that to a global variable on the JS window object from within python. Then in the JavaScript cell we can access the global variable containing the JSON directly.

Cell 1
import json
# create json in python
data = json.dumps({
   'type': 'LinkChart',
   'items': [{
   'type': 'node',
   'id': 'n1',
   'c': 'blue',
   't': 'node 1'
}]})

from IPython.display import Javascript
#runs arbitrary javascript, client-side
Javascript("""
          window.data={};
          """.format(data))

Cell 2
%%javascript
console.log('KeyLines data', data);

Try it for yourself

Are you inspired to enrich Jupyter with graph visualization? You can find more about Jupyter on their website, and request a KeyLines trial over here. Let us know how you get on!

Jupyter, Jupyter Notebook and Project Jupyter © of Project Jupyter.

|

Subscribe to our newsletter

Get occasional data visualization updates, stories and best practice tips by email