Taking Rickshaw for a Go

Rickshaw is a simple framework for drawing charts of time series data on a web page, built on top of Mike Bostock's delightful D3 library. These charts can be powered by static historical data sets, or living data that continuously updates in real time.

Rickshaw builds on top of D3 technically, and spiritually too. Rickshaw makes every effort to provide help for common problems without obscuring anything underneath it. If you need to reach down to D3 or the SVG layers below, go right ahead -- it's all there waiting.

Let's start with a simple but complete program that paints a chart:

Breaking that down, first we pull in our dependencies and create a div to hold our chart. Then in our script we call Rickshaw.Graph's constructor, and pass along an element reference to our chart container, some layout instructions, and a series of data objects.

The series object has a couple of slots, a data array of coordinate objects, and a color to draw them with. Finally, we call the render() method on our just instantiated graph object, which creates paints our chart on the screen.

Let's Try with Real Data

Our previous work allowed us to paint a chart of made up values with minimal scaffolding. That was fun, but it doesn't tell us anything interesting about data. Let's use population change data from the 2010 U.S. Census to power our chart, and see what we find.

We'll begin by drawing a line representing the United States population with a point for each decade from 1910 to 2010. We'll use a short script we've written to massage the CSV data at the census.gov URL into a JavaScript data structure that Rickshaw.Graph's constructor can take as its data argument.

Time on the X-Axis

A trained eye can already see some points of interest there. For instance, ending about a quarter way into the graph there is a short period where the growth rate flattens out significantly. What happened then?

First we have to answer the question of when the flattening happened. Putting a label on our x axis should help. Rickshaw gives us a helper for time based axes. After we modify our data transformation script to use epoch seconds for the x values we can pass our graph along to Rickshaw.Graph.Axis.Time's constructor. When the graph's render() function is later called Rickshaw examines the x domain and determines the time unit being used, and labels the graph accordingly. The styling we included lines up the labels nicely across the bottom of our graph.

Our updated transform_epoch.pl uses epoch seconds for x. Let's see how we do.

Y-Axis Too

Now let's add the pieces to get a y axis. We need a new HTML element to put the y axis in, as well as some styling to position the axis absolutely in relation to the chart.

We pass along a reference to our graph to Rickshaw.Graph.Axis.Y's constructor, as well as the element we want to draw the axis inside. We also ask Rickshaw.Fixtures.Number.formatKMBT to help us format the numbers on our y ticks in there.

Breaking Things Down

The Great Depression left a mark. We should break that data down by region. Some simple changes to our data transformation gives us the regional data for our series. Here's transform_region.pl.

Plugging that data into our series parameter leaves us wanting to provide colors for each of those individual series. We'll use the Rickshaw.Color.Palette plugin to pick our colors. Once we've created our palette, calling its color() method returns the next color.

What Are We Looking At?

We need a legend! Following a familiar pattern, we add a container div for the legend and style it. Then we call the constructor for the Rickshaw.Graph.Legend plugin, which takes a reference to our newly added DOM element, and a reference to the graph.

Unstacking

It's clear that the South is growing quickly, but instead of painting this chart as a stacked graph it would be nice to see how these growth patterns line up against each other. We set the renderer in a callback, and then ask the graph to update.

In addition to setting the default renderer for the graph, we've added a little JavaScript to observe clicks between our stack/line toggle whose job is to update the type of renderer we're using and render the graph appropriately.

More Later

We're just getting started, but that's all for today. Next time we'll get into stacked bars, and different line interpolations, and smoothing, and zooming.

If you're clamoring for more, you may enjoy a poke around in the examples directory.