We use a lot of Dojo at mSpoke, so it was an easy choice for us to use Dojo Charting to create the plots in our dashboard.  However, it doesn’t yet include some chart types we’d like.  So I built them.  This post covers our custom box and whisker plot.

A box and whisker plot elegantly displays distributional statistics about a set of data.  The box covers the middle 50% of the data, the line in the box shows the median, the whiskers cover the range of points that are not outliers, and the outliers are indicated using markers.

Dojo box and whisker chart

I’ve hosted an interactive version of the chart and the source code.  mSpoke is happy to share this code, and I would be happy to work with Dojo to include it in later releases. [Update: in 2008 mSpoke placed this code into public domain, with no warranty of any kind. I've updated the source code to reflect this status.]

Using the box and whisker plot

Creating a box and whisker plot is very similar to the creation of other Dojo charts.  In addition to including dojo.js, you’ll need to include BoxAndWhisker.js:

<script type="text/javascript" 
        src="mspoke/charting/plot2d/BoxAndWhisker.js"></script>

The javascript to create the plot is simple:

    var chart = new dojox.charting.Chart2D("chart");
    chart.addPlot("default", {type: "BoxAndWhisker", markers: true});

I’ve included two different ways to pass in the data for a series.  The first is to simply list all of the data points; BoxAndWhisker.js will compute the median, middle 50% of points, whiskers and outliers.

    var fill = new dojo.Color([0x00, 0x4f, 0x80, 0.7]);
    var stroke = {color:fill};

    // List all points approach
    chart.addSeries( "Mon",
      [4.4, 6.7, 5.7, 4.6, 4.1, 4.4, 4.3, 4, 3.5, 6.2, 6.5, 0.5],
      {stroke:stroke, fill:fill, center:1, width:0.2});

You must specify the center and width for the box to display properly.  The center indicates where the x-coordinate the box and whisker for the series will be placed and the width indicates the width along the x-axis of the box.  You can specify the range and labels of the axes using chart.addAxis.  View the source of the interactive version for an example.

The other approach is better suited for handling large data sets, when passing in all of the data would make the script run slowly.  In this case, you need to figure out the box and whisker coordinates yourself.

    // Pass in box and whisker coordinates and outliers
    chart.addSeries( "Tue",
      {lwhisker: 1.4, lbox: 2.9, median: 3.35, ubox: 5.1, uwhisker: 7.5,
       outliers: [0.2, 8.9]},
      {stroke:stroke, fill:fill , center:2, width:0.2});

lwhisker and uwhisker are the lower and upper points for the whiskers, lbox and ubox specify the range of the box, and median is the coordinate for the median line in the box.  You can specify the list of markers with the outliers parameter.  Complete source for constructing a box and whisker plot is available in the source of the interactive version.

Creating custom plot types

Building a custom Dojo plot isn’t extremely hard, but it takes some patience to get things just right.  The biggest quirk was that I had indicate in code that the BoxAndWhisker plot type is a part of dojox.charting.  I suspect I may be misunderstanding how to use the Dojo Toolkit correctly.  In order to make the chart visible to Dojo, BoxAndWhisker.js must use dojo.provide at the top of the file:

dojo.provide("dojox.charting.plot2d.BoxAndWhisker");

Following the example in other Dojo plots, I used dojo.declare to declare the plot constructur. As with the call to dojo.provide, I had to declare the plot to be a part of dojox.charting:

	dojo.declare("dojox.charting.plot2d.BoxAndWhisker",
                          dojox.charting.plot2d.Base, {

Otherwise, I was able to develop the chart by following the examples already provided in dojox.charting.plot2d.