260 lines
7.6 KiB
HTML
260 lines
7.6 KiB
HTML
<!doctype>
|
|
<head>
|
|
<link rel="stylesheet" href="vendor/prettify/prettify.css">
|
|
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.0/jquery.min.js"></script>
|
|
<script src="vendor/prettify/prettify.js"></script>
|
|
<link rel="stylesheet" href="style.css">
|
|
</head>
|
|
|
|
<body>
|
|
|
|
<h1>Taking Rickshaw for a Go</h1>
|
|
|
|
<p>
|
|
Rickshaw is a simple framework for drawing charts of time series data
|
|
on a web page, built on top of Mike Bostock's delightful
|
|
<a href="http://mbostock.github.com/d3/">D3 library</a>. These charts
|
|
can be powered by static historical data sets, or living data that
|
|
continuously updates in real time.
|
|
</p>
|
|
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<p>
|
|
Let's start with a simple but complete program that paints a chart:
|
|
</p>
|
|
|
|
<section class="example" id="example_01">
|
|
<header>
|
|
<a href="example_01.html" target="_blank">view</a>
|
|
<h3>Example 01</h3>
|
|
</header>
|
|
<iframe scrolling="no"></iframe>
|
|
<pre class="prettyprint"></pre>
|
|
</section>
|
|
|
|
<p>
|
|
Breaking that down, first we pull in our dependencies and create
|
|
a div to hold our chart. Then in our <code>script</code> we
|
|
call <code>Rickshaw.Graph</code>'s constructor, and pass along an
|
|
element reference to our chart container, some layout instructions,
|
|
and a series of data objects.
|
|
</p>
|
|
|
|
<p>
|
|
The <code>series</code> object has a couple of slots,
|
|
a <code>data</code> 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.
|
|
</p>
|
|
|
|
<h2>Let's Try with Real Data</h2>
|
|
|
|
<p>
|
|
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 <a href="http://2010.census.gov/2010census/data/pop_change.csv">population change data</a> from the
|
|
2010 U.S. Census to power our chart, and see what we find.
|
|
</p>
|
|
|
|
<p>
|
|
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 <a href="transform.pl">script</a> we've written to massage the
|
|
CSV data at the census.gov URL into a JavaScript data structure
|
|
that <code>Rickshaw.Graph</code>'s constructor can take as
|
|
its <code>data</code> argument.
|
|
</p>
|
|
|
|
<br>
|
|
<section class="example" id="example_02">
|
|
<header>
|
|
<a href="example_02.html" target="_blank">view</a>
|
|
<h3>Example 02</h3>
|
|
</header>
|
|
<iframe scrolling="no"></iframe>
|
|
<pre class="prettyprint linenums"></pre>
|
|
</section>
|
|
|
|
<h2>Time on the X-Axis</h2>
|
|
|
|
<p>
|
|
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?
|
|
</p>
|
|
|
|
<p>
|
|
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 <code>x</code> values we can pass our
|
|
graph along to <code>Rickshaw.Graph.Axis.Time</code>'s constructor.
|
|
When the graph's <code>render()</code> function is later called
|
|
Rickshaw examines the <code>x</code> 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.
|
|
</p>
|
|
|
|
<p>
|
|
Our updated <a href="./transform_epoch.pl">transform_epoch.pl</a> uses epoch
|
|
seconds for <code>x</code>. Let's see how we do.
|
|
</p>
|
|
|
|
<br>
|
|
<section class="example" id="example_03">
|
|
<header>
|
|
<a href="example_03.html" target="_blank">view</a>
|
|
<h3>Example 03</h3>
|
|
</header>
|
|
<iframe scrolling="no"></iframe>
|
|
<pre class="prettyprint linenums"></pre>
|
|
</section>
|
|
|
|
|
|
<h2>Y-Axis Too</h2>
|
|
|
|
<p>
|
|
Now let's add the pieces to get a <code>y</code> axis. We need a new
|
|
HTML element to put the <code>y</code> axis in, as well as some
|
|
styling to position the axis absolutely in relation to the chart.
|
|
</p>
|
|
|
|
<p>
|
|
We pass along a reference to our graph to
|
|
<code>Rickshaw.Graph.Axis.Y</code>'s constructor, as well as the
|
|
element we want to draw the axis inside. We also ask
|
|
<code>Rickshaw.Fixtures.Number.formatKMBT</code> to help us format the
|
|
numbers on our <code>y</code> ticks in there.
|
|
</p>
|
|
|
|
<section class="example" id="example_04">
|
|
<header>
|
|
<a href="example_04.html" target="_blank">view</a>
|
|
<h3>Example 04</h3>
|
|
</header>
|
|
<iframe scrolling="no"></iframe>
|
|
<pre class="prettyprint linenums"></pre>
|
|
</section>
|
|
<br>
|
|
|
|
<h2>Breaking Things Down</h2>
|
|
|
|
<p>
|
|
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 <a href="transform_region.pl">transform_region.pl</a>.
|
|
</p>
|
|
|
|
<p>
|
|
Plugging that data into our series parameter leaves us wanting to
|
|
provide colors for each of those individual series. We'll use the
|
|
<code>Rickshaw.Color.Palette</code> plugin to pick our colors. Once
|
|
we've created our palette, calling its <code>color()</code> method
|
|
returns the next color.
|
|
</p>
|
|
|
|
<br>
|
|
<section class="example" id="example_05">
|
|
<header>
|
|
<a href="example_05.html" target="_blank">view</a>
|
|
<h3>Example 05</h3>
|
|
</header>
|
|
<iframe scrolling="no"></iframe>
|
|
<pre class="prettyprint linenums"></pre>
|
|
</section>
|
|
|
|
<h2>What Are We Looking At?</h2>
|
|
|
|
<p>
|
|
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
|
|
<code>Rickshaw.Graph.Legend</code> plugin, which takes a reference to
|
|
our newly added DOM element, and a reference to the graph.
|
|
</p>
|
|
|
|
<br>
|
|
<section class="example" id="example_06">
|
|
<header>
|
|
<a href="example_06.html" target="_blank">view</a>
|
|
<h3>Example 06</h3>
|
|
</header>
|
|
<iframe scrolling="no"></iframe>
|
|
<pre class="prettyprint linenums"></pre>
|
|
</section>
|
|
|
|
<h2>Unstacking</h2>
|
|
|
|
<p>
|
|
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.
|
|
</p>
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<br>
|
|
<section class="example" id="example_07">
|
|
<header>
|
|
<a href="example_07.html" target="_blank">view</a>
|
|
<h3>Example 07</h3>
|
|
</header>
|
|
<iframe scrolling="no"></iframe>
|
|
<pre class="prettyprint"></pre>
|
|
</section>
|
|
|
|
<h2>More Later</h2>
|
|
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<p>
|
|
If you're clamoring for more, you may enjoy a poke around in the
|
|
<a href="../examples/">examples</a> directory.
|
|
</p>
|
|
|
|
<br><br>
|
|
<script>
|
|
var sections = document.querySelectorAll('section.example');
|
|
|
|
var htmlEntities = function(str) {
|
|
return String(str).replace(/&/g, '&').replace(/</g, '<').replace(/>/g, '>').replace(/"/g, '"');
|
|
}
|
|
|
|
Array.prototype.forEach.call(sections, function(s) {
|
|
|
|
var code = s.querySelector('pre');
|
|
var iframe = s.querySelector('iframe');
|
|
var anchor = s.querySelector('a');
|
|
|
|
var exampleURL = s.getAttribute('id') + ".html";
|
|
|
|
iframe.src = exampleURL;
|
|
|
|
$.ajax( {
|
|
url: exampleURL,
|
|
success: function(r) {
|
|
code.innerHTML = htmlEntities(r);
|
|
code.innerHTML = prettyPrintOne(code.innerHTML);
|
|
}
|
|
} );
|
|
|
|
} );
|
|
|
|
</script>
|
|
</body>
|