fix disappearing annotations bug
[dygraphs.git] / docs / data.html
CommitLineData
53e5cec3 1<!DOCTYPE html>
708cbe06
DV
2<html>
3 <head>
10494b48 4 <meta http-equiv="X-UA-Compatible" content="IE=EmulateIE7; IE=EmulateIE9">
708cbe06
DV
5 <title>dygraphs input types</title>
6 <style type="text/css">
f10f06f5
DV
7 code { white-space: pre; border: 1px dashed black; display: block; }
8 pre { white-space: pre; border: 1px dashed black; }
9 body { max-width: 800px; }
708cbe06
DV
10 </style>
11 </head>
12 <body>
13 <h2>dygraphs Data Format</h2>
14
15 <p>When you create a Dygraph object, your code looks something like
16 this:</p>
17
18 <code>
19 g = new Dygraph(document.getElementById("div"),
20 <i>data</i>,
21 { <i>options</i> });
22 </code>
23
24 <p>This document is about what you can put in the <i>data</i>
25 parameter.</p>
26
27 <p>There are five types of input that dygraphs will accept:</p>
28 <ol>
f10f06f5
DV
29 <li><a href="#csv">CSV data</a>
30 <li><a href="#url">URL</a>
31 <li><a href="#array">array (native format)</a>
32 <li><a href="#function">function</a>
33 <li><a href="#datatable">DataTable</a>
708cbe06
DV
34 </ol>
35
36 <p>These are all discussed below. If you're trying to debug why your input
37 won't parse, <b>check the JS error console</b>. dygraphs tries to log
38 informative errors explaining what's wrong with your data, and these can
39 often point you in the right direction.</p>
40
41 <p>There are several options which affect how your input data is
42 interpreted. These are:
43 <ul>
44 <li> <i>xValueParser</i> affects CSV only.
45 <li> <i>errorBars</i> affects all input types.
46 <li> <i>customBars</i> affects all input types.
47 <li> <i>fractions</i> affects all input types.
48 <li> <i>labels</i> affects all input types.
49 </ul>
50 </p>
51
f10f06f5 52 <a name="csv"><h3>CSV</h3>
708cbe06
DV
53 <p>Here's an example of what CSV data should look like:</p>
54 <pre>
55 Date,Series1,Series2
56 2009/07/12,100,200 # comments are OK on data lines
57 2009/07/19,150,201
58 </pre>
59
60 <p>"CSV" is actually a bit of a misnomer: the data can be tab-delimited,
61 too. The delimiter is set by the <i>delimiter</i> option. It default to ",".
62 If no delimiter is found in the first row, it switches over to tab.</p>
63
64 <p>CSV parsing can be split into three parts: headers, x-value and
65 y-values.</p>
66
67 <h4>Headers</h4>
68 <p>If you don't specify the <i>labels</i> option, dygraphs will look at the
69 first line of your CSV data to get the labels. If you see numbers for series
70 labels when you hover over the dygraph, it's likely because your first line
71 contains data but is being parsed as a label. The solution is to either add
72 a header line or specify the labels like this:</p>
73
74 <code>
75 new Dygraph(el,
76 "2009/07/12,100,200\n" +
77 "2009/07/19,150,201\n",
78 { labels: [ "Date", "Series1", "Series2" ] });
79 </code>
80
81 <h4>x-values</h4>
82 <p>Once the headers are parsed, dygraphs needs to determine what the type of
83 the x values is. They're either dates or numbers. To make this
84 determination, it looks at the first column of the first row ("2009/07/12"
85 in the example above). Here's the heuristic: if it contains a '-' or a '/',
86 or otherwise doesn't parse as a float, the it's a date. Otherwise, it's a
87 number.</p>
88
89 <p>Once the type is determined, that doesn't mean all the values will parse
90 correctly. The general rule is:<p>
91
92 <ul>
93 <li>For dates, your strings have to be parseable by <i>Date.parse</i>.
94 <li>For numbers, your strings have to be parseable by <i>parseFloat</i>.
95 </ul>
96
97 <p>You can manually verify this using a JavaScript console. If a value
98 doesn't parse, dygraphs will put a warning about it on your console. But
99 beware: different browsers support different date formats!</p>
100
101 <p>Here are some valid date formats:</p>
102 <ul>
103 <li>2009-07-12</li>
104 <li>2009/07/12</li>
105 <li>2009/07/12 12</li>
106 <li>2009/07/12 12:34</li>
107 <li>2009/07/12 12:34:56</li>
108 </ul>
109
110 <p>If you specify the <i>xValueParser</i> option, then all this detection is
111 bypassed and your function is called instead. Your parser function takes in
112 a string and needs to return a number. For dates/times, you should return
113 milliseconds since epoch. You may also want to specify a few other options
114 to make sure that everything gets displayed properly.<p>
115
116 <p>Here's code which parses a CSV file with unix timestamps in the first
117 column:</p>
118
119 <code>
120 new Dygraph(el,
121 "Date,Series1,Series2\n" +
122 "1247382000,100,200\n" +
123 "1247986800,150,201\n",
124 {
125 xValueFormatter: Dygraph.dateString_,
126 xValueParser: function(x) { return 1000*parseInt(x); },
127 xTicker: Dygraph.dateTicker
128 });
129 </code>
130
131 <h4>y-values</h4>
132 <p>Dependent (y-axis) values are simpler than x-values because they're
133 always numbers. The complexity here comes from the various ways that you can
134 specify the uncertainty in your measurements.<p>
135
136 <p>If your y-values are just numbers, then they need to be parseable by
137 JavaScript's parseFloat function. Acceptable formats include:</p>
138
139 <ul>
140 <li>12
141 <li>-12
142 <li>12.
143 <li>12.3
144 <li>1.24e+1
145 <li>-1.24e+1
146 </ul>
147
148 <p>If you have missing data, just leave the column blank (your CSV file will
149 probably contain a ",," in it).</p>
150
151 <p>If your numbers have uncertainty associated with them, then there are
152 three basic ways to express this: using fractions, standard deviations or
153 explicit ranges.</p>
154
155 <h5>Fractions</h5>
156 <p>If you specify the <i>fractions</i> option, then your data will all be
157 interpreted as ratios between zero and one. This is often the case if you're
158 plotting a percentage.</p>
159
160 <code>
161 new Dygraph(el,
162 "X,Frac1,Frac2\n" +
163 "1,1/2,3/4\n"+
164 "2,1/3,2/3\n"+
165 "3,2/3,17/49\n"+
166 "4,25/30,100/200",
167 { fractions: true });
168 </code>
169
170 <p>Why not just divide the fractions out yourself? There are two attractive
171 reasons not to:</p>
172
173 <ul>
174 <li>If you set both <i>fractions</i> and <i>errorBars</i>, then the
175 denominator is interpreted as a sample size and dygraphs will plot <a
176 href="http://en.wikipedia.org/wiki/Binomial_proportion_confidence_interval">Wilson
177 binomial proportion confidence intervals</a> around each point.
178
179 <li>If you set <i>showRoller</i>, then dygraphs will combine the values as
180 fractions. If two point are <i>a/b</i> and <i>c/d</i>, it will plot
181 <i>(a+b) / (c+d)</i> rather than <i>(a/b + c/d) / 2</i>, which is what
182 you'd get if you divided the fractions through. This will also shrink the
183 confidence intervals.</li>
184 </ul>
185
186 <h5>Standard Deviations</h5>
187 <p>Often you have a measurement and also a measure of its uncertainty: a
188 standard deviation. If you specify the <i>errorBars</i> option, dygraphs
189 will look for alternating value and standard deviation columns in your CSV
190 data. Here's what it should look like:</p>
191
192 <code>
193 new Dygraph(el,
194 "X,Y1,Y2\n" +
195 "1,10,5,20,5\n" +
196 "2,12,5,22,5\n",
197 { errorBars: true });
198 </code>
199
200 <p>The "5" values are standard deviations. When each point is plotted, a
201 2-standard deviation region around it is shaded, resulting in a 95%
202 confidence interval. If you want more or less confidence, you can set the
203 <i>sigma</i> option to something other than 2.0.</p>
204
205 <p>When you roll data with standard deviations, dygraphs will plot the
206 average of your values in each rolling period and the RMS value of your
207 standard deviations: sqrt(std1 + std2 + std3 + ... + stdN)/N.</p>
208
209 <h5>Custom error bars</h5>
210 <p>Sometimes your data has asymetric uncertainty or you want to specify
211 something else with the error bars around a point. One example of this is
212 the "temperatures" demo on the <a href="http://danvk.org/dygraphs">dygraphs
213 home page.</a>, where the point is the daily average and the bars denote
214 the low and high temperatures for the day.</p>
215
216 <p>To specify this format, set the <i>customBars</i> option. Your CSV values
217 should each be three numbers separated by semicolons ("low;mid;high").
218 Here's an example:</p>
219
220 <code>
221 new Dygraph(el,
222 "X,Y1,Y2\n" +
223 "1,10;20;30,20;5;25\n" +
224 "2,10;25;35,20;10;25\n",
225 { customBars: true });
226 </code>
227
228 <p>The middle value need not lie between the low and high values. If you set
229 a rolling period, the three values will all be averaged independently.</p>
230
231
f10f06f5 232 <a name="url"><h3>URL</h3>
708cbe06
DV
233 <p>If you pass in a URL, dygraphs will issue an XMLHttpRequest for it and
234 attempt to parse the returned data as CSV.
235 </p>
236
237 <p><i>Common problems</i>. Make sure the URL is accessible and returns data
238 in text format (as opposed to a CSV file with an HTML header). You can see
239 what the response looks like by checking your JS console or by requesting
240 the URL yourself.</p>
241
242
f10f06f5 243 <a name="array"><h3>Array (native format)</h3>
708cbe06
DV
244 <p>If you'll be constructing your data set from a server-side program (or
245 from JavaScript) then you're better off producing an array than CSV data.
246 This saves the cost of parsing the CSV data and also avoids common parser
247 errors.</p>
248
249 <p>The downside is that it's harder to look at your data (you'll need to use
250 a JS debugger) and that the data format is a bit less clear for values with
251 uncertainties.</p>
252
f10f06f5 253 <p>Here's an example of "native format":</p>
708cbe06 254
f10f06f5
DV
255 <code>
256 new Dygraph(document.getElementById("graphdiv2"),
257 [
258 [1,10,100],
259 [2,20,80],
260 [3,50,60],
261 [4,70,80]
262 ],
263 {
264 labels: [ "x", "A", "B" ]
265 });
266 </code>
708cbe06 267
f10f06f5
DV
268 <h4>Headers</h4>
269 <p>Headers for native format must be specified via the <i>labels</i>
270 option. There's no other way to set them.</p>
271
272 <h4>x-values</h4>
273 <p>If you want your x-values to be dates, you'll need to use specify a Date
274 object in the first column. Otherwise, specify a number. Here's a sample
275 array with dates on the x-axis:</p>
708cbe06 276
f10f06f5
DV
277 <code>
278 [
279 [ new Date("2009/07/12"), 100, 200 ],
280 [ new Date("2009/07/19"), 150, 220 ]
281 ]
282 </code>
283
284 <h4>y-values</h4>
285 <p>You can specify <i>errorBars</i>, <i>fractions</i> or <i>customBars</i>
286 with the array format. If you specify any of these, the values become arrays
287 (rather than numbers). Here's what the format looks like for each one:</p>
288
289 <code>
290 <i>errorBars</i>: [x, [value1, std1], [value2, std2], ...]
291 <i>fractions</i>: [x, [num1, den1], [num2, den2], ...]
292 <i>customBars</i>: [x, [low1, val1, high1], [low2, val2, high2], ...]
293 </code>
294
295 <p>To specify missing data, set the value to null. You may not set a value
296 inside an array to null. Use null instead of the entire array.</p>
297
298 <a name="function"><h3>Functions</h3>
299
300 <p>You can specify a function that returns any of the other types. If
301 <i>x</i> is a valid piece of dygraphs input, then so is</p>
302
303 <code>
304 function() { return x; }
305 </code>
306
307 <a name="datatable"><h3>DataTable</h3>
308 <p>You can also specify a Google Visualization Library <a
309 href="http://code.google.com/apis/visualization/documentation/reference.html#DataTable">DataTable</a>
310 object as your input data. This lets you easily switch between dygraphs and
311 other gviz visualizations such as the Annotated Timeline. It also lets you
312 embed a Dygraph in a Google Spreadsheet.</p>
313
314 <p>You'll need to set your first column's type to one of "number", "date"
315 or "datetime".</p>
316
317 <pre>
318 DataTable TODO:
708cbe06
DV
319 - When to use Dygraph.GvizWrapper
320 - how to specify fractions
321 - how to specify missing data
322 - how to specify value + std. dev.
323 - how to specify [low, middle, high]
324 - walkthrough of embedding a gadget in google docs/on a web page
325 - walkthrough of using std. dev. in a spreadsheet chart
f10f06f5 326 </pre>
708cbe06 327
d731e964
DV
328 <!-- Google Analytics -->
329<script type="text/javascript">
330 var _gaq = _gaq || [];
331 _gaq.push(['_setAccount', 'UA-769809-2']);
332 _gaq.push(['_trackPageview']);
333 (function() {
334 var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
335 ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
336 var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
337 })();
338</script>
708cbe06
DV
339 </body>
340</html>