What’s the JavaScript InfoVis Toolkit?

The JavaScript InfoVis Toolkit provides web standard based tools to create interactive data visualizations for the Web.

What’s new in this version?

This version introduces radical new features, an API redesign and new visualizations. If you don’t want to read the whole article and just want to play with the examples you can go to the demos page.

New Visualizations

With this version of the Toolkit the number of available visualizations has doubled. Some of the new visualizations are the AreaChart, BarChart and PieChart, which were described in more detail in this article. I’ve also added Sunburst and Force-Directed visualizations. I wrote about these visualizations before here and here. I also want to thank Pablo Flouret, who contributed most of the code for the Icicle visualization, also a new addition to the toolkit.

You can play now with these visualizations at the demos page!

Features common to all visualizations

I’ve also enhanced all visualizations with new configuration options that enable new features. These features are:

• Panning and zooming across all visualizations.
• A new event system that enables you to attach events to DOM elements or to native canvas nodes and also add support for touch events, drag and drop, etc.
• Complex animations have the ability to animate any style property of a node, edge or label. There is also support for animating canvas specific properties like shadowBlur, shadowColor, fillStyle, etc.

A new TreeMap visualization

The underlying rendering functions in the TreeMap visualization have changed. While in prior versions of the Toolkit the TreeMap was DOM-based, this new version renders the TreeMap entirely in Canvas. This enables you to add custom nodes of any shape or nature you like (can be images, circles, polygons) and also to take advantage of the new animation engine of the toolkit to add smooth transitions for the drill-down. These new things can be tested at the TreeMap section in the demos page.

API Redesign

The old API was too low level. Before creating any visualization you had to manually create a Canvas widget and pass it as parameter to the visualization class. Also, many other parameters like width and height of the canvas were required. For Background canvases the API had a couple of flaws, and it wasn’t clear how to use it either. Many of these things have been solved with the new API design. The Canvas class became an inner class implicitly created when making a new visualization. Width and height of the canvas are set to the container’s offsetWidth and offsetHeight if they’re not provided, and background canvases are easier to attach to the visualization.
Most of all, there is now a single global object in the library: $jit. This declares the namespace for the library and makes sure you won’t have conflicts with any other JavaScript library.

A new Website

Last but not least, I worked on a website redesign, taking advantage of the new HTML5/CSS3 features supported by major browsers. There’s also a detailed documentation page to get you started.

It’s alpha

Finally I’d like to say that this is an alpha version. There are lots of known bugs and I’m counting on you to report bugs, send fixes, and collaborate in any aspect of the toolkit.

Thanks

To Pablo Flouret for contributing code to the toolkit, and to my wife, Luz Caballero for making me happy.

Now go get the Toolkit!

I’ll start with the new features:

SpaceTree: SwitchAlignment

I added some new global configuration properties to the SpaceTree: align and indent.

Align sets the alignment of the tree to center, left and right:

The indent parameter sets an offset between a parent and its children when the alignment is left or right. You can also use the switchAlignment method for changing the alignment of the tree with an animation.

SpaceTree: Multiple nodes in path

I added two new methods to the SpaceTree: addNodeInPath and clearNodesInPath.
These two methods allow you to add a node to the “selected-nodes” path. When a node belongs to the “selected-nodes” path it remains always visible (as in always expanded).

I made this small video to show the feature:

SpaceTree: MultiTree

I added a SpaceTree configuration property called multitree.
If multitree=true, the visualization will search for the $orn data property in each node and display the subtrees according to their orientation.

In this example I set multitree=true and set $orn=’left’ for some nodes and $orn=’right’ for others. This way I create a partition of the tree:

I also use the setRoot method to set the clicked node as root for the visualization. This way the clicked node is centered and a centrifugal view from that node is drawn.

Bug Fixes

I’ve been fixing a couple of bugs also, most of them have to do with Treemaps:

• Refreshing treemaps keeps old tooltips over (Thanks Ariel Kempf)
• Treemap: change box filling order from towards top right, to towards bottom right (Thanks Tim Bunce)
• Treemap: patch to fix gaps between boxes (Thanks Tim Bunce)
• Treemap: avoid creating boxes too small to see (Thanks Tim Bunce)
• Add a boolean to the fx.clearLabels method for clearing all labels regardless of any condition.

I also want to thank Guido Schmidt for his interest in the library and work on the GWT JIT component.

There’s also been some JIT development for Grails done by Bertrand Goetzmann.

Anyway, things are looking good!

What’s the JavaScript InfoVis Toolkit?

The JavaScript InfoVis Toolkit provides tools for creating Interactive Data Visualizations for the Web.

What’s new in this version?

• A new project page where you can access all things related to this library: documentation, demos, tutorials, this blog, etc.
• A complete API documentation generated with Natural Docs, with some Narrative Documentation and Syntax Highlighted Code Examples.
• A Demos page where you can find some interactive library examples and you can browse through the examples code.
• The JavaScript InfoVis Toolkit is now hosted at GitHub, so you can fork it and do whatever you like with it. You can also report bugs with the new issue tracker.

Code-Related

• The library has been split into modules for code reuse.
• All visualizations are packaged in the same file. You can create multiple instances of any visualization. Moreover, you can combine and compose visualizations. If you want to know more take a look at the Advanced Demos.
• This Toolkit is library agnostic. This means that you can combine this toolkit with your favorite DOM/Events/Ajax framework such as Prototype, MooTools, ExtJS, YUI, JQuery, etc.
• You can extend this library in many ways by adding or overriding class methods. The JavaScript InfoVis Toolkit has a robust (and private) class system, heavily inspired by MooTools’, that allows you to implement new methods in the same class without having to define any new Class extension. By creating mutable classes you can add new custom Node and Edge rendering functions pretty easily.
• Custom visualizations are created by adding or changing Node/Edge colors, shapes, rendering functions, etc. You can also implement many controller methods that are triggered at different stages of the animation, like onBefore/AfterPlotLine, onBefore/AfterCompute, onBefore/AfterPlotNode, request, etc.
  You can also add new Animation transitions like Elastic or Back with easeIn/Out transitions.
  If you want to know more about these features please take a look at the Demos code.

As you can see, this new version has been built with four concepts/goals in mind: Modularity, Customization, Composition and Extensibility. I already explained some of these things in the previous post.

Hope you enjoy it.

• A more stable and usable Canvas class.
• Finishing last features included in the Spacetree, Treemap and RGraph InfoVis papers.

I’m quite happy with this version of the library, since it implements all lasting features in my TODO list.
This doesn’t mean much for the library, since I’m still having lots of ideas for next releases, but at least I finished something I put up to and that makes me happy .

Canvas

I implemented a new Canvas class, focusing on performance and usability.

The Canvas class is more like a Canvas Widget, since it creates a cross-browser canvas tag and a label div container, wrapped in a main div element.
This way, labels are relative to the canvas element and not absolute positioned, like they were on previous versions. I’d like to thank the people in this thread for providing nice ideas for implementing the Canvas class.

This canvas class makes also the Spacetree visualization cross browser, working perfectly well in IE6+.

Prior to version 1.0.8a, you had to put a canvas tag and a div label container in your html to create a new visualization. From version 1.0.8a this is no longer needed: you just have to include a visualization div container, like this:

<div id="infovis"></div>

A simple canvas instantiation could be something like this:

      //Create a new canvas instance.
      var canvas = new Canvas('mycanvas', {
         //Where to inject canvas. Any HTML container will do.
         'injectInto':'infovis',
         //Set width and height, default's to 200.
         'width': 900,
         'height': 500,
        //Set canvas styles.
        'styles': {
            'fillStyle': '#ccb',
            'strokeStyle': '#ccb'
        }
      });

The first parameter in the canvas constructor is the id of the canvas widget.
This id will be the main wrapper div id, and it will serve as prefix for the ids of the other DOM elements created.
The second parameter is a canvas configuration object. Some of the object’s properties are:

• injectInto: The id of the div where you want to inject the canvas widget
• width, height: Width and height of the canvas widget. Default’s to 200
• styles: an object containing specific canvas styles. If you want to know more about canvas styles you can read this article.

The html generated by this call will be appended in the div container (#infovis) previously defined:

<div id="infovis">
  <div id="mycanvas" style="position:relative;">
    <canvas id="mycanvas-canvas" width=900 height=500
    style="position:absolute; top:0; left:0; width:900px; height:500px;" />
    <div id="mycanvas-label"
    style="overflow:visible; position:absolute; top:0; left:0; width:900px; height:0px">
    </div>
  </div>
</div>

Notice how the Canvas id is used as the id of the main div container and also as prefix for the actual canvas element and the div label container element.
If we were using the Spacetree in IE, we could use an extra backgroundColor parameter as IE hack, since excanvas does not support clipping paths, which are used by the Spacetree visualization:

      //Create a new canvas instance.
      var canvas = new Canvas('mycanvas', {
         //Where to inject canvas. Any HTML container will do.
         'injectInto':'infovis',
         //Set width and height, default's to 200.
         'width': 900,
         'height': 500,
         //Set a background color in case the browser
         //does not support clearing a specific area.
        'backgroundColor': '#222',
        //Set canvas styles.
        'styles': {
            'fillStyle': '#ccb',
            'strokeStyle': '#ccb'
        }
      });

We can define also a background Canvas.
Take for example the RGraph example, in which we plot concentric circles as background for the visualization.
Prior to version 1.0.8a, the background was rendered at each frame, since at each frame of an animation the canvas is fully cleared to plot the graph’s next position. This wasn’t very good for performance.

Defining a background canvas was the sanest choice. That way the background is rendered only once:

  //Create a new canvas instance.
  var canvas = new Canvas('mycanvas', {
    //Where to inject the canvas. Any div container will do.
    'injectInto':'infovis',
    //width and height for canvas. Default's to 200.
    'width': 900,
    'height':500,
    //Canvas styles
    'styles': {
        'fillStyle': '#ccddee',
        'strokeStyle': '#772277'
    },
    //Add a background canvas for plotting
    //concentric circles.
    'backgroundCanvas': {
        //Add Canvas styles for the bck canvas.
      'styles': {
            'fillStyle': '#444',
            'strokeStyle': '#444'
        },
        //Add the initialization and plotting functions.
        'impl': {
            'init': $empty,
            'plot': function(canvas, ctx) {
                var times = 6, d = Config.levelDistance;
                var pi2 = Math.PI*2;
                for(var i=1; i<=times; i++) {
                    ctx.beginPath();
                    ctx.arc(0, 0, i * d, 0, pi2, true);
                    ctx.stroke();
                    ctx.closePath();
                }
            }
        }
    }
 });

The background canvas created will have mycanvas-bkcanvas as id.
For more information about the canvas class you can check its object reference, the examples provided with the library and the updated quick tutorials which you can find in the documentation.

Treemap

I implemented the Strip layout for the Treemap, in addition to the Squarified and Slice and Dice layout algorithms provided in previous versions of the library.
I updated the treemap example to impement different tiling algorithms. Use the dropdown box at the left of the screen to change the current layout.

Why another tiling algorithm?
Well, as the Wikipedia explains:
To create a treemap, one must define a tiling algorithm, that is, a way to divide a rectangle into sub-rectangles of specified areas. Ideally, a treemap algorithm would create rectangles of aspect ratio close to one; would preserve some sense of the ordering of input data; and would change only slowly when the underlying data changes slowly. Unfortunately, these properties have an inverse relationship.

The Strip tiling algorithm provides a good compromise between order, stability and aspect ratio values.
More precisely, the three techniques implemented in the JIT can be classified as follows:

• Slice and Dice: Ordered, very high aspect ratios, stable
• Squarified: Unordered, lowest aspect ratios, medium stability
• Strip: Ordered, medium aspect ratios, medium stability

So the Strip algorithm is a good complement to the tiling algorithms provided.

Spacetree

I implemented two new layouts for the Spacetree, bottom and right layouts.
You can change the Spacetree layouts by using the dropdown box at the left of the visualization.

The bottom layout could be pretty useful for making family trees or things like that .
Anyway, another good thing of the Spacetree is that it works for IE6+ now (thanks to the new Canvas implementation).
Some cleanup regarding the plotting algorithms and how labels were created was done, please check the ST quick tutorial to understand exactly what changed.

RGraph

I implemented the second animation constraint mentioned in the RGraph paper: child ordering.
This constraint decreases edge crossing during animations, making animations more intuitive and graspable by the viewer.
The child ordering constraint consists in mantaining child ordering for the parent of the clicked node, that way we can decrease the edge crossing cases during animations:

I didn't make a new example for this, but you should see the difference when comparing it with the examples packaged in previous versions of the library.

Hypertree

I did some Cleanup of the Hypertree code, and stripped off the Mouse class and the prepareCanvasEvents method.
Those kind of things can be easily implemented with DOM/AJAX frameworks like Mootools or JQuery.
The hypertree example packaged with the library shows a possible workaround for prepareCanvasEvents:

  //optional: set an "onclick" event handler on the canvas tag to animate the tree.
  var mycanvas = $('mycanvas');
  var size = canvas.getSize();
  mycanvas.addEvent('click', function(e) {
    var pos = mycanvas.getPosition();
    var s = Math.min(size.width, size.height) / 2;
    ht.move({
      'x':  (e.page.x - pos.x - size.width  / 2) / s,
      'y':  (e.page.y - pos.y - size.height / 2) / s
    });
  });

Anyway, that's all for now. Please feel free to file bugs if you spot one.
Remember also that the main project page has links to documentation, google groups, browser support, updated examples and some other things

• A complete refactoring of the Spacetree. That code was not clear. I also binded the ST to the Animation object used by the Hypertree and RGraph. This allows it to have easeIn and easeOut transitions. I also updated the documentation for this class.
  Main functionality is now packaged under the Tree Class, making a good distinction between generic code (say Tree.Util for example) and more specific code (like the Tree.Geometry object, or Tree.Label).
  Here’s the old example of an “infinite” spacetree, done with the “new code”.
• Hypertree and RGraphs can now handle weighted nodes and edges in trees and graphs. The same goes for the Spacetree, although I have not tested that yet.

  Weighted nodes:
  This goes only for the RGraph and the Hypertree, since I don’t see a clear representation of weighted nodes in the Spacetree, and the Treemap already represents weight either with size or color.
  Weighted nodes are enabled when setting Config.allowVariableNodeDiameters = true.
  Remember what a dataset is? A dataset is a reference to the property data of a JSON node representation. There you can store data by appending { key:’someKey’, value:’someValue’} objects to the data array property.
  The value of the first object of the data property will be taken in account to calculate the nodes diameters. You will also want to specify two properties of the config object, the nodeRangeDiameters property:

  		//Property: nodeRangeDiameters
  		//Diameters range. For variable node weights.
  		nodeRangeDiameters: {
  			min: 10,
  			max: 35
  		},
  

  Which specifies the specific range of your nodes diameters. Nodes will range from 10px to 35px as default. The other property is the nodeRangeValues:

  		//Property: nodeRangeValues
  		// The interval of the values of the first object of your dataSet.
  		// A superset of the values can also be specified.
  		nodeRangeValues: {
  			min: 1,
  			max: 35
  		},
  

  You’ll need to specify range values for your first dataset object value. This is all the information we need to know in order to plot a RGraph or Hypertree with weighted nodes. Here’s an example of a K6 Hypergraph with variable node diameters (and weighted edges).

  A note on usability
  There’s an extra property for the Hypertree Config object called Config.transformNodes. When applying a moebius transformation of the tree (that is, when the tree moves), tree nodes and edges change their proportion. This is not a good feature if you’re planning to add weighted nodes in your Hypertree, since they will be deformed and thus the user won’t be able to tell which node is bigger than which. You can set this property to false when using weighted nodes on your visualization.

  Weighted edges
  Two new methods have been included in the controller object, these are onBeforePlotLine(adj); and onAfterPlotLine(adj);. Both receive an adjacency object, which has the following structure:

  var adj = {
  	nodeFrom: ""/* A node connected with this adjacence */,
  	nodeTo: ""/* Other node connected with this adjacence */,
  	data: { //An object storing your custom information.
  		weight: w
  	}
  };

  Use the two controller methods to change the canvas lineWidth property or the stroke color (more information on that here). For example,

  /* some code... */
  
   var rgraph= new RGraph(canvas,  {
    	//Use onBeforePlotLine and onAfterPlotLine controller
    	//methods to adjust your canvas lineWidth
    	//parameter in order to plot weighted edges on
    	//your graph. You can also change the color of the lines.
    	onBeforePlotLine: function(adj) {
    			lineW = canvas.getContext().lineWidth;
    			canvas.getContext().lineWidth = adj.data.weight;
    	},
  
    	onAfterPlotLine: function(adj) {
    			canvas.getContext().lineWidth = lineW;
    	},
  
  /* some other code*/
  

  Ok, but how do I store edge weights?
  The JSON Graph structure has been extended to the following form (notice that the old Graph structure is still accepted).

  var json = [
  {
  	"id": "aUniqueIdentifier",
  	"name": "usually a nodes name",
  	"data": [
  	    {key:"some key",       value: "some value"},
  		{key:"some other key", value: "some other value"}
  	],
  	"adjacencies": [
  	{
  		nodeTo:"aNodeId",
  		data: {} //put whatever you want here
  	}
  	//more objects like these...
  	]
  } /* ... more nodes here ... */ ];
  

  JSON Tree structures
  For JSON Trees is simpler. If you have a Node A and B is a child of A, then store in Bs dataset a property concerning the weight of the edge A-B. These nodes will be stored in the adj object onBeforePlotLine and onAfterPlotLine. You can access them by doing adj.nodeFrom and adj.nodeTo.

  Here’s an example of a K6 RGraph with weighted nodes and edges.

• The last example also shows a new feature for the RGraph, polar interpolation. You will notice that node transitions are different from previous examples. You can change the interpolation by setting Config.interpolation to ‘polar’ or ‘linear’. I’ll make a more detailed explanation for polar interpolation in some other post. If you want to know more about the cool features of the paper inspiring the RGraph, you can see this post.
• API Changes
  These features introduced an api change that has already been updated in all tutorials, although I have not checked for errors yet (will do today and/or tomorrow). You should not set the controller property from the ST, RGraph, Treemaps and Hypertree instances. That is, you can’t do:

  var st = new ST(canvas);
  st.controller = ; //the controller object
  

  Instead, you should do:

  var st = new ST(canvas, controller);
  

• I updated all examples packaged with the library, also adding the two K6 examples showed above. Code that depends on the Mootools library (that is, the example files and the Treemap visualization) has been updated to the final 1.2 version of the Mootools library. This library is shipped as an extra with the JIT.

Special thanks to Rene Becker for pointing bugs and Daniel Herrero for suggesting cool performance improvements.
Remember that you can post any question, suggestion or comment on the JIT google group.

Get the library already!
Bye!

The graph structure

The JSON graph structure is an array of nodes, each having as properties:

• id a unique identifier for the node.
• name a node’s name.
• data The data property contains a dataset. That is, an array of key-value objects defined by the user. Roughly speaking, this is where you can put some extra information about your node. You’ll be able to access this information at different stages of the computation of the JIT visualizations by using a controller.
• adjacencies An array of strings each representing a nodes id.

For example,

var json = [
{
	"id": "aUniqueIdentifier",
	"name": "usually a nodes name",
	"data": [
	    {key:"some key",       value: "some value"},
		{key:"some other key", value: "some other value"}
	],
	"adjacencies": ["anotherUniqueIdentifier", "yetAnotherUniqueIdentifier" /* ... */]
} /* ... more nodes here ... */ ];

I did a small example of a K6 rendered with a RGraph. The JSON graph structure used for this example is:

var json= [
    {"id":"node0",
     "name":"node0 name",
     "data":[
        {"key":"some key",
         "value":"some value"},
        {"key":"some other key",
         "value":"some other value"}],
     "adjacencies":["node1","node2","node3","node4","node5"]},
    {"id":"node1",
     "name":"node1 name",
     "data":[
        {"key":"some key",
         "value":"some value"},
        {"key":"some other key",
         "value":"some other value"}],
     "adjacencies":["node0","node2","node3","node4","node5"]},
    {"id":"node2",
     "name":"node2 name",
     "data":[
        {"key":"some key",
         "value":"some value"},
        {"key":"some other key",
         "value":"some other value"}],
     "adjacencies":["node0","node1","node3","node4","node5"]},
    {"id":"node3",
     "name":"node3 name",
     "data":[
        {"key":"some key",
         "value":"some value"},
        {"key":"some other key",
         "value":"some other value"}],
     "adjacencies":["node0","node1","node2","node4","node5"]},
    {"id":"node4",
     "name":"node4 name",
     "data":[
        {"key":"some key",
         "value":"some value"},
        {"key":"some other key",
         "value":"some other value"}],
     "adjacencies":["node0","node1","node2","node3","node5"]},
    {"id":"node5",
     "name":"node5 name",
     "data":[
        {"key":"some key",
         "value":"some value"},
        {"key":"some other key",
         "value":"some other value"}],
     "adjacencies":["node0","node1","node2","node3","node4"]}];

You can post any question at the google group for this project.
Enjoy!