Merge pull request #125 from jllodra/master
[dygraphs.git] / docs / index.html
CommitLineData
15c966e0 1<!DOCTYPE html>
078d1d29
DV
2<html>
3 <head>
10494b48 4 <meta http-equiv="X-UA-Compatible" content="IE=EmulateIE7; IE=EmulateIE9">
89055383
DV
5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
6
fe57a69b 7 <title>dygraphs JavaScript Visualization Library</title>
078d1d29 8 <!--[if IE]>
15c966e0 9 <script type="text/javascript" src="excanvas.js"></script>
078d1d29 10 <![endif]-->
9f006dbf 11 <script type="text/javascript" src="dygraph-combined.js"></script>
15c966e0 12 <link rel="stylesheet" href="style.css">
41deeafa
DV
13
14 <!-- Google Analytics -->
15 <script type="text/javascript">
16 var _gaq = _gaq || [];
17 _gaq.push(['_setAccount', 'UA-769809-2']);
18 _gaq.push(['_trackPageview']);
19 (function() {
20 var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
21 ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
22 var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
23 })();
24 </script>
078d1d29 25 </head>
15c966e0 26 <body>
639fd40c
DV
27 <a href="http://github.com/danvk/dygraphs"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://a248.e.akamai.net/assets.github.com/img/71eeaab9d563c2b3c590319b398dd35683265e85/687474703a2f2f73332e616d617a6f6e6177732e636f6d2f6769746875622f726962626f6e732f666f726b6d655f72696768745f677261795f3664366436642e706e67" alt="Fork me on GitHub"></a>
28
15c966e0
AK
29 <div id="nav">
30 <h2>Documentation</h2>
31 <ul>
68f9bed3
AK
32 <li><a href="#demo">Demo</a></li>
33 <li><a href="#usage">Usage</a></li>
34 <li><a href="#ie">IE Compatibility</a></li>
35 <li><a href="#gviz">GViz Data</a></li>
36 <li><a href="#baseball">Baseball chart</a></li>
37 <li><a href="#stock">Stock chart</a></li>
71ac4733 38 <li><a href="#gwt">GWT Compatibility</a></li>
68f9bed3 39 <li><a href="#policy">Data Policy</a></li>
afdcaac6
DV
40 <li><a href="options.html">Options Reference</a></li>
41 <li><a href="jsdoc/symbols/Dygraph.html">JSDoc Reference</a></li>
2b2a2f1c
DV
42 <li><a href="data.html">Data Formats</a></li>
43 <li><a href="annotations.html">Annotations</a></li>
44 </ul>
45
15c966e0
AK
46 <h2>Project</h2>
47 <ul>
80d143b3 48 <li><a href="http://blog.dygraphs.com/">Blog</a></li>
68f9bed3
AK
49 <li><a href="http://github.com/danvk/dygraphs">Source</a></li>
50 <li><a href="http://code.google.com/p/dygraphs/issues/">Issues</a></li>
51 <li><a href="http://code.google.com/p/dygraphs/issues/entry">Report Bug</a></li>
cd12bba0 52 <li><a href="changes.html">Contribute a change</a></li>
a843ade7 53 <li><a href="mailto:dygraphs-users [at] googlegroups.com">Contact</a></li>
15c966e0 54 </ul>
68f9bed3 55
ab80172e 56 <h2>Demos/Usage</h2>
15c966e0 57 <ul>
ab80172e
DV
58 <li><a href="#gallery">Usage Gallery</a></li>
59 <hr/>
2b2a2f1c 60 <li><a href="tests/">(browse demos)</a></li>
68f9bed3
AK
61 <li><a href="tests/demo.html">Basic Demo</a></li>
62 <li><a href="tests/gviz.html">GViz Demo</a></li>
63 <li><a href="tests/plotter.html">Equation Plotter</a></li>
64 <li><a href="tests/perf.html">Performance Test</a></li>
2b2a2f1c
DV
65 <li><a href="tests/annotation.html">Annotations</a></li>
66 <li><a href="tests/annotation-gviz.html">Annotations (GViz)</a></li>
116bd142 67 <li><a href="tests/fillGraph.html">Filled Chart</a></li>
68f9bed3 68 <li><a href="tests/perf.html">Fractions</a></li>
bf5b5f4d 69 <li><a href="tests/visibility.html">Visibility</a></li>
68f9bed3
AK
70 <li><a href="tests/label-div.html">Labels in a DIV</a></li>
71 <li><a href="tests/numeric-axis.html">Numeric Axis</a></li>
72 <li><a href="tests/draw-points.html">Dotted Points</a></li>
73 <li><a href="tests/native-format.html">Native Format</a></li>
74 <li><a href="tests/grid_dot.html">Crazy Styles</a></li>
75 <li><a href="tests/spacing.html">Tick spacing</a></li>
76 <li><a href="tests/callback.html">Callbacks</a></li>
77 <li><a href="tests/crosshair.html">Crosshairs</a></li>
78 <li><a href="tests/hourly.html">Hourly/Minutely data</a></li>
79 <li><a href="tests/isolated-points.html">Isolated Points</a></li>
80 <li><a href="tests/missing-data.html">Missing Data</a></li>
81 <li><a href="tests/border.html">Bordered chart</a></li>
82 <li><a href="tests/custom-bars.html">Custom Bars</a></li>
83 <li><a href="tests/customLabel.html">Custom Label Styles</a></li>
84 <li><a href="tests/dygraph.html">Minimal Example</a></li>
85 <li><a href="tests/negative.html">Negative Numbers</a></li>
86 <li><a href="tests/noise.html">Noisy Data</a></li>
87 <li><a href="tests/two-series.html">Multiple Series</a></li>
a7ef12f5 88 <li><a href="tests/highlighted-region.html">Custom Underlay / background</a></li>
6b837a40 89 <li><a href="tests/zoom.html">Tests for zoom operations</a></li>
60adad33 90 <li><a href="tests/logscale.html">Log scale tests</a></li>
15c966e0
AK
91 </ul>
92 </div>
fe57a69b 93
15c966e0
AK
94 <div id="content">
95 <h1>dygraphs JavaScript Visualization Library</h1>
68f9bed3 96
15c966e0 97 <p><a href="http://github.com/danvk/dygraphs">http://github.com/danvk/dygraphs</a></p>
ab80172e 98 <p>See <a href="http://blog.dygraphs.com/">blog</a>, <a href="http://groups.google.com/group/dygraphs-users">mailing list</a>, <a href="http://github.com/danvk/dygraphs/downloads/">downloads</a>, <a href="tests/">demos</a> and <a href="http://code.google.com/p/dygraphs/issues/">open issues</a></p>
68f9bed3 99
15c966e0 100 <p>dygraphs is an open source JavaScript library that produces produces interactive, zoomable charts of time series. It is designed to display dense data sets and enable users to explore and interpret them.</p>
68f9bed3 101
15c966e0 102 <h3 id="demo">A demo is worth a thousand words:</h3>
68f9bed3 103
c65f2303 104 <p style="font-size:0.8em">(Mouse over to highlight individual values. Click and drag to zoom. Double-click to zoom back out. Change the number and hit enter to adjust the averaging period.)</p>
68f9bed3 105
15c966e0
AK
106 <div id="demodiv" style="width:800px; height:320px;"></div>
107 <script type="text/javascript">
68f9bed3 108 g = new Dygraph(
15c966e0
AK
109 document.getElementById("demodiv"),
110 "ny-vs-sf.txt",
111 {
112 rollPeriod: 14,
113 showRoller: true,
114 customBars: true,
3bc2cb3c
DV
115 title: 'Daily Temperatures in New York vs. San Francisco',
116 ylabel: 'Temperature (F)',
fe45f972
DV
117 legend: 'always',
118 labelsDivStyles: { 'textAlign': 'right' }
15c966e0 119 }
68f9bed3 120 );
15c966e0 121 </script>
68f9bed3 122
15c966e0
AK
123 <h4>Some things to notice:</h4>
124 <ul>
68f9bed3
AK
125 <li>There's less seasonal temperature variation in SF than in NY.</li>
126 <li>The difference is about 15&deg; F for SF vs. 50&deg; F for NY.</li>
127 <li>The daily data (set rolling period to 1) is quite noisy and hides this conclusion.</li>
128 <li>Using a 14-day moving average makes it clearer. A 100-day rolling period averages out nearly all the specifics from the data.</li>
129 <li>There's a gap in the data for SF, when the weather station was down (zoom into October 2007 to see it).</li>
130 <li>The bands around each point indicate average highs and lows.</li>
131 <li>There is a <em>lot</em> of data in this chart: low, average and high for each city on each day of a three year period &asymp; 6000 data points in all.</li>
15c966e0 132 </ul>
68f9bed3 133
15c966e0 134 <p>dygraphs allows the user to explore the data and discover these facts.</p>
68f9bed3 135
ab80172e
DV
136 <p>For more demos, browse the dygraph <a href="tests/">tests</a>
137 directory. To see other people who are using dygraphs, check out the <a
138 href="#gallery">usage gallery</a>.</p>
68f9bed3 139
15c966e0
AK
140 <h3>Features</h3>
141 <p>Some of the features of dygraphs:</p>
142 <ul>
68f9bed3
AK
143 <li>Plots time series without using an external server or Flash</li>
144 <li>Works in Internet Explorer (using excanvas)</li>
c4370b98 145 <li>Lightweight (69kb) and responsive</li>
ca49434a 146 <li>Displays values on mouseover, making interaction easily discoverable</li>
68f9bed3
AK
147 <li>Supports error bands around data series</li>
148 <li>Interactive zoom</li>
2b2a2f1c 149 <li>Displays Annotations on the chart</li>
68f9bed3
AK
150 <li>Adjustable averaging period</li>
151 <li>Can intelligently chart fractions</li>
152 <li>Customizable click-through actions</li>
153 <li>Compatible with the Google Visualization API</li>
154 <li>Intelligent defaults make it easy to use</li>
15c966e0 155 </ul>
68f9bed3 156
15c966e0 157 <h2 id="usage">Usage</h2>
68f9bed3 158
15c966e0 159 <p>To use dygraphs, include the <code><a href="http://github.com/danvk/dygraphs/downloads/">dygraph-combined.js</a></code> JavaScript file and instantiate a <code>Dygraph</code> object.</p>
68f9bed3 160
15c966e0 161 <p>Here's a basic example to get things started:</p>
68f9bed3 162
15c966e0 163 <div class="example" style="clear:both;">
68f9bed3 164 <div class="codeblock" style="float:left;width:400px;">
15c966e0
AK
165 <h3 style="text-align:center">HTML</h3>
166 <code>
167 <pre>
078d1d29
DV
168&lt;html&gt;
169&lt;head&gt;
68f9bed3 170&lt;script type=&quot;text/javascript&quot;
15c966e0 171 src=&quot;dygraph-combined.js&quot;&gt;&lt;/script&gt;
078d1d29
DV
172&lt;/head&gt;
173&lt;body&gt;
68f9bed3
AK
174&lt;div id=&quot;graphdiv&quot;&gt;&lt;/div&gt;
175&lt;script type=&quot;text/javascript&quot;&gt;
15c966e0
AK
176 g = new Dygraph(
177
178 // containing div
179 document.getElementById(&quot;graphdiv&quot;),
180
181 // CSV or path to a CSV file.
182 &quot;Date,Temperature\n&quot; +
183 &quot;2008-05-07,75\n&quot; +
184 &quot;2008-05-08,70\n&quot; +
185 &quot;2008-05-09,80\n&quot;
186
187 );
078d1d29
DV
188&lt;/script&gt;
189&lt;/body&gt;
190&lt;/html&gt;
15c966e0
AK
191</pre>
192 </code>
68f9bed3
AK
193 </div>
194 <div class="codeoutput" style="float:left;">
15c966e0
AK
195 <h3 style="text-align:center">OUTPUT</h3>
196 <div id="graphdiv"></div>
197 <script type="text/javascript">
198 g = new Dygraph(
199
200 // containing div
201 document.getElementById("graphdiv"),
202
203 // CSV or path to a CSV file.
204 "Date,Temperature\n" +
205 "2008-05-07,75\n" +
206 "2008-05-08,70\n" +
207 "2008-05-09,80\n"
208 );
209 </script>
68f9bed3 210 </div>
15c966e0 211 </div>
68f9bed3 212
ff00d3e2 213 <p style="clear:both">In order to keep this example self-contained, the second parameter is raw CSV data. The dygraphs library parses this data (including column headers), resizes its container to a reasonable default, calculates appropriate axis ranges and tick marks and draws the graph.</p>
68f9bed3 214
15c966e0 215 <p>In most applications, it makes more sense to include a CSV file instead. If the second parameter to the constructor doesn't contain a newline, it will be interpreted as the path to a CSV file. The Dygraph will perform an XMLHttpRequest to retrieve this file and display the data when it becomes available. Make sure your CSV file is readable and serving from a place that understands XMLHttpRequest's! In particular, you cannot specify a CSV file using <code>"file:///"</code>. Here's an example: (data from <a href="http://www.wunderground.com/history/airport/KNUQ/2007/1/1/CustomHistory.html?dayend=31&amp;monthend=12&amp;yearend=2007&amp;req_city=NA&amp;req_state=NA&amp;req_statename=NA">Weather Underground</a>)</p>
68f9bed3 216
15c966e0 217 <div class="example" style="clear:both;">
68f9bed3 218 <div class="codeblock" style="float:left;width:400px;">
15c966e0
AK
219 <h3 style="text-align:center">HTML</h3>
220 <code>
68f9bed3 221<pre>
078d1d29
DV
222&lt;html&gt;
223&lt;head&gt;
68f9bed3 224&lt;script type=&quot;text/javascript&quot;
15c966e0 225 src=&quot;dygraph-combined.js&quot;&gt;&lt;/script&gt;
078d1d29
DV
226&lt;/head&gt;
227&lt;body&gt;
68f9bed3
AK
228&lt;div id=&quot;graphdiv2&quot;
229 style=&quot;width:500px; height:300px;&quot;&gt;&lt;/div&gt;
230&lt;script type=&quot;text/javascript&quot;&gt;
15c966e0
AK
231 g2 = new Dygraph(
232 document.getElementById(&quot;graphdiv2&quot;),
233 &quot;temperatures.csv&quot;, // path to CSV file
234 {} // options
235 );
078d1d29
DV
236&lt;/script&gt;
237&lt;/body&gt;
238&lt;/html&gt;
239</pre>
15c966e0 240 </code>
68f9bed3
AK
241 </div>
242 <div class="codeoutput" style="float:left;">
15c966e0
AK
243 <h3 style="text-align:center">OUTPUT</h3>
244 <div id="graphdiv2" style="width:500px; height:300px;"></div>
245 <script type="text/javascript">
246 g2 = new Dygraph(
247 document.getElementById("graphdiv2"),
248 "temperatures.csv",
249 {}
250 );
251 </script>
68f9bed3 252 </div>
15c966e0 253 </div>
68f9bed3 254
15c966e0 255 <p style="clear:both;">The file used is <code><a href="temperatures.csv">temperatures.csv</a></code>.</p>
68f9bed3 256
15c966e0 257 <p>There are a few things to note here:</p>
68f9bed3 258
15c966e0 259 <ul>
68f9bed3
AK
260 <li>The Dygraph sent off an XHR to get the temperatures.csv file.</li>
261 <li>The labels were taken from the first line of <code>temperatures.csv</code>, which is <code>Date,High,Low</code>.</li>
262 <li>The Dygraph automatically chose two different, easily-distinguishable colors for the two data series.</li>
263 <li>The labels on the x-axis have switched from days to months. If you zoom in, they'll switch to weeks and then days.</li>
264 <li>Some heuristics are used to determine a good vertical range for the data. The idea is to make all the data visible and have human-friendly values on the axis (i.e. 200 instead of 193.4). Generally this works well.</li>
265 <li>The data is very spiky. A moving average would be easier to interpret.</li>
15c966e0 266 </ul>
68f9bed3 267
15c966e0 268 <p>This problem can be fixed by specifying the appropriate options in the "additional options" parameter to the Dygraph constructor. To set the number of days for a moving average, use the <code>rollPeriod</code> option. Here's how it's done:</p>
68f9bed3 269
15c966e0 270 <div class="example" style="clear:both;">
68f9bed3 271 <div class="codeblock" style="float:left;width:400px;">
15c966e0
AK
272 <h3 style="text-align:center">HTML</h3>
273 <code>
68f9bed3 274<pre>
078d1d29
DV
275&lt;html&gt;
276&lt;head&gt;
68f9bed3 277&lt;script type=&quot;text/javascript&quot;
15c966e0 278 src=&quot;dygraph-combined.js&quot;&gt;&lt;/script&gt;
078d1d29
DV
279&lt;/head&gt;
280&lt;body&gt;
68f9bed3 281&lt;div id=&quot;graphdiv3&quot;
15c966e0 282 style=&quot;width:500px; height:300px;&quot;&gt;&lt;/div&gt;
68f9bed3 283&lt;script type=&quot;text/javascript&quot;&gt;
15c966e0
AK
284 g3 = new Dygraph(
285 document.getElementById(&quot;graphdiv3&quot;),
286 &quot;temperatures.csv&quot;,
287 {
288 rollPeriod: 7,
289 showRoller: true
290 }
291 );
078d1d29
DV
292&lt;/script&gt;
293&lt;/body&gt;
294&lt;/html&gt;
295</pre>
15c966e0 296 </code>
68f9bed3
AK
297 </div>
298 <div class="codeoutput" style="float:left;">
15c966e0
AK
299 <h3 style="text-align:center">OUTPUT</h3>
300 <div id="graphdiv3" style="width:500px; height:300px;"></div>
301 <script type="text/javascript">
302 g3 = new Dygraph(
303 document.getElementById("graphdiv3"),
304 "temperatures.csv",
305 {
306 rollPeriod: 7,
307 showRoller: true
308 }
309 );
310 </script>
68f9bed3 311 </div>
15c966e0
AK
312 </div>
313
314 <p style="clear:both;">A rolling average can be set using the text box in the lower left-hand corner of the graph (the showRoller attribute is what makes this appear). Also note that we've explicitly set the size of the chart div.</p>
68f9bed3 315
15c966e0 316 <h2>Error Bars</h2>
68f9bed3 317
15c966e0 318 <p>Another significant feature of the dygraphs library is the ability to display error bars around data series. One standard deviation must be specified for each data point. A <em>&plusmn;n</em> sigma band will be drawn around the data series at that point. If a moving average is being displayed, dygraphs will compute the standard deviation of the average at each point. I.E. <em>&sigma; = sqrt( (&sigma;<sub>1<sup>2</sup></sub> + &sigma;<sub>2<sup>2</sup></sub> + ... + &sigma;<sub>n<sup>2</sup></sub>) / n )</em></p>
68f9bed3 319
15c966e0 320 <p>Here's a demonstration. There are two data series. One is <code>N(100,10)</code> with a standard deviation of 10 specified at each point. The other is <code>N(80,20)</code> with a standard deviation of 20 specified at each point. The CSV file was generated using Octave and can be viewed at <a href="twonormals.csv">twonormals.csv</a>.</p>
68f9bed3 321
15c966e0 322 <div class="example" style="clear:both;">
68f9bed3 323 <div class="codeblock" style="float:left;width:400px;">
15c966e0
AK
324 <h3 style="text-align:center">HTML</h3>
325 <code>
68f9bed3 326<pre>
078d1d29
DV
327&lt;html&gt;
328&lt;head&gt;
68f9bed3 329&lt;script type=&quot;text/javascript&quot;
15c966e0 330 src=&quot;combined.js&quot;&gt;&lt;/script&gt;
078d1d29
DV
331&lt;/head&gt;
332&lt;body&gt;
68f9bed3 333&lt;div id=&quot;graphdiv4&quot;
096c1158 334 style=&quot;width:480px; height:320px;&quot;&gt;&lt;/div&gt;
68f9bed3 335&lt;script type=&quot;text/javascript&quot;&gt;
15c966e0
AK
336 g4 = new Dygraph(
337 document.getElementById(&quot;graphdiv4&quot;),
338 &quot;twonormals.csv&quot;,
339 {
340 rollPeriod: 7,
341 showRoller: true,
342 errorBars: true,
343 valueRange: [50,125]
344 }
345 );
078d1d29
DV
346&lt;/script&gt;
347&lt;/body&gt;
348&lt;/html&gt;
349</pre>
15c966e0 350 </code>
68f9bed3
AK
351 </div>
352 <div class="codeoutput" style="float:left;">
15c966e0 353 <h3 style="text-align:center">OUTPUT</h3>
096c1158 354 <div id="graphdiv4" style="width:480px; height:320px;"></div>
15c966e0
AK
355 <script type="text/javascript">
356 g4 = new Dygraph(
357 document.getElementById("graphdiv4"),
358 "twonormals.csv",
359 {
360 rollPeriod: 7,
361 showRoller: true,
362 errorBars: true,
363 valueRange: [50,125]
364 }
365 );
366 </script>
68f9bed3 367 </div>
15c966e0 368 </div>
68f9bed3 369
15c966e0
AK
370 <p style="clear:both;">Things to note here:</p>
371
372 <ul>
68f9bed3
AK
373 <li>The <strong>errorBars</strong> option affects both the interpretation of the CSV file and the display of the graph. When <strong>errorBars</strong> is set to true, each line is interpreted as <em>YYYYMMDD</em>, <em>A</em>, <em>sigma_A</em>, <em>B</em>, <em>sigma_B</em>, &hellip;</li>
374 <li>The first line of the CSV file doesn't mention the error columns. In this case, it's just "Date,Series1,Series2".</li>
375 <li>The averaging visibly affects the error bars. This is most clear if you crank up the rolling period to something like 100 days. For the earliest dates, there won't be 100 data points to average so the signal will be noisier. The error bars get smaller like sqrt(N) going forward in time until there's a full 100 points to average.</li>
376 <li>The error bars are partially transparent. This can be seen when they overlap one another.</li>
15c966e0 377 </ul>
68f9bed3 378
15c966e0 379 <h2 id="ie">Internet Explorer Compatibility</h2>
68f9bed3 380
1b8d37e5 381 <p>The dygraphs library relies heavily on the HTML5 <code>&lt;canvas&gt;</code> tag, which Microsoft Internet Explorer did not traditionally support. To use Microsoft's native canvas implementation in IE9, you need to set an HTML5 doctype on your page:</p>
435c59c9 382
25c2433d
DV
383<pre>
384&lt;!DOCTYPE html&gt;
385</pre>
1b8d37e5
DV
386
387 <p>When IE9 is in HTML5 mode, dygraphs works just like in other modern browsers.</p>
388
25c2433d 389 <p>If you want to support previous versions of Internet Explorer (IE6&ndash;IE8), you'll need to include the <a href="http://code.google.com/p/explorercanvas/">excanvas</a> library, which emulates the <code>&lt;canvas&gt;</code> tag using VML. You can add excanvas by including the following snippet:</p>
435c59c9
DV
390
391<pre>
25c2433d
DV
392&lt;!DOCTYPE html&gt;
393&lt;html&gt;
394 &lt;head&gt;
395 &lt;meta http-equiv="X-UA-Compatible" content="IE=EmulateIE7; IE=EmulateIE9"&gt;
396 &lt;!--[if IE]&gt;&lt;script src="path/to/excanvas.js"&gt;&lt;/script&gt;&lt;![endif]--&gt;
397 &lt;/head&gt;
435c59c9
DV
398</pre>
399
25c2433d
DV
400<p>(This is surprisingly tricky because the HTML5 doctype breaks excanvas in IE8. See <a href="https://groups.google.com/group/dygraphs-users/browse_thread/thread/c60709e04bc7fe5f#">this discussion</a> for details.)</p>
401
402 <p>While VML emulation sounds like it would be slow, it works well in practice for most charts.</p>
435c59c9 403
15c966e0 404 <p>One common gotcha to look out for: make sure you don't have any trailing commas in parameter lists, e.g.</p>
435c59c9 405
68f9bed3
AK
406<pre>
407new Dygraph(el, data, {
15c966e0 408 showRoller: true, // note trailing comma
435c59c9
DV
409})</pre>
410
68f9bed3 411 <p>Most browsers will ignore the trailing comma, but it will break under IE.</p>
aaa21dc9 412
68f9bed3 413 <h2 id="gviz">GViz Data</h2>
435c59c9 414
2b2a2f1c
DV
415 <p>The <a
416 href="http://code.google.com/apis/visualization/documentation/index.html">Google
417 Visualization API</a> provides a standard interface for describing data.
418 Once you've specified your data using this API, you can plug in any
419 GViz-compatible visualization. dygraphs is such a visualization. In
420 particular, it can be used as a drop-in replacement for the
421 AnnotatedTimeline visualization used on Google Finance and other sites. To
422 see how this works, check out the <a href="tests/annotation-gviz.html">gviz
423 annotation demo.</a></p>
36676109 424
68f9bed3 425 <p>For a simple demonstration of how to use dygraphs a GViz visualization, see <a href="http://danvk.org/dygraphs/tests/gviz.html">http://danvk.org/dygraphs/tests/gviz.html</a>. dygraphs can also be used as a GViz gadget. This allows it to be embedded inside of a Google Spreadsheet. For a demonstration of this, see <a href="http://spreadsheets.google.com/ccc?key=0Anx1yCqeL8YUdDR1c3pPREhraGhkWmdhaURjOXRncXc&amp;hl=en">this spreadsheet</a>. The URL for the gadget is <code><a href="http://danvk.org/dygraphs/gadget.xml">http://danvk.org/dygraphs/gadget.xml</a></code>.</p>
36676109 426
68f9bed3 427 <p>Here's an example of a published gviz gadget using dygraphs:</p>
a87e8e01 428
15c966e0 429 <script src="http://spreadsheets.google.com/gpub?url=http%3A%2F%2Fkb8jbn8l90ocl9n4b14jrcvp61ceqis5.spreadsheets.gmodules.com%2Fgadgets%2Fifr%3Fup__table_query_url%3Dhttp%253A%252F%252Fspreadsheets.google.com%252Ftq%253Frange%253DA1%25253AC31%2526headers%253D-1%2526key%253D0Anx1yCqeL8YUdDR1c3pPREhraGhkWmdhaURjOXRncXc%2526gid%253D0%2526pub%253D1%26up__table_query_refresh_interval%3D300%26url%3Dhttp%253A%252F%252Fdanvk.org%252Fdygraphs%252Fgadget.xml%253Fnocache&height=215&width=530"></script>
a87e8e01 430
68f9bed3 431 <h2 id="baseball">Charting Fractions</h2>
15c966e0 432
68f9bed3
AK
433 <p>Situations often arise where you want to plot fractions, e.g. the fraction of respondents in a poll who said they'd vote for candidate X or the number of hits divided by at bats (baseball's batting average). Fractions require special treatment for two main reasons:</p>
434
435 <ul>
15c966e0
AK
436 <li>The average of <code>a1/b1</code> and <code>a2/b2</code> is <code>(a1+a2)/(b1+b2)</code>, not <code>(a1/b1 + a2/b2)/2</code>.</li>
437 <li>The normal approximation is not always applicable and more sophisticated confidence intervals (e.g. the <a href="http://en.wikipedia.org/wiki/Binomial_proportion_confidence_interval">Wilson confidence interval</a>) must be employed to avoid ratios that exceed 100% or go below 0%.</li>
68f9bed3
AK
438 </ul>
439
440 <p>Fortunately, dygraphs handles both of these for you! Here's a chart and the command that generated it:</p>
441
442 <div style="width:750px; text-align:center; font-weight: bold; font-size: 125%;">Batting Average for Ichiro Suzuki vs. Mariners (2004)</div>
443 <div id="baseballdiv" style="width:750px; height:300px;"></div>
444 <script type="text/javascript">
15c966e0
AK
445 new Dygraph(
446 document.getElementById("baseballdiv"),
447 "suzuki-mariners.txt",
448 {
449 fractions: true,
450 errorBars: true,
451 showRoller: true,
452 rollPeriod: 15
453 }
454 );
68f9bed3
AK
455 </script>
456
457 <p>Command:</p>
a87e8e01 458<pre>
15c966e0 459 new Dygraph(
68f9bed3
AK
460 document.getElementById(&quot;baseballdiv&quot;),
461 &quot;suzuki-mariners.txt&quot;,
462 {
15c966e0
AK
463 fractions: true,
464 errorBars: true,
465 showRoller: true,
466 rollPeriod: 15
68f9bed3 467 }
15c966e0 468 );
a87e8e01
DV
469</pre>
470
68f9bed3
AK
471 <p>The <code>fractions</code> option indicates that the values in each column should be parsed as fractions (e.g. "1/2" instead of "0.5"). The <code>errorBars</code> option indicates that we'd like to see a confidence interval around each data point. By default, when <code>fractions</code> is set, you get a Wilson confidence interval. If you look carefully at the chart, you can see that the error bars are asymmetric.</p>
472
473 <p>A couple things to notice about this chart:</p>
15c966e0 474
68f9bed3 475 <ul>
15c966e0
AK
476 <li>The error bars for Ichiro's batting average are larger than for the Mariners', since he has far fewer at bats than his team.</li>
477 <li>dygraphs makes it easy to see "batting average over the last 30 games". This is ordinarily quite difficult to compute. It makes it clear where the "hot" and "cold" part of Suzuki's season were.</li>
478 <li>If you set the averaging period to something large, like 200, you'll see the team's and player's batting average through that game. The final number is the overall batting average for the season.</li>
479 <li>Where the error bars do not overlap, we can say with 95% confidence that the series differ. There is a better than 95% chance that Ichiro was a better hitter than his team as a whole in 2004, the year he won the batting title.</li>
68f9bed3
AK
480 </ul>
481
482 <h2 id="stock">One last demo</h2>
483
484 <p>This chart shows monthly closes of the Dow Jones Industrial Average, both in nominal and real (i.e. adjusted for inflation) dollars. The shaded areas show its monthly high and low. CPI values with a base from 1982-84 are used to adjust for inflation.</p>
485
096c1158 486 <div id="dow_chart" style="width:750px; height:350px;"></div>
7ffbfdc1
DV
487 <p><b>Display: </b>
488 <input type=checkbox id=0 onClick="stockchange(this)" checked>
489 <label for="0"> Nominal</label>
490 <input type=checkbox id=1 onClick="stockchange(this)" checked>
491 <label for="1"> Real</label>
2b2a2f1c
DV
492 <input type=checkbox id=ann onClick="annotationschange(this)" checked>
493 <label for="ann"> Annotations</label>
7ffbfdc1
DV
494 </p>
495
68f9bed3 496 <script type="text/javascript">
2b2a2f1c
DV
497 var stock_annotations = [
498 {
499 series: "Real",
500 x: "1929-08-15",
501 shortText: "A",
502 text: "1929 Stock Market Peak"
503 },
504 {
505 series: "Nominal",
506 x: "1987-08-15",
507 shortText: "B",
508 text: "1987 Crash"
509 },
510 {
511 series: "Nominal",
512 x: "1999-12-15",
513 shortText: "C",
514 text: "1999 (.com) Peak"
515 },
516 {
517 series: "Nominal",
518 x: "2007-10-15",
519 shortText: "D",
520 text: "All-Time Market Peak"
521 }
522 ];
523
15c966e0 524 // From http://www.econstats.com/eqty/eq_d_mi_3.csv
7ffbfdc1 525 stockchart = new Dygraph(
15c966e0
AK
526 document.getElementById('dow_chart'),
527 "dow.txt",
528 {
529 showRoller: true,
530 customBars: true,
2b2a2f1c
DV
531 labelsKMB: true,
532 drawCallback: function(g, is_initial) {
533 if (!is_initial) return;
534 g.setAnnotations( stock_annotations );
535 }
15c966e0
AK
536 }
537 );
7ffbfdc1
DV
538
539 function stockchange(el) {
540 stockchart.setVisibility(el.id, el.checked);
541 }
2b2a2f1c
DV
542
543 function annotationschange(el) {
544 if (el.checked) {
545 stockchart.setAnnotations(stock_annotations);
546 } else {
547 stockchart.setAnnotations([]);
548 }
549 }
68f9bed3 550 </script>
94a2e379
DV
551<!--
552
553Here is a script to regenerate the Dow Jones plot:
554
555# Get unadjusted DJIA data in a nice format:
556curl -O http://www.econstats.com/eqty/eq_d_mi_3.csv
557sed '1,17d' eq_d_mi_3.csv | cut -d, -f1,6 | perl -pe 's/(\d{4}-\d\d)-\d\d/$1/g' | perl -pe 's/, */\t/' | grep -v 'na' | perl -ne 'chomp; ($m,$v) = split/\t/; $close{$m} = $v; if ($low{$m} == 0 || $v < $low{$m}) { $low{$m}=$v } if ($v > $high{$m}) { $high{$m} = $v } END { for $x(sort keys %close) { print "$x\t$low{$x}\t$close{$x}\t$high{$x}\n" } } ' > monthly-djia.tsv
558
559# Fetch and format the CPI data:
560curl 'http://data.bls.gov/PDQ/servlet/SurveyOutputServlet?series_id=CUUR0000SA0&years_option=all_years&periods_option=all_periods&output_type=column&output_format=text&delimiter=comma' > cpi-u.txt
561sed '1,/Series Id,Year,/d' cpi-u.txt | sed '/^$/,$d' | cut -d, -f2,3,4 | perl -ne 'print if /,M(0[0-9]|1[012]),/' | perl -pe 's/(\d{4}),M(\d{2}),/$1-$2\t/g' > cpi-u.tsv
562
563# Merge:
15c966e0 564join -t' ' cpi-u.tsv monthly-djia.tsv > annotated-djia.tsv
94a2e379
DV
565perl -ne 'BEGIN{print "Month,Nominal,Real\n"} chomp; ($m,$cpi,$low,$close,$high) = split /\t/; $cpi /= 100.0; print "$m-15,$low;$close;$high,",($low/$cpi),";",($close/$cpi),";",($high/$cpi),"\n"' annotated-djia.tsv > dow.txt
566
567-->
353a0294 568
68f9bed3
AK
569 <h2 id="options">Other Options</h2>
570
5af2de24
DV
571 <p>In addition to the options mentioned above (<code>showRoller</code>, <code>rollPeriod</code>, <code>errorBars</code>, <code>valueRange</code>), there are <i>many</i> others.</p>
572
573 <p>For a full list, see the <a href="options.html">Dygraphs Options Reference</a> page.</p>
68f9bed3
AK
574
575 <h2>Common Gotchas</h2>
576
577 <p>Here are a few problems that I've frequently run into while using the dygraphs library.</p>
578
579 <ul>
dde90a16 580 <li>If your chart doesn't display, be sure to check your browser's JavaScript error console. dygraphs makes every attempt to log errors and warnings, and these can often guide you in the right direction.</li>
15c966e0
AK
581 <li>Make sure your CSV files are readable! If your graph isn't showing up, the XMLHttpRequest for the CSV file may be failing. You can determine whether this is the case using tools like <a href="http://www.getfirebug.com/">Firebug</a>.</li>
582 <li>Make sure your CSV files are in the correct format. They must be of the form <code>YYYYMMDD, series1, series2, </code>&hellip; . And if you set the <code>errorBars</code> property, make sure you alternate data series and standard deviations.</li>
583 <li>dygraphs are not happy when placed inside a <code>&lt;center&gt;</code> tag. This applies to the CSS <code>text-align</code> property as well. If you want to center a Dygraph, put it inside a table with <code>align = center</code> set.</li>
584 <li>Don't set the <code>dateWindow</code> property to a date. It expects milliseconds since epoch, which can be obtained from a JavaScript Date object's valueOf method.</li>
585 <li>Make sure you don't have any trailing commas in your call to the Dygraph constructor or in the options parameter. Firefox, Chrome and Safari ignore these but they can cause a graph to not display in Internet Explorer.</li>
68f9bed3
AK
586 </ul>
587
71ac4733
AV
588 <h2 id="gwt">GWT Compatibility</h2>
589 <p>There is currently no GWT wrapper around Dygraphs, however there is a class that can be used to easily load Dygraphs into the browser. To use it, include the generated dygraph-gwt.jar file in your classpath and add the following line to your GWT module:</p>
590
591<pre>
592&lt;inherits name=&quot;org.danvk.dygraphs&quot;/&gt;
593</pre>
594
595 <p>Call org.danvk.Dygraphs.install() when your application starts to install the JavaScript code into the browser. You can use <a href="http://code.google.com/webtoolkit/doc/latest/DevGuideCodingBasicsJSNI.html">JSNI</a> to call Dygraphs from your GWT code, as in the example below. The example uses the <a href="http://code.google.com/p/gwt-google-apis/wiki/VisualizationGettingStarted">Visualization API for GWT</a> and the <a href="#gviz">Dygraphs GViz API.</a></p>
596
597<pre>
096c1158
DV
598public static native JavaScriptObject drawDygraph(
599 Element element, DataTable dataTable, double minY, double maxY) /*-{
600 var chart = new $wnd.Dygraph.GVizChart(element);
601 chart.draw(dataTable,
602 {
603 valueRange: [minY, maxY]
604 });
605 return chart;
606}-*/;
71ac4733
AV
607</pre>
608
ab80172e
DV
609 <a name="gallery" />
610 <h2>Usage Gallery</h2>
611 <p>Since its public release in late 2009, dygraphs has found many users
612 across the web. This is a small collection of the uses that we know about.
613 If you're using dygraphs, please send <a
614 href="mailto:dan@dygraphs.com">Dan</a> a link and he'll add it to this
615 list.</p>
616
617 <p>dygraphs was originally developed at Google and has found wide use on
618 internal dashboards and servers there. There are also a few uses of
619 dygraphs on public Google products:</p>
620
621 <ul class='padded-list'>
622 <li><a href="http://www.google.com/trends/correlate/search?e=id:20xKcnNqHrk&t=weekly">Google Correlate</a><br/>
623 <span class="desc">Uses dygraphs for time series visualization. Mostly a standard configuration, with just a few tweaks to match Google style.</span></li>
624
625 <li><a href="http://www.google.com/trends/correlate/draw?p=us">Google Correlate - Search by Drawing</a><br/>
626 <span class="desc">This is a highly customized configuration which lets the user draw a time series. Based on <a href="tests/drawing.html">this demo</a>.</span></li>
627
628 <li><a href="https://www.google.com/latitude/b/0/history/manage">Google Latitude History Dashboard</a><br/>
629 <span class="desc">Uses mouse interaction callbacks to synchronize time series points with markers on a Google Map.</span></li>
630 </ul>
631
632 <p>dygraphs has also found use in other organizations:</p>
633
634 <ul class='padded-list'>
19add90b
DV
635 <li><a
636 href="http://iswa.ccmc.gsfc.nasa.gov:8080/IswaSystemWebApp/index.jsp?i_1=388&l_1=99&t_1=316&w_1=800&h_1=400&s_1=0!3!0!ACE.B_x!ACE.B_y!ACE.B_z!">Integrated
637 Space Weather Analysis System</a> (NASA)<br/>
638 <span class="desc">&ldquo;We use [dygraphs] in the Integrated Space Weather
639 Analysis System available from the Space Weather Laboratory at NASA Goddard
640 Space Flight Center. It works quite well for time series data from various
641 missions and simulations that we store.&rdquo;</span></li>
642
643
644 <li><a href="http://www.eutelsat.fr">Eutelsat</a><br/>
645 <span class="desc">&ldquo;Eutelsat uses dygraphs for charting spacecraft
646 telemetry for a fleet of 25 geostationary satellites. The spacecraft
647 engineers are very happy with it. All satellite combined are producing
648 about 200 millions unique data points per day so we really appreciate the
649 excellent performance of dygraphs.&rdquo;</span></li>
650
965cd401
DV
651 <li><a href="http://www.10gen.com/mongodb-monitoring-service">10gen MongoDB
652 Monitoring Service</a><br/>
653 <span class="desc">A free monitoring service for MongoDB from 10gen (the
654 creators of MongoDB). Used by thousands of servers and users. Makes use of
655 <a href="tests/synchronize.html">synchronized charts</a> to display many
656 quantities simultaneously.</span></li>
657
ab80172e
DV
658 <li><a href="http://toolserver.org/~dartar/moodbar/">Wikimedia Foundation - Moodbar data dashboard</a><br/>
659 <span class="desc">dygraphs is used internally at Wikimedia as a handy solution to monitor the
660 results of a bunch of small experiments.</span></li>
161b2a6f 661
db2e28cb
DV
662 <li><a href="http://code.google.com/p/quadrant-framework/">quadrant-framework</a> (MySQL Load Testing Framework)<br/>
663 <span class="desc">A user friendly framework for creating and visualizing
664 MySQL database load test jobs. For more information on its use of dygraphs,
665 see <a href="http://themattreid.com/wordpress/2011/05/20/quadrant-framework-rev7-update-adds-dygraphs-support/">this post</a>.</span></li>
666
667 <li><a href="http://spinwave.wordpress.com/2011/03/28/spinwave-systems-enables-energy-efficiency-case-studies/">Spinwave Systems</a> (Home energy monitoring)<br/>
668 <span class="desc">dygraphs is used to chart energy usage over time.</span></li>
669
19add90b 670
161b2a6f
DV
671 <li><a href="http://www.socib.es/jwebchart/?file=http://thredds.socib.es/thredds/dodsC/mooring/weather_station/mobims_calamillor-scb_met001/L1/dep0001_mobims-calamillor_scb-met001_L1_latest.nc">Jwebchart</a><br/>
672 <span class="desc">
673 jWebChart is a stand-alone and Thredds' embedded plotting system for
674 netCDF files. NetCDF is a common standard for the storage and
675 distribution of scientific data.
676 </span></li>
677
7a8dd19c 678 <li><a href="http://ngrams.cavorite.com/">n-gramas - Explore las tendencias en los artículos periodísticos de Colombia.</a><br/>
89055383
DV
679
680
7a8dd19c
DV
681 <span class="desc">(English: "Explore trends in newspaper articles of
682 Colombia"). dygraphs is used for displaying the results of this n-grams
683 viewer. Uses an extension for exporting the plots as PNG images
684 (<a href="http://cavorite.com/labs/js/dygraphs-export/">[1]</a>, <a href="https://github.com/cavorite/dygraphs">[2]</a>).
685 </span></li>
686
ab80172e
DV
687 </ul>
688
689 <p>Are you using dygraphs? Please let <a href="mailto:dan@dygraphs.com">Dan</a> know and he'll add your link here!</p>
690
691
68f9bed3 692 <h2 id="policy">Data Policy</h2>
15c966e0 693 <p>dygraphs is purely client-side JavaScript. It does not send your data to any servers &ndash; the data is processed entirely in the client's browser.</p>
2739bb8f 694
68f9bed3 695 <p style="font-size:0.8em">Created May 9, 2008 by <a href=mailto:danvdk@gmail.com>Dan Vanderkam</a></p>
15c966e0 696 </div>
fe57a69b 697
078d1d29 698</body>
65914f5f 699</html>