docs/index.html

   1 <!DOCTYPE html>
   2 <html>
   3   <head>
   4     <meta http-equiv="X-UA-Compatible" content="IE=EmulateIE7; IE=EmulateIE9">
   5     <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
   6
   7     <title>dygraphs JavaScript Visualization Library</title>
   8     <!--[if IE]>
   9       <script type="text/javascript" src="excanvas.js"></script>
  10     <![endif]-->
  11     <script type="text/javascript" src="dygraph-combined.js"></script>
  12     <link rel="stylesheet" href="style.css">
  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>
  25   </head>
  26   <body>
  27     <a href="http://github.com/danvk/dygraphs"><img style="position: absolute; top: 0; right: 0; border: 0; z-index: 1;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_green_007200.png" alt="Fork me on GitHub"></a>
  28
  29     <div id="nav">
  30       <h2>Documentation</h2>
  31       <ul>
  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>
  38         <li><a href="#gwt">GWT Compatibility</a></li>
  39         <li><a href="#policy">Data Policy</a></li>
  40         <li><a href="options.html">Options Reference</a></li>
  41         <li><a href="jsdoc/symbols/Dygraph.html">JSDoc Reference</a></li>
  42         <li><a href="data.html">Data Formats</a></li>
  43         <li><a href="annotations.html">Annotations</a></li>
  44       </ul>
  45
  46       <h2>Project</h2>
  47       <ul>
  48         <li><a href="http://blog.dygraphs.com/">Blog</a></li>
  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>
  52         <li><a href="changes.html">Contribute a change</a></li>
  53         <li><a href="mailto:dygraphs-users [at] googlegroups.com">Contact</a></li>
  54       </ul>
  55
  56       <h2>Demos/Usage</h2>
  57       <ul>
  58         <li><a href="#users">Known Users</a></li>
  59         <hr/>
  60         <li><span style="color: red;">New!</span> <a href="gallery/">(browse gallery)</a></li>
  61         <li><a href="tests/">(browse demos)</a></li>
  62         <li><a href="tests/demo.html">Basic Demo</a></li>
  63         <li><a href="tests/gviz.html">GViz Demo</a></li>
  64         <li><a href="tests/plotter.html">Equation Plotter</a></li>
  65         <li><a href="tests/perf.html">Performance Test</a></li>
  66         <li><a href="tests/annotation.html">Annotations</a></li>
  67         <li><a href="tests/annotation-gviz.html">Annotations (GViz)</a></li>
  68         <li><a href="tests/fillGraph.html">Filled Chart</a></li>
  69         <li><a href="tests/perf.html">Fractions</a></li>
  70         <li><a href="tests/visibility.html">Visibility</a></li>
  71         <li><a href="tests/label-div.html">Labels in a DIV</a></li>
  72         <li><a href="tests/numeric-axis.html">Numeric Axis</a></li>
  73         <li><a href="tests/draw-points.html">Dotted Points</a></li>
  74         <li><a href="tests/native-format.html">Native Format</a></li>
  75         <li><a href="tests/grid_dot.html">Crazy Styles</a></li>
  76         <li><a href="tests/spacing.html">Tick spacing</a></li>
  77         <li><a href="tests/callback.html">Callbacks</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/highlighted-region.html">Custom Underlay / background</a></li>
  87         <li><a href="tests/zoom.html">Tests for zoom operations</a></li>
  88         <li><a href="tests/logscale.html">Log scale tests</a></li>
  89       </ul>
  90     </div>
  91
  92     <div id="content">
  93       <h1>dygraphs JavaScript Visualization Library</h1>
  94
  95       <p><a href="http://github.com/danvk/dygraphs">http://github.com/danvk/dygraphs</a></p>
  96       <p>For help, <a
  97         href="http://stackoverflow.com/questions/ask?tags=dygraphs+javascript">ask
  98         a question</a> on StackOverflow. You may also be interested in the <a
  99         href="http://blog.dygraphs.com/">blog</a>, <a
 100         href="http://groups.google.com/group/dygraphs-users">mailing list</a>, <a
 101         href="tests/">demos</a> and <a
 102         href="http://code.google.com/p/dygraphs/issues/">open issues</a>.</p>
 103
 104       <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>
 105
 106       <h3 id="demo">A demo is worth a thousand words:</h3>
 107
 108       <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>
 109
 110       <div id="demodiv" style="width:800px; height:320px;"></div>
 111       <script type="text/javascript">
 112         g = new Dygraph(
 113           document.getElementById("demodiv"),
 114           "ny-vs-sf.txt",
 115           {
 116             rollPeriod: 14,
 117             showRoller: true,
 118             customBars: true,
 119             title: 'Daily Temperatures in New York vs. San Francisco',
 120             ylabel: 'Temperature (F)',
 121             legend: 'always',
 122             labelsDivStyles: { 'textAlign': 'right' }
 123           }
 124         );
 125       </script>
 126
 127       <h4>Some things to notice:</h4>
 128       <ul>
 129         <li>There's less seasonal temperature variation in SF than in NY.</li>
 130         <li>The difference is about 15&deg; F for SF vs. 50&deg; F for NY.</li>
 131         <li>The daily data (set rolling period to 1) is quite noisy and hides this conclusion.</li>
 132         <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>
 133         <li>There's a gap in the data for SF, when the weather station was down (zoom into October 2007 to see it).</li>
 134         <li>The bands around each point indicate average highs and lows.</li>
 135         <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>
 136       </ul>
 137
 138       <p>dygraphs allows the user to explore the data and discover these facts.</p>
 139
 140       <p>For more demos, browse the dygraph <a href="tests/">tests</a>
 141       directory. To see other people who are using dygraphs, check out the <a
 142       href="#users">known users</a>.</p>
 143
 144       <h3>Features</h3>
 145       <p>Some of the features of dygraphs:</p>
 146       <ul>
 147         <li>Plots time series without using an external server or Flash</li>
 148         <li>Works in Internet Explorer (using excanvas)</li>
 149         <li>Lightweight (69kb) and responsive</li>
 150         <li>Displays values on mouseover, making interaction easily discoverable</li>
 151         <li>Supports error bands around data series</li>
 152         <li>Interactive zoom</li>
 153         <li>Displays Annotations on the chart</li>
 154         <li>Adjustable averaging period</li>
 155         <li>Can intelligently chart fractions</li>
 156         <li>Customizable click-through actions</li>
 157         <li>Compatible with the Google Visualization API</li>
 158         <li>Intelligent defaults make it easy to use</li>
 159       </ul>
 160
 161       <h2 id="usage">Usage</h2>
 162
 163       <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>
 164
 165       <p>Here's a basic example to get things started:</p>
 166
 167       <div class="example" style="clear:both;">
 168         <div class="codeblock" style="float:left;width:400px;">
 169           <h3 style="text-align:center">HTML</h3>
 170           <code>
 171   <pre>
 172 &lt;html&gt;
 173 &lt;head&gt;
 174 &lt;script type=&quot;text/javascript&quot;
 175   src=&quot;dygraph-combined.js&quot;&gt;&lt;/script&gt;
 176 &lt;/head&gt;
 177 &lt;body&gt;
 178 &lt;div id=&quot;graphdiv&quot;&gt;&lt;/div&gt;
 179 &lt;script type=&quot;text/javascript&quot;&gt;
 180   g = new Dygraph(
 181
 182     // containing div
 183     document.getElementById(&quot;graphdiv&quot;),
 184
 185     // CSV or path to a CSV file.
 186     &quot;Date,Temperature\n&quot; +
 187     &quot;2008-05-07,75\n&quot; +
 188     &quot;2008-05-08,70\n&quot; +
 189     &quot;2008-05-09,80\n&quot;
 190
 191   );
 192 &lt;/script&gt;
 193 &lt;/body&gt;
 194 &lt;/html&gt;
 195 </pre>
 196           </code>
 197         </div>
 198         <div class="codeoutput" style="float:left;">
 199           <h3 style="text-align:center">OUTPUT</h3>
 200           <div id="graphdiv"></div>
 201           <script type="text/javascript">
 202             g = new Dygraph(
 203
 204               // containing div
 205               document.getElementById("graphdiv"),
 206
 207               // CSV or path to a CSV file.
 208               "Date,Temperature\n" +
 209               "2008-05-07,75\n" +
 210               "2008-05-08,70\n" +
 211               "2008-05-09,80\n"
 212             );
 213           </script>
 214         </div>
 215       </div>
 216
 217       <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>
 218
 219       <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>
 220
 221       <div class="example" style="clear:both;">
 222         <div class="codeblock" style="float:left;width:400px;">
 223           <h3 style="text-align:center">HTML</h3>
 224           <code>
 225 <pre>
 226 &lt;html&gt;
 227 &lt;head&gt;
 228 &lt;script type=&quot;text/javascript&quot;
 229   src=&quot;dygraph-combined.js&quot;&gt;&lt;/script&gt;
 230 &lt;/head&gt;
 231 &lt;body&gt;
 232 &lt;div id=&quot;graphdiv2&quot;
 233   style=&quot;width:500px; height:300px;&quot;&gt;&lt;/div&gt;
 234 &lt;script type=&quot;text/javascript&quot;&gt;
 235   g2 = new Dygraph(
 236     document.getElementById(&quot;graphdiv2&quot;),
 237     &quot;temperatures.csv&quot;, // path to CSV file
 238     {}          // options
 239   );
 240 &lt;/script&gt;
 241 &lt;/body&gt;
 242 &lt;/html&gt;
 243 </pre>
 244           </code>
 245         </div>
 246         <div class="codeoutput" style="float:left;">
 247           <h3 style="text-align:center">OUTPUT</h3>
 248           <div id="graphdiv2" style="width:500px; height:300px;"></div>
 249           <script type="text/javascript">
 250             g2 = new Dygraph(
 251               document.getElementById("graphdiv2"),
 252               "temperatures.csv",
 253               {}
 254             );
 255           </script>
 256         </div>
 257       </div>
 258
 259       <p style="clear:both;">The file used is <code><a href="temperatures.csv">temperatures.csv</a></code>.</p>
 260
 261       <p>There are a few things to note here:</p>
 262
 263       <ul>
 264         <li>The Dygraph sent off an XHR to get the temperatures.csv file.</li>
 265         <li>The labels were taken from the first line of <code>temperatures.csv</code>, which is <code>Date,High,Low</code>.</li>
 266         <li>The Dygraph automatically chose two different, easily-distinguishable colors for the two data series.</li>
 267         <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>
 268         <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>
 269         <li>The data is very spiky. A moving average would be easier to interpret.</li>
 270       </ul>
 271
 272       <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>
 273
 274       <div class="example" style="clear:both;">
 275         <div class="codeblock" style="float:left;width:400px;">
 276           <h3 style="text-align:center">HTML</h3>
 277           <code>
 278 <pre>
 279 &lt;html&gt;
 280 &lt;head&gt;
 281 &lt;script type=&quot;text/javascript&quot;
 282   src=&quot;dygraph-combined.js&quot;&gt;&lt;/script&gt;
 283 &lt;/head&gt;
 284 &lt;body&gt;
 285 &lt;div id=&quot;graphdiv3&quot;
 286   style=&quot;width:500px; height:300px;&quot;&gt;&lt;/div&gt;
 287 &lt;script type=&quot;text/javascript&quot;&gt;
 288   g3 = new Dygraph(
 289     document.getElementById(&quot;graphdiv3&quot;),
 290     &quot;temperatures.csv&quot;,
 291     {
 292       rollPeriod: 7,
 293       showRoller: true
 294     }
 295   );
 296 &lt;/script&gt;
 297 &lt;/body&gt;
 298 &lt;/html&gt;
 299 </pre>
 300           </code>
 301         </div>
 302         <div class="codeoutput" style="float:left;">
 303           <h3 style="text-align:center">OUTPUT</h3>
 304           <div id="graphdiv3" style="width:500px; height:300px;"></div>
 305           <script type="text/javascript">
 306             g3 = new Dygraph(
 307               document.getElementById("graphdiv3"),
 308               "temperatures.csv",
 309               {
 310                 rollPeriod: 7,
 311                 showRoller: true
 312               }
 313             );
 314           </script>
 315         </div>
 316       </div>
 317
 318       <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>
 319
 320       <h2>Error Bars</h2>
 321
 322       <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>
 323
 324       <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>
 325
 326       <div class="example" style="clear:both;">
 327         <div class="codeblock" style="float:left;width:400px;">
 328           <h3 style="text-align:center">HTML</h3>
 329           <code>
 330 <pre>
 331 &lt;html&gt;
 332 &lt;head&gt;
 333 &lt;script type=&quot;text/javascript&quot;
 334   src=&quot;combined.js&quot;&gt;&lt;/script&gt;
 335 &lt;/head&gt;
 336 &lt;body&gt;
 337 &lt;div id=&quot;graphdiv4&quot;
 338   style=&quot;width:480px; height:320px;&quot;&gt;&lt;/div&gt;
 339 &lt;script type=&quot;text/javascript&quot;&gt;
 340   g4 = new Dygraph(
 341     document.getElementById(&quot;graphdiv4&quot;),
 342     &quot;twonormals.csv&quot;,
 343     {
 344       rollPeriod: 7,
 345       showRoller: true,
 346       errorBars: true,
 347       valueRange: [50,125]
 348     }
 349   );
 350 &lt;/script&gt;
 351 &lt;/body&gt;
 352 &lt;/html&gt;
 353 </pre>
 354           </code>
 355         </div>
 356         <div class="codeoutput" style="float:left;">
 357           <h3 style="text-align:center">OUTPUT</h3>
 358           <div id="graphdiv4" style="width:480px; height:320px;"></div>
 359           <script type="text/javascript">
 360             g4 = new Dygraph(
 361               document.getElementById("graphdiv4"),
 362               "twonormals.csv",
 363               {
 364                 rollPeriod: 7,
 365                 showRoller: true,
 366                 errorBars: true,
 367                 valueRange: [50,125]
 368               }
 369             );
 370           </script>
 371         </div>
 372       </div>
 373
 374       <p style="clear:both;">Things to note here:</p>
 375
 376       <ul>
 377         <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>
 378         <li>The first line of the CSV file doesn't mention the error columns. In this case, it's just "Date,Series1,Series2".</li>
 379         <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>
 380         <li>The error bars are partially transparent. This can be seen when they overlap one another.</li>
 381       </ul>
 382
 383       <h2 id="ie">Internet Explorer Compatibility</h2>
 384
 385       <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>
 386
 387 <pre>
 388 &lt;!DOCTYPE html&gt;
 389 </pre>
 390
 391       <p>When IE9 is in HTML5 mode, dygraphs works just like in other modern browsers.</p>
 392
 393       <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>
 394
 395 <pre>
 396 &lt;!DOCTYPE html&gt;
 397 &lt;html&gt;
 398   &lt;head&gt;
 399     &lt;meta http-equiv="X-UA-Compatible" content="IE=EmulateIE7; IE=EmulateIE9"&gt;
 400     &lt;!--[if IE]&gt;&lt;script src="path/to/excanvas.js"&gt;&lt;/script&gt;&lt;![endif]--&gt;
 401   &lt;/head&gt;
 402 </pre>
 403
 404 <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. Note that the &lt;meta http-equiv&hellip;&gt; line must appear <i>first</i> in the &lt;head&gt; section for this to work properly.)</p>
 405
 406     <p>While VML emulation sounds like it would be slow, it works well in practice for most charts.</p>
 407
 408     <p>One common gotcha to look out for: make sure you don't have any trailing commas in parameter lists, e.g.</p>
 409
 410 <pre>
 411 new Dygraph(el, data, {
 412   showRoller: true,  // note trailing comma
 413 })</pre>
 414
 415     <p>Most browsers will ignore the trailing comma, but it will break under IE.</p>
 416
 417     <p>You may also need to delay instantiating any dygraphs until after the DOM
 418     content is ready, as there have been some <a
 419       href="https://groups.google.com/d/topic/dygraphs-users/qPX4Syx2kz8/discussion">reports</a>
 420     that excanvas won't work until this happens. If you're using jQuery, this
 421     means drawing your charts inside of a <code>$(function() { ... })</code>
 422     block.</p>
 423
 424     <h2 id="gviz">GViz Data</h2>
 425
 426     <p>The <a
 427       href="http://code.google.com/apis/visualization/documentation/index.html">Google
 428       Visualization API</a> provides a standard interface for describing data.
 429     Once you've specified your data using this API, you can plug in any
 430     GViz-compatible visualization. dygraphs is such a visualization. In
 431     particular, it can be used as a drop-in replacement for the
 432     AnnotatedTimeline visualization used on Google Finance and other sites. To
 433     see how this works, check out the <a href="tests/annotation-gviz.html">gviz
 434       annotation demo.</a></p>
 435
 436     <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>
 437
 438     <p>Here's an example of a published gviz gadget using dygraphs:</p>
 439
 440     <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>
 441
 442     <h2 id="baseball">Charting Fractions</h2>
 443
 444     <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>
 445
 446     <ul>
 447       <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>
 448       <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>
 449     </ul>
 450
 451     <p>Fortunately, dygraphs handles both of these for you! Here's a chart and the command that generated it:</p>
 452
 453     <div style="width:750px; text-align:center; font-weight: bold; font-size: 125%;">Batting Average for Ichiro Suzuki vs. Mariners (2004)</div>
 454     <div id="baseballdiv" style="width:750px; height:300px;"></div>
 455     <script type="text/javascript">
 456       new Dygraph(
 457         document.getElementById("baseballdiv"),
 458         "suzuki-mariners.txt",
 459         {
 460           fractions: true,
 461           errorBars: true,
 462           showRoller: true,
 463           rollPeriod: 15
 464         }
 465       );
 466     </script>
 467
 468     <p>Command:</p>
 469 <pre>
 470   new Dygraph(
 471     document.getElementById(&quot;baseballdiv&quot;),
 472     &quot;suzuki-mariners.txt&quot;,
 473     {
 474       fractions: true,
 475       errorBars: true,
 476       showRoller: true,
 477       rollPeriod: 15
 478     }
 479   );
 480 </pre>
 481
 482     <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>
 483
 484     <p>A couple things to notice about this chart:</p>
 485
 486     <ul>
 487       <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>
 488       <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>
 489       <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>
 490       <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>
 491     </ul>
 492
 493     <h2 id="stock">One last demo</h2>
 494
 495     <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>
 496
 497     <div id="dow_chart" style="width:750px; height:350px;"></div>
 498     <p><b>Display: </b>
 499     <input type=checkbox id=0 onClick="stockchange(this)" checked>
 500     <label for="0"> Nominal</label>
 501     <input type=checkbox id=1 onClick="stockchange(this)" checked>
 502     <label for="1"> Real</label>
 503     <input type=checkbox id=ann onClick="annotationschange(this)" checked>
 504     <label for="ann"> Annotations</label>
 505     </p>
 506
 507     <script type="text/javascript">
 508       var stock_annotations = [
 509         {
 510           series: "Real",
 511           x: "1929-08-15",
 512           shortText: "A",
 513           text: "1929 Stock Market Peak"
 514         },
 515         {
 516           series: "Nominal",
 517           x: "1987-08-15",
 518           shortText: "B",
 519           text: "1987 Crash"
 520         },
 521         {
 522           series: "Nominal",
 523           x: "1999-12-15",
 524           shortText: "C",
 525           text: "1999 (.com) Peak"
 526         },
 527         {
 528           series: "Nominal",
 529           x: "2007-10-15",
 530           shortText: "D",
 531           text: "All-Time Market Peak"
 532         }
 533       ];
 534
 535     // From http://www.econstats.com/eqty/eq_d_mi_3.csv
 536       stockchart = new Dygraph(
 537         document.getElementById('dow_chart'),
 538         "dow.txt",
 539         {
 540           showRoller: true,
 541           customBars: true,
 542           labelsKMB: true,
 543           drawCallback: function(g, is_initial) {
 544             if (!is_initial) return;
 545             g.setAnnotations( stock_annotations );
 546           }
 547         }
 548       );
 549
 550       function stockchange(el) {
 551         stockchart.setVisibility(el.id, el.checked);
 552       }
 553
 554       function annotationschange(el) {
 555         if (el.checked) {
 556           stockchart.setAnnotations(stock_annotations);
 557         } else {
 558           stockchart.setAnnotations([]);
 559         }
 560       }
 561     </script>
 562 <!--
 563
 564 Here is a script to regenerate the Dow Jones plot:
 565
 566 # Get unadjusted DJIA data in a nice format:
 567 curl -O http://www.econstats.com/eqty/eq_d_mi_3.csv
 568 sed '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
 569
 570 # Fetch and format the CPI data:
 571 curl '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
 572 sed '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
 573
 574 # Merge:
 575 join -t'     ' cpi-u.tsv monthly-djia.tsv > annotated-djia.tsv
 576 perl -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
 577
 578 -->
 579
 580     <h2 id="options">Other Options</h2>
 581
 582     <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>
 583
 584     <p>For a full list, see the <a href="options.html">Dygraphs Options Reference</a> page.</p>
 585
 586     <h2>Common Gotchas</h2>
 587
 588     <p>Here are a few problems that I've frequently run into while using the dygraphs library.</p>
 589
 590     <ul>
 591       <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>
 592       <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>
 593       <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>
 594       <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>
 595       <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>
 596       <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>
 597     </ul>
 598
 599     <h2 id="gwt">GWT Compatibility</h2>
 600     <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>
 601
 602 <pre>
 603 &lt;inherits name=&quot;org.danvk.dygraphs&quot;/&gt;
 604 </pre>
 605
 606     <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>
 607
 608 <pre>
 609 public static native JavaScriptObject drawDygraph(
 610     Element element, DataTable dataTable, double minY, double maxY) /*-{
 611   var chart = new $wnd.Dygraph.GVizChart(element);
 612   chart.draw(dataTable,
 613     {
 614       valueRange: [minY, maxY]
 615     });
 616   return chart;
 617 }-*/;
 618 </pre>
 619
 620     <a name="users" />
 621     <h2>Known Users</h2>
 622     <p>Since its public release in late 2009, dygraphs has found many users
 623     across the web. This is a small collection of the uses that we know about.
 624     If you're using dygraphs, please send <a
 625     href="mailto:dan@dygraphs.com">Dan</a> a link and he'll add it to this
 626     list.</p>
 627
 628     <p>dygraphs was originally developed at Google and has found wide use on
 629     internal dashboards and servers there. There are also a few uses of
 630     dygraphs on public Google products:</p>
 631
 632     <ul class='padded-list'>
 633     <li><a href="http://www.google.com/trends/correlate/search?e=id:20xKcnNqHrk&t=weekly">Google Correlate</a><br/>
 634     <span class="desc">Uses dygraphs for time series visualization. Mostly a standard configuration, with just a few tweaks to match Google style.</span></li>
 635
 636     <li><a href="http://www.google.com/trends/correlate/draw?p=us">Google Correlate - Search by Drawing</a><br/>
 637     <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>
 638
 639     <li><a href="https://www.google.com/latitude/b/0/history/manage">Google Latitude History Dashboard</a><br/>
 640     <span class="desc">Uses mouse interaction callbacks to synchronize time series points with markers on a Google Map.</span></li>
 641     </ul>
 642
 643     <p>dygraphs has also found use in other organizations:</p>
 644
 645     <ul class='padded-list'>
 646   <li><a
 647     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
 648     Space Weather Analysis System</a> (NASA)<br/>
 649   <span class="desc">&ldquo;We use [dygraphs] in the Integrated Space Weather
 650     Analysis System available from the Space Weather Laboratory at NASA Goddard
 651     Space Flight Center. It works quite well for time series data from various
 652     missions and simulations that we store.&rdquo;</span></li>
 653
 654
 655   <li><a href="http://www.eutelsat.fr">Eutelsat</a><br/>
 656   <span class="desc">&ldquo;Eutelsat uses dygraphs for charting spacecraft
 657     telemetry for a fleet of 25 geostationary satellites. The spacecraft
 658     engineers are very happy with it.  All satellite combined are producing
 659     about 200 millions unique data points per day so we really appreciate the
 660     excellent performance of dygraphs.&rdquo;</span></li>
 661
 662   <li><a href="http://www.10gen.com/mongodb-monitoring-service">10gen MongoDB
 663     Monitoring Service</a><br/>
 664   <span class="desc">A free monitoring service for MongoDB from 10gen (the
 665     creators of MongoDB). Used by thousands of servers and users. Makes use of
 666     <a href="tests/synchronize.html">synchronized charts</a> to display many
 667     quantities simultaneously.</span></li>
 668
 669   <li><a href="http://duckduckgo.com/traffic.html">Duck Duck Go Traffic Dashboard</a><br/>
 670   <span class="desc">DDG uses dygraphs to display a public chart of their daily traffic. They use annotations and the moving average features.</span></li>
 671
 672     <li><a href="http://toolserver.org/~dartar/moodbar/">Wikimedia Foundation - Moodbar data dashboard</a><br/>
 673     <span class="desc">dygraphs is used internally at Wikimedia as a handy solution to monitor the
 674     results of a bunch of small experiments.</span></li>
 675
 676   <li><a href="http://code.google.com/p/quadrant-framework/">quadrant-framework</a> (MySQL Load Testing Framework)<br/>
 677   <span class="desc">A user friendly framework for creating and visualizing
 678     MySQL database load test jobs. For more information on its use of dygraphs,
 679     see <a href="http://themattreid.com/wordpress/2011/05/20/quadrant-framework-rev7-update-adds-dygraphs-support/">this post</a>.</span></li>
 680
 681   <li><a href="http://spinwave.wordpress.com/2011/03/28/spinwave-systems-enables-energy-efficiency-case-studies/">Spinwave Systems</a> (Home energy monitoring)<br/>
 682   <span class="desc">dygraphs is used to chart energy usage over time.</span></li>
 683
 684
 685     <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/>
 686     <span class="desc">
 687     jWebChart is a stand-alone and Thredds' embedded plotting system for
 688     netCDF files. NetCDF is a common standard for the storage and
 689     distribution of scientific data.
 690     </span></li>
 691
 692     <li><a href="http://ngrams.cavorite.com/">n-gramas - Explore las tendencias en los artículos periodísticos de Colombia.</a><br/>
 693
 694
 695     <span class="desc">(English: "Explore trends in newspaper articles of
 696     Colombia"). dygraphs is used for displaying the results of this n-grams
 697     viewer.  Uses an extension for exporting the plots as PNG images
 698     (<a href="http://cavorite.com/labs/js/dygraphs-export/">[1]</a>, <a href="https://github.com/cavorite/dygraphs">[2]</a>).
 699     </span></li>
 700
 701     <li><a href="http://www.glerl.noaa.gov/data/now/wlevels/dbd/altSite.html">NOAA Great Lakes Water Level Dashboard</a><br/>
 702     <span class="desc">The Great Lakes Water Level dashboard was designed to help users view, understand, and compare Great Lakes surface water elevation data and forecasts from a variety of different sources, and across a variety of time scales ranging from monthly average values, to annual and multi-decadal values. First developed in Adobe Flash, a HTML 5 compatible version has been in the works and a functional draft is available here.</span></li>
 703
 704     </ul>
 705
 706     <p>Are you using dygraphs? Please let <a href="mailto:dan@dygraphs.com">Dan</a> know and he'll add your link here!</p>
 707
 708
 709     <h2 id="policy">Data Policy</h2>
 710     <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>
 711
 712     <p style="font-size:0.8em">Created May 9, 2008 by <a href=mailto:danvdk@gmail.com>Dan Vanderkam</a></p>
 713   </div>
 714
 715 </body>
 716 </html>