Hands-on graph visualization: KeyLines & Neo4j
At Cambridge Intelligence, we build graph visualization technologies that make the world safer. KeyLines is our JavaScript SDK for interactive graph visualization. It’s ideal for hands-on Neo4j developers, offering the same power, scalability and flexibility for which the world’s most popular graph database has become known.
Over the last 7 years, hundreds of developers have used KeyLines to build visualization web applications for Neo4j. As a result, we’ve honed our integration code, documentation and support to make the process as simple as possible.
Build from scratch or use a template
As KeyLines is an SDK, there are limitless ways to customize your application. You have complete control over every aspect — UI, UX, functionality, visual appearance and branding. The most common approach is to use KeyLines’ API to harness functionality like the time bar, combos, SNA and geospatial visualization. For that, more advanced JavaScript developers can follow our tutorial over here.
Another popular option — which we’ll cover in this post — is to use one of our demos to kick-start the process. With this approach, we’ll use KeyLines’ Cypher integration and a one-to-one mapping between Neo4j and the chart, so switching the schema and producing your own visualization is fast and simple. Let’s get started.
A few prerequisites…
To follow this tutorial, you’ll need:
- a KeyLines SDK login (request an account here)
- a Neo4j instance, loaded with some data
- basic knowledge of JavaScript and web applications
The visualization architecture
The KeyLines-Neo4j architecture is simple, but secure and flexible enough to work in any setup:
KeyLines itself is a JavaScript file, deployed to a web server. The KeyLines chart is then embedded as an HTML element somewhere within your application (or as a standalone component) which allows the user to interact with, and explore, the graph.
Graphics rendering is powered by HTML5 Canvas or WebGL — KeyLines will switch between the two depending on the browser — so it performs well even with larger graphs. Also, everything stays inside your corporate firewall so data security shouldn’t be an issue.
Step 1: Download our Neo4j demo
Once you’re in the KeyLines SDK, take a few minutes to look around the site and review the documentation. The ‘Basics’ section of the Documentation tab is the best place to start.
Next, head to the Demos tab. Here you’ll find a gallery of KeyLines apps, ready to download and start customizing:
There’s a few different demos designed for Neo4j integration, but ‘Integrate with Neo4j’ is the most straightforward. It uses Cypher queries and KeyLines’ incremental layout to explore a Neo4j dataset of movies and actors (appropriately starting from The Matrix).
To the right of the demo KeyLines chart we’ve included an information box, containing the Cypher queries being raised, and some UI to run layouts from the KeyLines API.
From the demo page, click ‘Download’.
Step 2: Run the demo locally
The demo will download as a Zip folder. Inside you’ll find the following files:
You don’t need to know what each of these files does, but there are a few important ones:
- assets contains images for different components of the KeyLines chart, like the navigation controls and the chart watermark.
- css (as you’d expect) contains the different CSS files for the rest of your webpage. You can use ours, or write your own.
- images contains the image files for nodes, glyphs, etc.
- neo4j-db.js is the database driver, including Cypher integration and JSON parsing code.
- neo4j.js adds KeyLines functionality, as well as tying some of that functionality to general UI (e.g. run a layout when the user clicks on this button).
To get the demo running locally, open ‘index.htm’ in your preferred browser. You should see something like this:
At this point, the demo is running from our local filesystem. The chart is blank because we haven’t connected it to our database yet.
Step 3: Point the demo at your Neo4j database
In your ‘demo’ folder, find the neo4j-db.js file and add your instance login credentials to the following:
headers: {Authorization: ‘Basic ‘+btoa(‘username:password’)},
Obviously, this approach is only recommended during KeyLines prototyping. When you deploy your app in production, you’ll run Neo4j on a secure web server and only expose certain endpoints to KeyLines.
Using Bolt?
In this example, we’ve assumed you’re using Neo4j’s REST API to send queries back and forth. If you’re using Neo4j’s Bolt protocol, you’ll need to make some adjustments to the KeyLines demo at this stage:
- Set up the JavaScript Bolt library — either in your browser (using the browser version of the Neo4j driver) or on your server (for example by requiring Neo4j-driver in Node)
- Set up the driver — by adding your credentials and creating sessions to run KeyLines’ Cypher queries
- Process the Bolt response into KeyLines JSON — in a single loop you can: a) convert the node IDs, b) do the same for link/edge start and endpoints, c) convert other numeric properties.
More detailed instructions can be found in this blog post.
Step 4: Update the schema
Next you need to map your Neo4j data to the KeyLines schema, and choose the visual model you want to use.
This stage can be as simple or as complex as you like, but our demo uses one-to-one mapping between the chart and database, and follows a typical user workflow (expand and explore). For most developers, a few simple ‘find and replace’ commands should do the trick.
E.g. open neo4j-db.js, find e: item.d.type === ‘movie’ ? 1.7 : 2.5 , which enlarges movie nodes in our demo, and replace movie with whichever node type from your schema you want represented as a larger size.
You’ll also need to adjust the Cypher queries in-line with your own schema. That’s in the queryTemplates object in neo4j-db.js.
Finally, you can also change node and link styles at this stage, for example by finding the ‘dbDemoTheme’ object in neo4j.js and changing the font icons by editing the ‘fi’ property.
Step 5: Run the demo
The final step is to start your database and load KeyLines. If you’re using Node, that’s a simple `npm install` followed by `npm start` in the root folder.
Now navigate to http://localhost:8080 to find your interactive KeyLines — Neo4j demo:
Optional step 6: incorporate advanced functionality
By now, you’ll have a simple demo, running from your database with your own visual styling. It’s a great starting point for you to visually explore and understand your Neo4j data.
But if you want to take your insight a step further, the KeyLines API offers a huge library of advanced graph analysis and visualization functionality. With a few lines of JavaScript code (take a look at our 80+ demos for inspiration) you can incorporate graph layouts, SNA centrality measures, temporal / dynamic graph visualization, geospatial analysis, filtering or our advanced ‘combos’ functionality.
Try it for yourself
This tutorial is just the starting point. KeyLines and Neo4j are a powerful combination, and make it easy for you to build custom, flexible and high-performance graph exploration tools.
Start a trial over here, or contact us for more information.
