Rickshaw from rCharts

Taking Rickshaw for a Go

This is a near exact replica of the Rickshaw getting started tutorial built using the R packages slidify and rCharts. All credit and attribution should be directed to the original authors. See the copyright at the end of this page.

rCharts gives us the power of Rickshaw from R. 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 Rickshaw chart from R. rCharts will handle all the js package dependencies and add them to our HTML file, so the R user will not need to worry about these. Instead of the <div> and <script> that we see in the original tutorial, we will build this chart all with the R code below. You should notice a lot of similarity between the R code and the original javascript/HTML code.

Example 01

#if you have not installed slidify, slidifyLibraries, or rCharts
#require(devtools)
#install_github('slidify', 'ramnathv', ref = 'dev')
#install_github('rCharts', 'ramnathv')
#install_github('slidifyLibraries', 'ramnathv', ref = 'dev') # optional
require( rCharts )

options(RCHART_TEMPLATE = 'Rickshaw.html')

#specify the data
data = data.frame(
  c( 0, 1, 2, 3 ),
  c( 40, 49, 17, 42 ),
  stringsAsFactors = FALSE
)
colnames(data) <- c("x","y")
#build the plot
r1 <- Rickshaw$new()
r1$layer(
  y ~ x,
  data = data,
  type = "area",
  colors= "steelblue",
  height = 240,
  width = 540
)
#turn off all the nice built in features
#to match the sparse first example
r1$set(
  hoverDetail = FALSE,
  xAxis = FALSE,
  yAxis = FALSE,
  shelving = FALSE,
  legend = FALSE,
  slider = FALSE,
  highlight = FALSE
)
#r1

Breaking that down, we define our data. Then we call the Rickshaw$new() constructor, and in the layer() method pass some layout instructions and our data.

The layer() method allows a R formula y~x common to base and lattice graphics or a more traditional x=, y = format to specify the x and y components of our data. Within layer(), we also pass the name of our data source data = data, the type of graph type = 'area', and in this case manually specify a color color = 'steelblue'. rCharts by default will turn on all the very nice features of Rickshaw, such as legend, hoverDetail, xAxis, yAxis, shelving, legend, and slider. We will use set() to turn all these to FALSE for this introductory spartan example.

Finally, we call the r1 method on our just instantiated graph object, which creates an HTML file to draw our graph. Other ways to see the generated code are r1$html() to show the HTML code specific to the graph, r1$print()which adds the <div> tag to the HTML, r2$save("filename.html") to save our graph as an HTML file, and a very nice r1$publish() which in one line of code will send the HTML and all the dependencies to Gist to share with the world.

Let's Try with Real Data

To keep the code focused on the charts and not the data, we will use .csv files as our data source for the rest of the examples. To see this tutorial with the data specified in R, go to this version.

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 real data. Let's use population change data from the 2010 U.S. Census to power our chart, and see what we find. This dataset has moved now, and I have yet to find its new location, so we will just manually enter the data provided in the original Rickshaw tutorial.

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 the data created by the Rickshaw team's short script to massage the CSV data at the census.gov URL into a JavaScript data structure. We'll convert this JavaScript data structure into a more familiar R data.frame.

Example 02

#specify the data
data <- read.csv("data/data2.csv", stringsAsFactors = FALSE)
#build the plot
r2 <- Rickshaw$new()
r2$layer(
  y ~ x,
  data = data,
  type = "area",
  colors= "steelblue",
  height = 240,
  width = 540
)
#turn off all the nice built in features
#to match the sparse second example
r2$set(
  hoverDetail = FALSE,
  xAxis = FALSE,
  yAxis = FALSE,
  shelving = FALSE,
  legend = FALSE,
  slider = FALSE,
  highlight = FALSE
)
#r2

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. rCharts makes this incredibly easy. We will just remove the xAxis = FALSE, since a time-based x axis is turned on by default. We had turned it off in the previous two examples to match the original tutorial. 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.

We use the R as.POSIXct function to get dates as epoch seconds for x. Let's see how we accomplish this.

Example 03

#specify the data
data <- read.csv("data/data3.csv", stringsAsFactors = FALSE)
#build the plot
r3 <- Rickshaw$new()
r3$layer(
  y ~ x,
  data = data,
  type = "area",
  colors= "steelblue",
  height = 240,
  width = 540
)
#turn off all the nice built in features except xAxis
r3$set(
  hoverDetail = FALSE,
  yAxis = FALSE,
  shelving = FALSE,
  legend = FALSE,
  slider = FALSE,
  highlight = FALSE
)
#r3

Y-Axis Too

Now let's add the pieces to get a y axis. Like the x axis, rCharts by default draws a y axis, so we will just remove the yAxis = FALSE from the set() function. The default y axis will ask Rickshaw.Fixtures.Number.formatKMBT to help us format the numbers on our y ticks.

Example 04

#already have the data from previous chunk

#build the plot
#since we are just turning on the yAxis we can use r3 from above
r4 <- r3
#turn on yAxis with TRUE since we set to FALSE earlier
r4$set(
  yAxis = TRUE
)
#r4

Breaking Things Down

The Great Depression left a mark. We should break that data down by region. Some simple changes by the Rickshaw's team to the script transform_region.pl provided the regional data for this series.

Plugging that data into a data.frame now with three columns (name, x, and y) 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. Fortunately, rCharts handles all of this for us. Rickshaw offers some nice color palettes (classic9, colorwheel, cool, munin, spectrum14, spectrum2000, spectrum2001) which can be accessed in rCharts with the set() method, so something like r5$set( scheme = "cool" ). colorwheel is the default.

Example 05

data <- read.csv("data/data5.csv", stringsAsFactors = FALSE)
r5 <- Rickshaw$new()
r5$layer ( 
  y ~ x,
  data = data,
  groups = "name",
  height = 240,
  width = 540
)
#turn off features not used in the example
r5$set(
  hoverDetail = FALSE,
  shelving = FALSE,
  legend = FALSE,
  slider = FALSE,
  highlight = FALSE
)
#r5

What Are We Looking At?

We need a legend! Following a familiar pattern, we will just remove the legend = FALSE in our previous examples' set() method. Rickshaw will 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.

Example 06

#use data from previous example

#we can save some time by reusing our chart from Example 5
r6 <- r5
#now turn on the legend
r6$set(
  legend = TRUE
)
#r6

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 using the rCharts HTML for the chart, with slidify we can add 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.

For one final improvement we will also remove the set( ... = FALSE ) to show all the nice default functionality that rCharts implementation of Rickshaw provides. Make sure to check out the tooltip details on hover and the interactive legend. Amazing what we can do with 3 lines of R.

Example 07

#use data from previous example

r7 <- Rickshaw$new()
r7$layer ( 
  y ~ x,
  data = data,
  groups = "name",
  type = "line",
  height = 240,
  width = 540
)
#r7

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 which we will also reproduce with rCharts.

Thanks to:

Ramnath Vaidyanathan for his incredible slidify, rCharts, and more specifically help with this post
Shutterstock for this very nice Rickshaw charting library.