Merge branch 'master' of http://github.com/danvk/dygraphs
[dygraphs.git] / docs / index.html
CommitLineData
15c966e0 1<!DOCTYPE html>
078d1d29
DV
2<html>
3 <head>
fe57a69b 4 <title>dygraphs JavaScript Visualization Library</title>
078d1d29 5 <!--[if IE]>
15c966e0 6 <script type="text/javascript" src="excanvas.js"></script>
078d1d29 7 <![endif]-->
9f006dbf 8 <script type="text/javascript" src="dygraph-combined.js"></script>
15c966e0 9 <link rel="stylesheet" href="style.css">
078d1d29 10 </head>
15c966e0
AK
11 <body>
12 <div id="nav">
13 <h2>Documentation</h2>
14 <ul>
68f9bed3
AK
15 <li><a href="#demo">Demo</a></li>
16 <li><a href="#usage">Usage</a></li>
17 <li><a href="#ie">IE Compatibility</a></li>
18 <li><a href="#gviz">GViz Data</a></li>
19 <li><a href="#baseball">Baseball chart</a></li>
20 <li><a href="#stock">Stock chart</a></li>
21 <li><a href="#options">Options Reference</a></li>
71ac4733 22 <li><a href="#gwt">GWT Compatibility</a></li>
68f9bed3 23 <li><a href="#policy">Data Policy</a></li>
15c966e0 24 </ul>
68f9bed3 25
2b2a2f1c
DV
26 <h2>Features</h2>
27 <ul>
28 <li><a href="data.html">Data Formats</a></li>
29 <li><a href="annotations.html">Annotations</a></li>
30 </ul>
31
15c966e0
AK
32 <h2>Project</h2>
33 <ul>
68f9bed3
AK
34 <li><a href="http://github.com/danvk/dygraphs">Source</a></li>
35 <li><a href="http://code.google.com/p/dygraphs/issues/">Issues</a></li>
36 <li><a href="http://code.google.com/p/dygraphs/issues/entry">Report Bug</a></li>
a843ade7 37 <li><a href="mailto:dygraphs-users [at] googlegroups.com">Contact</a></li>
15c966e0 38 </ul>
68f9bed3 39
15c966e0
AK
40 <h2>Gallery</h2>
41 <ul>
2b2a2f1c 42 <li><a href="tests/">(browse demos)</a></li>
68f9bed3
AK
43 <li><a href="tests/demo.html">Basic Demo</a></li>
44 <li><a href="tests/gviz.html">GViz Demo</a></li>
45 <li><a href="tests/plotter.html">Equation Plotter</a></li>
46 <li><a href="tests/perf.html">Performance Test</a></li>
2b2a2f1c
DV
47 <li><a href="tests/annotation.html">Annotations</a></li>
48 <li><a href="tests/annotation-gviz.html">Annotations (GViz)</a></li>
116bd142 49 <li><a href="tests/fillGraph.html">Filled Chart</a></li>
68f9bed3 50 <li><a href="tests/perf.html">Fractions</a></li>
bf5b5f4d 51 <li><a href="tests/visibility.html">Visibility</a></li>
68f9bed3
AK
52 <li><a href="tests/label-div.html">Labels in a DIV</a></li>
53 <li><a href="tests/numeric-axis.html">Numeric Axis</a></li>
54 <li><a href="tests/draw-points.html">Dotted Points</a></li>
55 <li><a href="tests/native-format.html">Native Format</a></li>
56 <li><a href="tests/grid_dot.html">Crazy Styles</a></li>
57 <li><a href="tests/spacing.html">Tick spacing</a></li>
58 <li><a href="tests/callback.html">Callbacks</a></li>
59 <li><a href="tests/crosshair.html">Crosshairs</a></li>
60 <li><a href="tests/hourly.html">Hourly/Minutely data</a></li>
61 <li><a href="tests/isolated-points.html">Isolated Points</a></li>
62 <li><a href="tests/missing-data.html">Missing Data</a></li>
63 <li><a href="tests/border.html">Bordered chart</a></li>
64 <li><a href="tests/custom-bars.html">Custom Bars</a></li>
65 <li><a href="tests/customLabel.html">Custom Label Styles</a></li>
66 <li><a href="tests/dygraph.html">Minimal Example</a></li>
67 <li><a href="tests/negative.html">Negative Numbers</a></li>
68 <li><a href="tests/noise.html">Noisy Data</a></li>
69 <li><a href="tests/two-series.html">Multiple Series</a></li>
a7ef12f5 70 <li><a href="tests/highlighted-region.html">Custom Underlay / background</a></li>
6b837a40 71 <li><a href="tests/zoom.html">Tests for zoom operations</a></li>
15c966e0
AK
72 </ul>
73 </div>
fe57a69b 74
15c966e0
AK
75 <div id="content">
76 <h1>dygraphs JavaScript Visualization Library</h1>
68f9bed3 77
15c966e0 78 <p><a href="http://github.com/danvk/dygraphs">http://github.com/danvk/dygraphs</a></p>
a843ade7 79 <p>See <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/">gallery</a> and <a href="http://code.google.com/p/dygraphs/issues/">open issues</a></p>
68f9bed3 80
15c966e0 81 <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 82
15c966e0 83 <h3 id="demo">A demo is worth a thousand words:</h3>
68f9bed3 84
c65f2303 85 <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 86
15c966e0 87 <div id="title" style="width:800px; margin: 1em;text-align:center; font-weight: bold; font-size: 125%;">Temperatures in New York vs. San Francisco</div>
68f9bed3 88
15c966e0
AK
89 <div id="demodiv" style="width:800px; height:320px;"></div>
90 <script type="text/javascript">
68f9bed3 91 g = new Dygraph(
15c966e0
AK
92 document.getElementById("demodiv"),
93 "ny-vs-sf.txt",
94 {
95 rollPeriod: 14,
96 showRoller: true,
97 customBars: true,
98 yAxisLabelWidth: 30
99 }
68f9bed3 100 );
15c966e0 101 </script>
68f9bed3 102
15c966e0
AK
103 <h4>Some things to notice:</h4>
104 <ul>
68f9bed3
AK
105 <li>There's less seasonal temperature variation in SF than in NY.</li>
106 <li>The difference is about 15&deg; F for SF vs. 50&deg; F for NY.</li>
107 <li>The daily data (set rolling period to 1) is quite noisy and hides this conclusion.</li>
108 <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>
109 <li>There's a gap in the data for SF, when the weather station was down (zoom into October 2007 to see it).</li>
110 <li>The bands around each point indicate average highs and lows.</li>
111 <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 112 </ul>
68f9bed3 113
15c966e0 114 <p>dygraphs allows the user to explore the data and discover these facts.</p>
68f9bed3 115
15c966e0 116 <p>For more demos, browse the dygraph <a href="tests/">tests</a> directory.</p>
68f9bed3 117
15c966e0
AK
118 <h3>Features</h3>
119 <p>Some of the features of dygraphs:</p>
120 <ul>
68f9bed3
AK
121 <li>Plots time series without using an external server or Flash</li>
122 <li>Works in Internet Explorer (using excanvas)</li>
2b2a2f1c 123 <li>Lightweight (57kb) and responsive</li>
68f9bed3
AK
124 <li>Displays values on mouseover (this makes it easily discoverable)</li>
125 <li>Supports error bands around data series</li>
126 <li>Interactive zoom</li>
2b2a2f1c 127 <li>Displays Annotations on the chart</li>
68f9bed3
AK
128 <li>Adjustable averaging period</li>
129 <li>Can intelligently chart fractions</li>
130 <li>Customizable click-through actions</li>
131 <li>Compatible with the Google Visualization API</li>
132 <li>Intelligent defaults make it easy to use</li>
15c966e0 133 </ul>
68f9bed3 134
15c966e0 135 <h2 id="usage">Usage</h2>
68f9bed3 136
15c966e0 137 <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 138
15c966e0 139 <p>Here's a basic example to get things started:</p>
68f9bed3 140
15c966e0 141 <div class="example" style="clear:both;">
68f9bed3 142 <div class="codeblock" style="float:left;width:400px;">
15c966e0
AK
143 <h3 style="text-align:center">HTML</h3>
144 <code>
145 <pre>
078d1d29
DV
146&lt;html&gt;
147&lt;head&gt;
68f9bed3 148&lt;script type=&quot;text/javascript&quot;
15c966e0 149 src=&quot;dygraph-combined.js&quot;&gt;&lt;/script&gt;
078d1d29
DV
150&lt;/head&gt;
151&lt;body&gt;
68f9bed3
AK
152&lt;div id=&quot;graphdiv&quot;&gt;&lt;/div&gt;
153&lt;script type=&quot;text/javascript&quot;&gt;
15c966e0
AK
154 g = new Dygraph(
155
156 // containing div
157 document.getElementById(&quot;graphdiv&quot;),
158
159 // CSV or path to a CSV file.
160 &quot;Date,Temperature\n&quot; +
161 &quot;2008-05-07,75\n&quot; +
162 &quot;2008-05-08,70\n&quot; +
163 &quot;2008-05-09,80\n&quot;
164
165 );
078d1d29
DV
166&lt;/script&gt;
167&lt;/body&gt;
168&lt;/html&gt;
15c966e0
AK
169</pre>
170 </code>
68f9bed3
AK
171 </div>
172 <div class="codeoutput" style="float:left;">
15c966e0
AK
173 <h3 style="text-align:center">OUTPUT</h3>
174 <div id="graphdiv"></div>
175 <script type="text/javascript">
176 g = new Dygraph(
177
178 // containing div
179 document.getElementById("graphdiv"),
180
181 // CSV or path to a CSV file.
182 "Date,Temperature\n" +
183 "2008-05-07,75\n" +
184 "2008-05-08,70\n" +
185 "2008-05-09,80\n"
186 );
187 </script>
68f9bed3 188 </div>
15c966e0 189 </div>
68f9bed3 190
ff00d3e2 191 <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 192
15c966e0 193 <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 194
15c966e0 195 <div class="example" style="clear:both;">
68f9bed3 196 <div class="codeblock" style="float:left;width:400px;">
15c966e0
AK
197 <h3 style="text-align:center">HTML</h3>
198 <code>
68f9bed3 199<pre>
078d1d29
DV
200&lt;html&gt;
201&lt;head&gt;
68f9bed3 202&lt;script type=&quot;text/javascript&quot;
15c966e0 203 src=&quot;dygraph-combined.js&quot;&gt;&lt;/script&gt;
078d1d29
DV
204&lt;/head&gt;
205&lt;body&gt;
68f9bed3
AK
206&lt;div id=&quot;graphdiv2&quot;
207 style=&quot;width:500px; height:300px;&quot;&gt;&lt;/div&gt;
208&lt;script type=&quot;text/javascript&quot;&gt;
15c966e0
AK
209 g2 = new Dygraph(
210 document.getElementById(&quot;graphdiv2&quot;),
211 &quot;temperatures.csv&quot;, // path to CSV file
212 {} // options
213 );
078d1d29
DV
214&lt;/script&gt;
215&lt;/body&gt;
216&lt;/html&gt;
217</pre>
15c966e0 218 </code>
68f9bed3
AK
219 </div>
220 <div class="codeoutput" style="float:left;">
15c966e0
AK
221 <h3 style="text-align:center">OUTPUT</h3>
222 <div id="graphdiv2" style="width:500px; height:300px;"></div>
223 <script type="text/javascript">
224 g2 = new Dygraph(
225 document.getElementById("graphdiv2"),
226 "temperatures.csv",
227 {}
228 );
229 </script>
68f9bed3 230 </div>
15c966e0 231 </div>
68f9bed3 232
15c966e0 233 <p style="clear:both;">The file used is <code><a href="temperatures.csv">temperatures.csv</a></code>.</p>
68f9bed3 234
15c966e0 235 <p>There are a few things to note here:</p>
68f9bed3 236
15c966e0 237 <ul>
68f9bed3
AK
238 <li>The Dygraph sent off an XHR to get the temperatures.csv file.</li>
239 <li>The labels were taken from the first line of <code>temperatures.csv</code>, which is <code>Date,High,Low</code>.</li>
240 <li>The Dygraph automatically chose two different, easily-distinguishable colors for the two data series.</li>
241 <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>
242 <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>
243 <li>The data is very spiky. A moving average would be easier to interpret.</li>
15c966e0 244 </ul>
68f9bed3 245
15c966e0 246 <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 247
15c966e0 248 <div class="example" style="clear:both;">
68f9bed3 249 <div class="codeblock" style="float:left;width:400px;">
15c966e0
AK
250 <h3 style="text-align:center">HTML</h3>
251 <code>
68f9bed3 252<pre>
078d1d29
DV
253&lt;html&gt;
254&lt;head&gt;
68f9bed3 255&lt;script type=&quot;text/javascript&quot;
15c966e0 256 src=&quot;dygraph-combined.js&quot;&gt;&lt;/script&gt;
078d1d29
DV
257&lt;/head&gt;
258&lt;body&gt;
68f9bed3 259&lt;div id=&quot;graphdiv3&quot;
15c966e0 260 style=&quot;width:500px; height:300px;&quot;&gt;&lt;/div&gt;
68f9bed3 261&lt;script type=&quot;text/javascript&quot;&gt;
15c966e0
AK
262 g3 = new Dygraph(
263 document.getElementById(&quot;graphdiv3&quot;),
264 &quot;temperatures.csv&quot;,
265 {
266 rollPeriod: 7,
267 showRoller: true
268 }
269 );
078d1d29
DV
270&lt;/script&gt;
271&lt;/body&gt;
272&lt;/html&gt;
273</pre>
15c966e0 274 </code>
68f9bed3
AK
275 </div>
276 <div class="codeoutput" style="float:left;">
15c966e0
AK
277 <h3 style="text-align:center">OUTPUT</h3>
278 <div id="graphdiv3" style="width:500px; height:300px;"></div>
279 <script type="text/javascript">
280 g3 = new Dygraph(
281 document.getElementById("graphdiv3"),
282 "temperatures.csv",
283 {
284 rollPeriod: 7,
285 showRoller: true
286 }
287 );
288 </script>
68f9bed3 289 </div>
15c966e0
AK
290 </div>
291
292 <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 293
15c966e0 294 <h2>Error Bars</h2>
68f9bed3 295
15c966e0 296 <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 297
15c966e0 298 <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 299
15c966e0 300 <div class="example" style="clear:both;">
68f9bed3 301 <div class="codeblock" style="float:left;width:400px;">
15c966e0
AK
302 <h3 style="text-align:center">HTML</h3>
303 <code>
68f9bed3 304<pre>
078d1d29
DV
305&lt;html&gt;
306&lt;head&gt;
68f9bed3 307&lt;script type=&quot;text/javascript&quot;
15c966e0 308 src=&quot;combined.js&quot;&gt;&lt;/script&gt;
078d1d29
DV
309&lt;/head&gt;
310&lt;body&gt;
68f9bed3 311&lt;div id=&quot;graphdiv4&quot;
15c966e0 312 style=&quot;width:600px; height:300px;&quot;&gt;&lt;/div&gt;
68f9bed3 313&lt;script type=&quot;text/javascript&quot;&gt;
15c966e0
AK
314 g4 = new Dygraph(
315 document.getElementById(&quot;graphdiv4&quot;),
316 &quot;twonormals.csv&quot;,
317 {
318 rollPeriod: 7,
319 showRoller: true,
320 errorBars: true,
321 valueRange: [50,125]
322 }
323 );
078d1d29
DV
324&lt;/script&gt;
325&lt;/body&gt;
326&lt;/html&gt;
327</pre>
15c966e0 328 </code>
68f9bed3
AK
329 </div>
330 <div class="codeoutput" style="float:left;">
15c966e0
AK
331 <h3 style="text-align:center">OUTPUT</h3>
332 <div id="graphdiv4" style="width:600px; height:300px;"></div>
333 <script type="text/javascript">
334 g4 = new Dygraph(
335 document.getElementById("graphdiv4"),
336 "twonormals.csv",
337 {
338 rollPeriod: 7,
339 showRoller: true,
340 errorBars: true,
341 valueRange: [50,125]
342 }
343 );
344 </script>
68f9bed3 345 </div>
15c966e0 346 </div>
68f9bed3 347
15c966e0
AK
348 <p style="clear:both;">Things to note here:</p>
349
350 <ul>
68f9bed3
AK
351 <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>
352 <li>The first line of the CSV file doesn't mention the error columns. In this case, it's just "Date,Series1,Series2".</li>
353 <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>
354 <li>The error bars are partially transparent. This can be seen when they overlap one another.</li>
15c966e0 355 </ul>
68f9bed3 356
15c966e0 357 <h2 id="ie">Internet Explorer Compatibility</h2>
68f9bed3 358
15c966e0 359 <p>The dygraphs library relies heavily on HTML's <code>&lt;canvas&gt;</code> tag, which Microsoft Internet Explorer does not support. Fortunately, some clever engineers created the <a href="http://code.google.com/p/explorercanvas/">excanvas</a> library, which implements the <code>&lt;canvas&gt;</code> tag in IE using VML.</p>
435c59c9 360
15c966e0 361 <p>You can add IE support to any page using dygraphs by including the following in your page:</p>
435c59c9
DV
362
363<pre>
364&lt;head&gt;
15c966e0 365 &lt;!--[if IE]&gt;&lt;script src="excanvas.js"&gt;&lt;/script&gt;&lt;![endif]--&gt;
435c59c9
DV
366&lt;/head&gt;
367</pre>
368
15c966e0 369 <p>This works quite well in practice. Charts are responsive, even under VML emulation.</p>
435c59c9 370
15c966e0 371 <p>One common gotcha to look out for: make sure you don't have any trailing commas in parameter lists, e.g.</p>
435c59c9 372
68f9bed3
AK
373<pre>
374new Dygraph(el, data, {
15c966e0 375 showRoller: true, // note trailing comma
435c59c9
DV
376})</pre>
377
68f9bed3 378 <p>Most browsers will ignore the trailing comma, but it will break under IE.</p>
aaa21dc9 379
68f9bed3 380 <h2 id="gviz">GViz Data</h2>
435c59c9 381
2b2a2f1c
DV
382 <p>The <a
383 href="http://code.google.com/apis/visualization/documentation/index.html">Google
384 Visualization API</a> provides a standard interface for describing data.
385 Once you've specified your data using this API, you can plug in any
386 GViz-compatible visualization. dygraphs is such a visualization. In
387 particular, it can be used as a drop-in replacement for the
388 AnnotatedTimeline visualization used on Google Finance and other sites. To
389 see how this works, check out the <a href="tests/annotation-gviz.html">gviz
390 annotation demo.</a></p>
36676109 391
68f9bed3 392 <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 393
68f9bed3 394 <p>Here's an example of a published gviz gadget using dygraphs:</p>
a87e8e01 395
15c966e0 396 <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 397
68f9bed3 398 <h2 id="baseball">Charting Fractions</h2>
15c966e0 399
68f9bed3
AK
400 <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>
401
402 <ul>
15c966e0
AK
403 <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>
404 <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
405 </ul>
406
407 <p>Fortunately, dygraphs handles both of these for you! Here's a chart and the command that generated it:</p>
408
409 <div style="width:750px; text-align:center; font-weight: bold; font-size: 125%;">Batting Average for Ichiro Suzuki vs. Mariners (2004)</div>
410 <div id="baseballdiv" style="width:750px; height:300px;"></div>
411 <script type="text/javascript">
15c966e0
AK
412 new Dygraph(
413 document.getElementById("baseballdiv"),
414 "suzuki-mariners.txt",
415 {
416 fractions: true,
417 errorBars: true,
418 showRoller: true,
419 rollPeriod: 15
420 }
421 );
68f9bed3
AK
422 </script>
423
424 <p>Command:</p>
a87e8e01 425<pre>
15c966e0 426 new Dygraph(
68f9bed3
AK
427 document.getElementById(&quot;baseballdiv&quot;),
428 &quot;suzuki-mariners.txt&quot;,
429 {
15c966e0
AK
430 fractions: true,
431 errorBars: true,
432 showRoller: true,
433 rollPeriod: 15
68f9bed3 434 }
15c966e0 435 );
a87e8e01
DV
436</pre>
437
68f9bed3
AK
438 <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>
439
440 <p>A couple things to notice about this chart:</p>
15c966e0 441
68f9bed3 442 <ul>
15c966e0
AK
443 <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>
444 <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>
445 <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>
446 <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
447 </ul>
448
449 <h2 id="stock">One last demo</h2>
450
451 <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>
452
453 <div id="dow_chart" style="width:900px; height:350px;"></div>
7ffbfdc1
DV
454 <p><b>Display: </b>
455 <input type=checkbox id=0 onClick="stockchange(this)" checked>
456 <label for="0"> Nominal</label>
457 <input type=checkbox id=1 onClick="stockchange(this)" checked>
458 <label for="1"> Real</label>
2b2a2f1c
DV
459 <input type=checkbox id=ann onClick="annotationschange(this)" checked>
460 <label for="ann"> Annotations</label>
7ffbfdc1
DV
461 </p>
462
68f9bed3 463 <script type="text/javascript">
2b2a2f1c
DV
464 var stock_annotations = [
465 {
466 series: "Real",
467 x: "1929-08-15",
468 shortText: "A",
469 text: "1929 Stock Market Peak"
470 },
471 {
472 series: "Nominal",
473 x: "1987-08-15",
474 shortText: "B",
475 text: "1987 Crash"
476 },
477 {
478 series: "Nominal",
479 x: "1999-12-15",
480 shortText: "C",
481 text: "1999 (.com) Peak"
482 },
483 {
484 series: "Nominal",
485 x: "2007-10-15",
486 shortText: "D",
487 text: "All-Time Market Peak"
488 }
489 ];
490
15c966e0 491 // From http://www.econstats.com/eqty/eq_d_mi_3.csv
7ffbfdc1 492 stockchart = new Dygraph(
15c966e0
AK
493 document.getElementById('dow_chart'),
494 "dow.txt",
495 {
496 showRoller: true,
497 customBars: true,
2b2a2f1c
DV
498 labelsKMB: true,
499 drawCallback: function(g, is_initial) {
500 if (!is_initial) return;
501 g.setAnnotations( stock_annotations );
502 }
15c966e0
AK
503 }
504 );
7ffbfdc1
DV
505
506 function stockchange(el) {
507 stockchart.setVisibility(el.id, el.checked);
508 }
2b2a2f1c
DV
509
510 function annotationschange(el) {
511 if (el.checked) {
512 stockchart.setAnnotations(stock_annotations);
513 } else {
514 stockchart.setAnnotations([]);
515 }
516 }
68f9bed3 517 </script>
94a2e379
DV
518<!--
519
520Here is a script to regenerate the Dow Jones plot:
521
522# Get unadjusted DJIA data in a nice format:
523curl -O http://www.econstats.com/eqty/eq_d_mi_3.csv
524sed '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
525
526# Fetch and format the CPI data:
527curl '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
528sed '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
529
530# Merge:
15c966e0 531join -t' ' cpi-u.tsv monthly-djia.tsv > annotated-djia.tsv
94a2e379
DV
532perl -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
533
534-->
353a0294 535
68f9bed3
AK
536 <h2 id="options">Other Options</h2>
537
7e6fad88 538 <p>These are the options that can be passed in through the optional third parameter of the Dygraph constructor. Under each option is a set of links to tests which demonstrate its use. While we attempt to keep this list up-to-date, a more complete list can be found in the <code>Dygraph.DEFAULT_ATTRS</code> map in <code>dygraph.js</code> and the <code>this.options</code> map in <code>dygraph-canvas.js</code>.</p>
68f9bed3
AK
539
540 <table class="thinborder" width="900">
15c966e0
AK
541 <thead>
542 <tr>
543 <th width="150">Name</th>
0c75dc72
DV
544 <th width="200">Values</th>
545 <th width="150">Default</th>
546 <th>Description</th>
15c966e0
AK
547 </tr>
548 </thead>
549 <tbody>
550 <tr>
551 <td><strong>includeZero</strong></td>
552 <td><code>boolean</code></td>
553 <td><code>false</code></td>
dde90a16 554 <td>Usually, dygraphs will use the range of the data plus some padding to set the range of the y-axis. If this option is set, the y-axis will always include zero, typically as the lowest value. This can be used to avoid exaggerating the variance in the data.
939ecc46 555 <div class="tests">Tests: <a href="tests/no-range.html">no-range</a> <a href="tests/numeric-gviz.html">numeric-gviz</a> <a href="tests/small-range-zero.html">small-range-zero</a> </div>
dde90a16 556 </td>
15c966e0
AK
557 </tr>
558 <tr>
559 <td><strong>rollPeriod</strong></td>
8c851a1b 560 <td><code>integer &gt;= 1</code></td>
15c966e0 561 <td><code>1</code></td>
dde90a16 562 <td>Number of days over which to average data. Discussed extensively above.
939ecc46 563 <div class="tests">Tests: <a href="tests/demo.html">demo</a> <a href="tests/two-series.html">two-series</a> <a href="tests/noise.html">noise</a> </div>
dde90a16 564 </td>
15c966e0
AK
565 </tr>
566 <tr>
567 <td><strong>showRoller</strong></td>
568 <td><code>boolean</code></td>
569 <td><code>false</code></td>
dde90a16 570 <td>If the rolling average period text box should be shown.
1bc2103a 571 <div class="tests">Tests: <a href="tests/callback.html">callback</a> <a href="tests/crosshair.html">crosshair</a> <a href="tests/fractions.html">fractions</a> <a href="tests/isolated-points.html">isolated-points</a> <a href="tests/numeric-gviz.html">numeric-gviz</a> <a href="tests/underlay-callback.html">underlay-callback</a> <a href="tests/highlighted-region.html">highlighted-region</a></div>
dde90a16 572 </td>
15c966e0
AK
573 </tr>
574 <tr>
575 <td><strong>colors</strong></td>
576 <td><code>['red', '#00FF00']</code></td>
577 <td><code></code></td>
dde90a16 578 <td>List of colors for the data series. These can be of the form "#AABBCC" or "rgb(255,100,200)" or "yellow", etc. If not specified, equally-spaced points around a color wheel are used.
939ecc46 579 <div class="tests">Tests: <a href="tests/color-visibility.html">color-visibility</a> <a href="tests/demo.html">demo</a> </div>
dde90a16 580 </td>
15c966e0
AK
581 </tr>
582 <tr>
8c851a1b
DV
583 <td><strong>fillGraph</strong></td>
584 <td><code>boolean<br/></code></td>
f3975624 585 <td><code>false</code></td>
8c851a1b 586 <td>Should the area underneath the graph be filled? This option is not
dde90a16 587 compatible with error bars.
939ecc46 588 <div class="tests">Tests: <a href="tests/fillGraph.html">fillGraph</a> </div>
dde90a16 589 </td>
8c851a1b
DV
590 </tr>
591 <tr>
0c75dc72
DV
592 <td><strong>visibility</strong></td>
593 <td><code>Array of booleans<br/></code></td>
594 <td><code>[true, true, ...]</code></td>
595 <td>Which series should initially be visible? Once the Dygraph has
596 been constructed, you can access and modify the visibility of each
597 series using the <code>visibility</code> and
dde90a16 598 <code>setVisibility</code> methods.
939ecc46 599 <div class="tests">Tests: <a href="tests/visibility.html">visibility</a> <a href="tests/color-visibility.html">color-visibility</a> </div>
0c75dc72
DV
600 </td>
601 </tr>
602 <tr>
15c966e0
AK
603 <td><strong>colorSaturation</strong></td>
604 <td><code>0.0 - 1.0</code></td>
605 <td><code>1.0</code></td>
dde90a16 606 <td>If <strong>colors</strong> is not specified, saturation of the automatically-generated data series colors.
bf5b5f4d 607 <div class="tests">Tests: <font color=red>none</font></div>
dde90a16 608 </td>
15c966e0
AK
609 </tr>
610 <tr>
611 <td><strong>colorValue</strong></td>
612 <td><code>float (0.0 &mdash; 1.0)</code></td>
613 <td><code>1.0</code></td>
dde90a16 614 <td>If colors is not specified, value of the data series colors, as in hue/saturation/value. (0.0-1.0, default 0.5)
bf5b5f4d 615 <div class="tests">Tests: <font color=red>none</font></div>
dde90a16 616 </td>
15c966e0
AK
617 </tr>
618 <tr>
619 <td><strong>clickCallback</strong></td>
620 <td><code>function(e, date){<br>&nbsp;&nbsp;&nbsp;&nbsp;alert(date);<br>}</code></td>
621 <td><code>null</code></td>
dde90a16 622 <td>A function to call when a data point is clicked. The function should take two arguments, the event object for the click and the date that was clicked. (default null)
939ecc46 623 <div class="tests">Tests: <a href="tests/callback.html">callback</a> </div>
dde90a16 624 </td>
15c966e0
AK
625 </tr>
626 <tr>
627 <td><strong>zoomCallback</strong></td>
5ed061d6 628 <td><code>function(minDate,<br/>maxDate,<br/>minValue,<br/>maxValue){}</code></td>
15c966e0 629 <td><code>null</code></td>
5ed061d6
RK
630 <td>A function to call when the zoom window is changed (either by zooming in or out). minDate and maxDate are milliseconds since epoch. minValue and maxValue are y-axis range values.
631 <div class="tests">Tests: <a href="tests/callback.html">callback</a> <a href="tests/zoom.html">zoom</a></div>
dde90a16 632 </td>
15c966e0
AK
633 </tr>
634 <tr>
635 <td><strong>strokeWidth</strong></td>
636 <td><code>integer</code></td>
637 <td><code>1</code></td>
dde90a16 638 <td>Width of the data lines. This can be used to increase the contrast or some graphs.
bf5b5f4d 639 <div class="tests">Tests: <font color=red>none</font></div>
dde90a16 640 </td>
15c966e0
AK
641 </tr>
642 <tr>
643 <td><strong>dateWindow</strong></td>
644 <td><code>[<br>&nbsp;&nbsp;Date.parse('2006-01-01'),<br>&nbsp;&nbsp;(new Date()).valueOf()<br>]</code></td>
0c75dc72 645 <td rowspan="2"><code>Full range of the<br/> input is shown</code></td>
dde90a16 646 <td>Initially zoom in on a section of the graph. Is of the form [earliest, latest], where earliest/latest are milliseconds since epoch.
939ecc46 647 <div class="tests">Tests: <a href="tests/dateWindow.html">dateWindow</a> <a href="tests/link-interaction.html">link-interaction</a> </div>
dde90a16 648 </td>
15c966e0
AK
649 </tr>
650 <tr>
651 <td><strong>valueRange</strong></td>
652 <td><code>[10, 110]</code></td>
dde90a16 653 <td>Explicitly set the vertical range of the graph to [low, high].
bf5b5f4d 654 <div class="tests">Tests: <font color=red>none</font></div>
dde90a16 655 </td>
15c966e0
AK
656 </tr>
657 <tr>
658 <td><strong>labelsSeparateLines</strong></td>
659 <td><code>boolean</code></td>
660 <td><code>false</code></td>
dde90a16 661 <td>Put <code>&lt;br/&gt;</code> between lines in the label string. Often used in conjunction with <strong>labelsDiv</strong>.
939ecc46 662 <div class="tests">Tests: <a href="tests/customLabel.html">customLabel</a> <a href="tests/demo.html">demo</a> </div>
dde90a16 663 </td>
15c966e0
AK
664 </tr>
665 <tr>
666 <td><strong>labelsDiv</strong></td>
52fe05c1 667 <td><code style="font-size: small">document.getElementById('foo')</code><br/>or<br/><code>'foo'</code></td>
15c966e0 668 <td><code>null</code></td>
52fe05c1
SJ
669 <td style="vertical-align:top">Show data labels in an external div, rather than on the graph. This value can either be a div element or a div id.
670 <div class="tests">Tests: <a href="tests/label-div.html">label-div</a> </div>
671 </td>
672 </tr>
673 <tr>
674 <td><strong>labelsShowZeroValues</strong></td>
675 <td><code>boolean</code></td>
676 <td><code>true</code></td>
677 <td>Show zero value labels in the labelsDiv.
678 <div class="tests">Tests: <a href="tests/label-div.html">label-div</a> </div>
dde90a16 679 </td>
15c966e0
AK
680 </tr>
681 <tr>
682 <td><strong>labelsKMB</strong></td>
683 <td><code>true</code></td>
684 <td><code>false</code></td>
dde90a16 685 <td>Show K/M/B for thousands/millions/billions on y-axis.
939ecc46 686 <div class="tests">Tests: <a href="tests/demo.html">demo</a> <a href="tests/labelsKMB.html">labelsKMB</a> <a href="tests/no-range.html">no-range</a> </div>
dde90a16 687 </td>
15c966e0
AK
688 </tr>
689 <tr>
65914f5f
DV
690 <td><strong>labelsKMG2</strong></td>
691 <td><code>true</code></td>
692 <td><code>false</code></td>
693 <td>Show k/M/G for kilo/Mega/Giga on y-axis. This is different than
dde90a16 694 <code>labelsKMB</code> in that it uses base 2, not 10.
939ecc46 695 <div class="tests">Tests: <a href="tests/labelsKMB.html">labelsKMB</a> </div>
dde90a16 696 </td>
65914f5f
DV
697 </tr>
698 <tr>
15c966e0
AK
699 <td><strong>labelsDivWidth</strong></td>
700 <td><code>250</code></td>
701 <td><code></code></td>
dde90a16 702 <td>Width (in pixels) of the div which shows information on the currently-highlighted points.
939ecc46 703 <div class="tests">Tests: <a href="tests/customLabel.html">customLabel</a> </div>
dde90a16 704 </td>
15c966e0
AK
705 </tr>
706 <tr>
707 <td><strong>labelsDivStyles</strong></td>
708 <td><code>{}</code></td>
709 <td><code>null</code></td>
dde90a16 710 <td>Additional styles to apply to the currently-highlighted points div. For example, { 'font-weight': 'bold' } will make the labels bold.
939ecc46 711 <div class="tests">Tests: <a href="tests/border.html">border</a> <a href="tests/customLabel.html">customLabel</a> </div>
dde90a16 712 </td>
15c966e0
AK
713 </tr>
714 <tr>
715 <td><strong>highlightCircleSize</strong></td>
716 <td><code>integer</code></td>
717 <td><code>3</code></td>
dde90a16 718 <td>The size in pixels of the dot drawn over highlighted points.
939ecc46 719 <div class="tests">Tests: <a href="tests/grid_dot.html">grid_dot</a> </div>
dde90a16 720 </td>
15c966e0
AK
721 </tr>
722 <tr>
723 <td><strong>drawPoints</strong></td>
724 <td><code>boolean</code></td>
725 <td><code>false</code></td>
dde90a16 726 <td>Draw a small dot at each point, in addition to a line going through the point. This makes the individual data points easier to see, but can increase visual clutter in the chart.
939ecc46 727 <div class="tests">Tests: <a href="tests/draw-points.html">draw-points</a> </div>
dde90a16 728 </td>
15c966e0
AK
729 </tr>
730 <tr>
731 <td><strong>pointSize</strong></td>
732 <td><code>interger</code></td>
733 <td><code>1</code></td>
dde90a16 734 <td>The size of the dot to draw on each point in pixels (see drawPoints). A dot is always drawn when a point is "isolated", i.e. there is a missing point on either side of it. This also controls the size of those dots.
bf5b5f4d 735 <div class="tests">Tests: <font color=red>none</font></div>
dde90a16 736 </td>
15c966e0
AK
737 </tr>
738 <tr>
739 <td><strong>pixelsPerXLabel</strong></td>
740 <td rowspan="2"><code>integer</code></td>
741 <td><code>60</code></td>
dde90a16 742 <td rowspan="2">Number of pixels to require between each x- and y-label. Larger values will yield a sparser axis with fewer ticks.
939ecc46 743 <div class="tests">Tests: <a href="tests/spacing.html">spacing</a> </div>
dde90a16 744 </td>
15c966e0
AK
745 </tr>
746 <tr>
747 <td><strong>pixelsPerYLabel</strong></td>
748 <td><code>30</code></td>
749 </tr>
750 <tr>
751 <td><strong>xAxisLabelWidth</strong></td>
752 <td rowspan="2"><code>integer</code></td>
753 <td><code></code></td>
dde90a16 754 <td rowspan="2">Width (in pixels) of the x- and y-axis labels.
939ecc46 755 <div class="tests">Tests: <a href="tests/customLabel.html">customLabel</a> </div>
dde90a16 756 </td>
15c966e0
AK
757 </tr>
758 <tr>
759 <td><strong>yAxisLabelWidth</strong></td>
760 <td><code></code></td>
761 </tr>
762 <tr>
763 <td><strong>axisLabelFontSize</strong></td>
764 <td><code>integer</code></td>
765 <td><code>14</code></td>
dde90a16 766 <td>Size of the font (in pixels) to use in the axis labels, both x- and y-axis.
bf5b5f4d 767 <div class="tests">Tests: <font color=red>none</font></div>
dde90a16 768 </td>
15c966e0
AK
769 </tr>
770 <tr>
31eddad3
AV
771 <td><strong>xAxisLabelFormatter</strong></td>
772 <td><code>function(date, granularity)</code></td>
773 <td><code>Dygraph.dateAxisFormatter</code></td>
774 <td>Function to call to format values along the x axis.
775 <div class="tests">Tests: <a href="tests/x-axis-formatter.html">xAxisLabelFormatter</a></div>
776 </td>
84fc6aa7
NN
777 </tr>
778 <tr>
779 <td><strong>yAxisLabelFormatter</strong></td>
780 <td><code>function(x)</code></td>
781 <td><code>yValueFormatter</code></td>
782 <td>
783 Function used to format values along the Y axis. By default it uses the same as the <code>yValueFormatter</code> unless specified.
784 <div class="tests">Tests: <a href="tests/y-axis-formatter.html">yAxisLabelFormatter</a></div>
785 </td>
786 </tr>
31eddad3 787 <tr>
15c966e0
AK
788 <td><strong>rightGap</strong></td>
789 <td><code>integer</code></td>
790 <td><code></code></td>
dde90a16 791 <td>Number of pixels to leave blank at the right edge of the Dygraph. This makes it easier to highlight the right-most data point.
bf5b5f4d 792 <div class="tests">Tests: <font color=red>none</font></div>
dde90a16 793 </td>
15c966e0
AK
794 </tr>
795 <tr>
796 <td><strong>errorBars</strong></td>
797 <td><code>boolean</code></td>
798 <td><code>false</code></td>
dde90a16 799 <td>Does the data contain standard deviations? Setting this to true alters the input format (see above).
939ecc46 800 <div class="tests">Tests: <a href="tests/noise.html">noise</a> <a href="tests/customLabel.html">customLabel</a> <a href="tests/draw-points.html">draw-points</a> <a href="tests/fillGraph.html">fillGraph</a> <a href="tests/fractions.html">fractions</a> </div>
dde90a16 801 </td>
15c966e0
AK
802 </tr>
803 <tr>
804 <td><strong>sigma</strong></td>
805 <td><code>integer</code></td>
806 <td><code></code></td>
dde90a16 807 <td>When errorBars is set, shade this many standard deviations above/below each point.
bf5b5f4d 808 <div class="tests">Tests: <font color=red>none</font></div>
dde90a16 809 </td>
15c966e0
AK
810 </tr>
811 <tr>
812 <td><strong>fractions</strong></td>
813 <td><code>boolean</code></td>
814 <td><code>false</code></td>
dde90a16 815 <td>When set, attempt to parse each cell in the CSV file as "a/b", where a and b are integers. The ratio will be plotted. This allows computation of Wilson confidence intervals (see below).
939ecc46 816 <div class="tests">Tests: <a href="tests/fractions.html">fractions</a> </div>
dde90a16 817 </td>
15c966e0
AK
818 </tr>
819 <tr>
820 <td><strong>wilsonInterval</strong></td>
821 <td><code>boolean</code></td>
822 <td><code>true</code></td>
dde90a16 823 <td>Use in conjunction with the "fractions" option. Instead of plotting +/- N standard deviations, dygraphs will compute a Wilson confidence interval and plot that. This has more reasonable behavior for ratios close to 0 or 1.
bf5b5f4d 824 <div class="tests">Tests: <font color=red>none</font></div>
dde90a16 825 </td>
15c966e0
AK
826 </tr>
827 <tr>
828 <td><strong>customBars</strong></td>
829 <td><code>boolean</code></td>
830 <td><code>false</code></td>
dde90a16 831 <td>When set, parse each CSV cell as "low;middle;high". Error bars will be drawn for each point between low and high, with the series itself going through middle.
939ecc46 832 <div class="tests">Tests: <a href="tests/custom-bars.html">custom-bars</a> <a href="tests/zero-series.html">zero-series</a> </div>
dde90a16 833 </td>
15c966e0 834 </tr>
85cda1ca
DV
835
836 <tr>
837 <td><strong>drawCallback</strong></td>
838 <td><code>function(dygraph, is_initial)</code></td>
839 <td><code>null</code></td>
840 <td>When set, this callback gets called every time the dygraph is drawn. This includes the initial draw, after zooming and repeatedly while panning. The first parameter is the dygraph being drawn. The second is a boolean value indicating whether this is the initial draw.
2322a4ca 841 <div class="tests">Tests: <a href="tests/callback.html">callback</a> <a href="tests/synchronize.html">synchronize</a> </div>
85cda1ca
DV
842 </td>
843 </tr>
844
845 <tr>
846 <td><strong>gridLineColor</strong></td>
847 <td><code>red, blue</code></td>
848 <td><code>rgb(128,128,128)</code></td>
849 <td>The color of the gridlines.
2322a4ca 850 <div class="tests">Tests: <a href="tests/grid_dot.html">grid_dot</a> </div>
85cda1ca
DV
851 </td>
852 </tr>
853
854 <tr>
855 <td><strong>highlightCallback</strong></td>
856 <td><code>function(event, x, points)</code></td>
a4c6a67c 857 <td><code>null</code></td>
85cda1ca 858 <td>When set, this callback gets called every time a new point is highlighted. The parameters are the JavaScript mousemove event, the x-coordinate of the highlighted points and an array of highlighted points: <code>[ {name: 'series', yval: y-value}, &hellip; ]</code>
2322a4ca 859 <div class="tests">Tests: <a href="tests/callback.html">callback</a> <a href="tests/crosshair.html">crosshair</a> </div>
a4c6a67c
AV
860 </td>
861 </tr>
862
863 <tr>
864 <td><strong>unhighlightCallback</strong></td>
865 <td><code>function(event)</code></td>
866 <td><code>null</code></td>
867 <td>When set, this callback gets called every time the user stops highlighting any point by mousing out of the graph. The parameter is the mouseout event.
868 <div class="tests">Tests: <a href="tests/callback.html">callback</a> <a href="tests/crosshair.html">crosshair</a> </div>
85cda1ca
DV
869 </td>
870 </tr>
871
872 <tr>
873 <td><strong>strokeWidth</strong></td>
874 <td><code>0.5, 2.0</code></td>
875 <td><code>1.0</code></td>
876 <td>The width of the lines connecting data points.
2322a4ca 877 <div class="tests">Tests: <a href="tests/grid_dot.html">grid_dot</a> </div>
85cda1ca
DV
878 </td>
879 </tr>
880
881 <tr>
882 <td><strong>width</strong></td>
883 <td rowspan="2"><code>integer</code></td>
884 <td><code>480</code></td>
885 <td rowspan="2">Width/Height (in pixels) of the chart. If the container div has been explicitly sized, these attributes will be ignored.
2322a4ca 886 <div class="tests">Tests: <a href="tests/demo.html">demo</a> <a href="tests/link-interaction.html">link-interaction</a> <a href="tests/no-range.html">no-range</a> </div>
85cda1ca
DV
887 </td>
888 </tr>
889 <tr>
890 <td><strong>height</strong></td>
891 <td><code>320</code></td>
892 </tr>
893
e17f6ca5
NN
894 <tr>
895 <td><strong>stepPlot</strong></td>
896 <td><code>boolean</code></td>
897 <td><code>false</code></td>
898 <td>
899 When set, display the graph as a step plot instead of a line plot.
900 <div class="tests">Tests: <a href="tests/steps.html">steps</a></div>
901 </td>
902 </tr>
903
84fc6aa7
NN
904 <tr>
905 <td><strong>xValueFormatter</strong></td>
906 <td><code>function(x)</code></td>
907 <td></td>
908 <td>
909 Function to provide a custom display format the X value for mouseover.
910 </td>
911 </tr>
912
913 <tr>
914 <td><strong>yValueFormatter</strong></td>
915 <td><code>function(x)</code></td>
916 <td>(Round to 2 decimal places)</td>
917 <td>
918 Function to provide a custom display format for the Y value for mouseover.
919 <div class="tests">Tests: <a href="tests/y-axis-formatter.html">yAxisLabelFormatter</a></div>
920 </td>
921 </tr>
922
00c281d4
NN
923 <tr>
924 <td><strong>avoidMinZero</strong></td>
925 <td><code>boolean</code></td>
926 <td><code>false</code></td>
927 <td>
928 When set, the heuristic that fixes the Y axis at zero for a data set with the minimum Y value of zero is disabled.
929 This is particularly useful for data sets that contain many zero values, especially for step plots which may otherwise have lines not visible running along the bottom axis.
930 <div class="tests">Tests: <a href="tests/avoidMinZero.html">avoidMinZero</a></div>
931 </td>
932 </tr>
933
15c966e0 934 </tbody>
68f9bed3
AK
935 </table>
936
937 <h2>Common Gotchas</h2>
938
939 <p>Here are a few problems that I've frequently run into while using the dygraphs library.</p>
940
941 <ul>
dde90a16 942 <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
943 <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>
944 <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>
945 <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>
946 <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>
947 <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
948 </ul>
949
71ac4733
AV
950 <h2 id="gwt">GWT Compatibility</h2>
951 <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>
952
953<pre>
954&lt;inherits name=&quot;org.danvk.dygraphs&quot;/&gt;
955</pre>
956
957 <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>
958
959<pre>
fb369f35 960 public static native JavaScriptObject drawDygraph(Element element, DataTable dataTable, double minY, double maxY) /*-{
71ac4733
AV
961 var chart = new $wnd.Dygraph.GVizChart(element);
962 chart.draw(dataTable,
963 {
964 valueRange: [minY, maxY]
965 });
966 return chart;
967 }-*/;
968</pre>
969
68f9bed3 970 <h2 id="policy">Data Policy</h2>
15c966e0 971 <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 972
68f9bed3 973 <p style="font-size:0.8em">Created May 9, 2008 by <a href=mailto:danvdk@gmail.com>Dan Vanderkam</a></p>
15c966e0 974 </div>
fe57a69b 975
a9df40de 976
15c966e0
AK
977 <!-- Google Analytics -->
978 <script src="http://www.google-analytics.com/urchin.js" type="text/javascript"></script>
979 <script type="text/javascript">_uacct = "UA-769809-1";urchinTracker();</script>
078d1d29 980</body>
65914f5f 981</html>