1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
|
<!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>
|
