Merge
[dygraphs.git] / dygraph-tickers.js
CommitLineData
88e95c46
DV
1/**
2 * @license
3 * Copyright 2011 Dan Vanderkam (danvdk@gmail.com)
4 * MIT-licensed (http://opensource.org/licenses/MIT)
5 */
48e614ac
DV
6
7/**
8 * @fileoverview Description of this file.
9 * @author danvk@google.com (Dan Vanderkam)
10 *
11 * A ticker is a function with the following interface:
12 *
13 * function(a, b, pixels, options_view, dygraph, forced_values);
14 * -> [ { v: tick1_v, label: tick1_label[, label_v: label_v1] },
15 * { v: tick2_v, label: tick2_label[, label_v: label_v2] },
16 * ...
17 * ]
18 *
19 * The returned value is called a "tick list".
20 *
21 * Arguments
22 * ---------
23 *
24 * [a, b] is the range of the axis for which ticks are being generated. For a
25 * numeric axis, these will simply be numbers. For a date axis, these will be
26 * millis since epoch (convertable to Date objects using "new Date(a)" and "new
27 * Date(b)").
28 *
29 * opts provides access to chart- and axis-specific options. It can be used to
30 * access number/date formatting code/options, check for a log scale, etc.
31 *
32 * pixels is the length of the axis in pixels. opts('pixelsPerLabel') is the
33 * minimum amount of space to be allotted to each label. For instance, if
34 * pixels=400 and opts('pixelsPerLabel')=40 then the ticker should return
35 * between zero and ten (400/40) ticks.
36 *
37 * dygraph is the Dygraph object for which an axis is being constructed.
38 *
39 * forced_values is used for secondary y-axes. The tick positions are typically
40 * set by the primary y-axis, so the secondary y-axis has no choice in where to
41 * put these. It simply has to generate labels for these data values.
42 *
43 * Tick lists
44 * ----------
45 * Typically a tick will have both a grid/tick line and a label at one end of
46 * that line (at the bottom for an x-axis, at left or right for the y-axis).
47 *
48 * A tick may be missing one of these two components:
49 * - If "label_v" is specified instead of "v", then there will be no tick or
50 * gridline, just a label.
51 * - Similarly, if "label" is not specified, then there will be a gridline
52 * without a label.
53 *
54 * This flexibility is useful in a few situations:
55 * - For log scales, some of the tick lines may be too close to all have labels.
56 * - For date scales where years are being displayed, it is desirable to display
57 * tick marks at the beginnings of years but labels (e.g. "2006") in the
58 * middle of the years.
59 */
60
3ce712e6 61/*jshint sub:true */
758a629f 62/*global Dygraph:false */
3ce712e6 63(function() {
c0f54d4f
DV
64"use strict";
65
b2867ee1 66/** @typedef {Array.<{v:number, label:string, label_v:(string|undefined)}>} */
0cd1ad15 67Dygraph.TickList = undefined; // the ' = undefined' keeps jshint happy.
b2867ee1
DV
68
69/** @typedef {function(
70 * number,
71 * number,
72 * number,
73 * function(string):*,
74 * Dygraph=,
75 * Array.<number>=
76 * ): Dygraph.TickList}
77 */
0cd1ad15 78Dygraph.Ticker = undefined; // the ' = undefined' keeps jshint happy.
b2867ee1
DV
79
80/** @type {Dygraph.Ticker} */
44462ba3
KW
81Dygraph.numericLinearTicks = function(a, b, pixels, opts, dygraph, vals) {
82 var nonLogscaleOpts = function(opt) {
83 if (opt === 'logscale') return false;
84 return opts(opt);
85 };
86 return Dygraph.numericTicks(a, b, pixels, nonLogscaleOpts, dygraph, vals);
87};
88
b2867ee1 89/** @type {Dygraph.Ticker} */
48e614ac 90Dygraph.numericTicks = function(a, b, pixels, opts, dygraph, vals) {
b2867ee1 91 var pixels_per_tick = /** @type{number} */(opts('pixelsPerLabel'));
48e614ac 92 var ticks = [];
758a629f 93 var i, j, tickV, nTicks;
48e614ac 94 if (vals) {
758a629f 95 for (i = 0; i < vals.length; i++) {
48e614ac
DV
96 ticks.push({v: vals[i]});
97 }
98 } else {
99 // TODO(danvk): factor this log-scale block out into a separate function.
100 if (opts("logscale")) {
758a629f 101 nTicks = Math.floor(pixels / pixels_per_tick);
48e614ac
DV
102 var minIdx = Dygraph.binarySearch(a, Dygraph.PREFERRED_LOG_TICK_VALUES, 1);
103 var maxIdx = Dygraph.binarySearch(b, Dygraph.PREFERRED_LOG_TICK_VALUES, -1);
104 if (minIdx == -1) {
105 minIdx = 0;
106 }
107 if (maxIdx == -1) {
108 maxIdx = Dygraph.PREFERRED_LOG_TICK_VALUES.length - 1;
109 }
110 // Count the number of tick values would appear, if we can get at least
111 // nTicks / 4 accept them.
112 var lastDisplayed = null;
113 if (maxIdx - minIdx >= nTicks / 4) {
114 for (var idx = maxIdx; idx >= minIdx; idx--) {
115 var tickValue = Dygraph.PREFERRED_LOG_TICK_VALUES[idx];
116 var pixel_coord = Math.log(tickValue / a) / Math.log(b / a) * pixels;
117 var tick = { v: tickValue };
758a629f 118 if (lastDisplayed === null) {
48e614ac
DV
119 lastDisplayed = {
120 tickValue : tickValue,
121 pixel_coord : pixel_coord
122 };
123 } else {
124 if (Math.abs(pixel_coord - lastDisplayed.pixel_coord) >= pixels_per_tick) {
125 lastDisplayed = {
126 tickValue : tickValue,
127 pixel_coord : pixel_coord
128 };
129 } else {
130 tick.label = "";
131 }
132 }
133 ticks.push(tick);
134 }
135 // Since we went in backwards order.
136 ticks.reverse();
137 }
138 }
139
140 // ticks.length won't be 0 if the log scale function finds values to insert.
758a629f 141 if (ticks.length === 0) {
48e614ac
DV
142 // Basic idea:
143 // Try labels every 1, 2, 5, 10, 20, 50, 100, etc.
144 // Calculate the resulting tick spacing (i.e. this.height_ / nTicks).
145 // The first spacing greater than pixelsPerYLabel is what we use.
146 // TODO(danvk): version that works on a log scale.
147 var kmg2 = opts("labelsKMG2");
fa0d7ad8 148 var mults, base;
48e614ac 149 if (kmg2) {
48f5d762 150 mults = [1, 2, 4, 8, 16, 32, 64, 128, 256];
fa0d7ad8 151 base = 16;
48e614ac 152 } else {
48f5d762 153 mults = [1, 2, 5, 10, 20, 50, 100];
fa0d7ad8 154 base = 10;
48e614ac 155 }
fa0d7ad8 156
48f5d762
KW
157 // Get the maximum number of permitted ticks based on the
158 // graph's pixel size and pixels_per_tick setting.
159 var max_ticks = Math.ceil(pixels / pixels_per_tick);
160
161 // Now calculate the data unit equivalent of this tick spacing.
162 // Use abs() since graphs may have a reversed Y axis.
163 var units_per_tick = Math.abs(b - a) / max_ticks;
164
165 // Based on this, get a starting scale which is the largest
166 // integer power of the chosen base (10 or 16) that still remains
167 // below the requested pixels_per_tick spacing.
fa0d7ad8
KW
168 var base_power = Math.floor(Math.log(units_per_tick) / Math.log(base));
169 var base_scale = Math.pow(base, base_power);
48f5d762
KW
170
171 // Now try multiples of the starting scale until we find one
172 // that results in tick marks spaced sufficiently far apart.
173 // The "mults" array should cover the range 1 .. base^2 to
174 // adjust for rounding and edge effects.
0cd1ad15 175 var scale, low_val, high_val, spacing;
fa0d7ad8
KW
176 for (j = 0; j < mults.length; j++) {
177 scale = base_scale * mults[j];
178 low_val = Math.floor(a / scale) * scale;
179 high_val = Math.ceil(b / scale) * scale;
180 nTicks = Math.abs(high_val - low_val) / scale;
181 spacing = pixels / nTicks;
48e614ac
DV
182 if (spacing > pixels_per_tick) break;
183 }
184
185 // Construct the set of ticks.
186 // Allow reverse y-axis if it's explicitly requested.
187 if (low_val > high_val) scale *= -1;
9146b6c0 188 for (i = 0; i <= nTicks; i++) {
758a629f 189 tickV = low_val + i * scale;
48e614ac
DV
190 ticks.push( {v: tickV} );
191 }
192 }
193 }
194
d67a4279 195 var formatter = /**@type{AxisLabelFormatter}*/(opts('axisLabelFormatter'));
48e614ac
DV
196
197 // Add labels to the ticks.
758a629f 198 for (i = 0; i < ticks.length; i++) {
48e614ac 199 if (ticks[i].label !== undefined) continue; // Use current label.
48e614ac 200 // TODO(danvk): set granularity to something appropriate here.
2fd143d3 201 ticks[i].label = formatter(ticks[i].v, 0, opts, dygraph);
48e614ac
DV
202 }
203
204 return ticks;
205};
206
207
b2867ee1 208/** @type {Dygraph.Ticker} */
48e614ac 209Dygraph.dateTicker = function(a, b, pixels, opts, dygraph, vals) {
7a1f1877 210 var chosen = Dygraph.pickDateTickGranularity(a, b, pixels, opts);
48e614ac
DV
211
212 if (chosen >= 0) {
213 return Dygraph.getDateAxis(a, b, chosen, opts, dygraph);
214 } else {
215 // this can happen if self.width_ is zero.
216 return [];
217 }
218};
219
220// Time granularity enumeration
b2867ee1 221// TODO(danvk): make this an @enum
48e614ac
DV
222Dygraph.SECONDLY = 0;
223Dygraph.TWO_SECONDLY = 1;
224Dygraph.FIVE_SECONDLY = 2;
225Dygraph.TEN_SECONDLY = 3;
226Dygraph.THIRTY_SECONDLY = 4;
227Dygraph.MINUTELY = 5;
228Dygraph.TWO_MINUTELY = 6;
229Dygraph.FIVE_MINUTELY = 7;
230Dygraph.TEN_MINUTELY = 8;
231Dygraph.THIRTY_MINUTELY = 9;
232Dygraph.HOURLY = 10;
233Dygraph.TWO_HOURLY = 11;
234Dygraph.SIX_HOURLY = 12;
235Dygraph.DAILY = 13;
236Dygraph.WEEKLY = 14;
237Dygraph.MONTHLY = 15;
238Dygraph.QUARTERLY = 16;
239Dygraph.BIANNUAL = 17;
240Dygraph.ANNUAL = 18;
241Dygraph.DECADAL = 19;
242Dygraph.CENTENNIAL = 20;
243Dygraph.NUM_GRANULARITIES = 21;
244
872a6a00
DV
245// Date components enumeration (in the order of the arguments in Date)
246// TODO: make this an @enum
247Dygraph.DATEFIELD_Y = 0;
248Dygraph.DATEFIELD_M = 1;
249Dygraph.DATEFIELD_D = 2;
250Dygraph.DATEFIELD_HH = 3;
251Dygraph.DATEFIELD_MM = 4;
252Dygraph.DATEFIELD_SS = 5;
253Dygraph.DATEFIELD_MS = 6;
254Dygraph.NUM_DATEFIELDS = 7;
255
256
257/** @type {Array.<{datefield:number, step:number, spacing:number}>} */
258Dygraph.TICK_PLACEMENT = [];
259Dygraph.TICK_PLACEMENT[Dygraph.SECONDLY] = {datefield: Dygraph.DATEFIELD_SS, step: 1, spacing: 1000 * 1};
260Dygraph.TICK_PLACEMENT[Dygraph.TWO_SECONDLY] = {datefield: Dygraph.DATEFIELD_SS, step: 2, spacing: 1000 * 2};
261Dygraph.TICK_PLACEMENT[Dygraph.FIVE_SECONDLY] = {datefield: Dygraph.DATEFIELD_SS, step: 5, spacing: 1000 * 5};
262Dygraph.TICK_PLACEMENT[Dygraph.TEN_SECONDLY] = {datefield: Dygraph.DATEFIELD_SS, step: 10, spacing: 1000 * 10};
263Dygraph.TICK_PLACEMENT[Dygraph.THIRTY_SECONDLY] = {datefield: Dygraph.DATEFIELD_SS, step: 30, spacing: 1000 * 30};
264Dygraph.TICK_PLACEMENT[Dygraph.MINUTELY] = {datefield: Dygraph.DATEFIELD_MM, step: 1, spacing: 1000 * 60};
265Dygraph.TICK_PLACEMENT[Dygraph.TWO_MINUTELY] = {datefield: Dygraph.DATEFIELD_MM, step: 2, spacing: 1000 * 60 * 2};
266Dygraph.TICK_PLACEMENT[Dygraph.FIVE_MINUTELY] = {datefield: Dygraph.DATEFIELD_MM, step: 5, spacing: 1000 * 60 * 5};
267Dygraph.TICK_PLACEMENT[Dygraph.TEN_MINUTELY] = {datefield: Dygraph.DATEFIELD_MM, step: 10, spacing: 1000 * 60 * 10};
268Dygraph.TICK_PLACEMENT[Dygraph.THIRTY_MINUTELY] = {datefield: Dygraph.DATEFIELD_MM, step: 30, spacing: 1000 * 60 * 30};
269Dygraph.TICK_PLACEMENT[Dygraph.HOURLY] = {datefield: Dygraph.DATEFIELD_HH, step: 1, spacing: 1000 * 3600};
270Dygraph.TICK_PLACEMENT[Dygraph.TWO_HOURLY] = {datefield: Dygraph.DATEFIELD_HH, step: 2, spacing: 1000 * 3600 * 2};
271Dygraph.TICK_PLACEMENT[Dygraph.SIX_HOURLY] = {datefield: Dygraph.DATEFIELD_HH, step: 6, spacing: 1000 * 3600 * 6};
272Dygraph.TICK_PLACEMENT[Dygraph.DAILY] = {datefield: Dygraph.DATEFIELD_D, step: 1, spacing: 1000 * 86400};
273Dygraph.TICK_PLACEMENT[Dygraph.WEEKLY] = {datefield: Dygraph.DATEFIELD_D, step: 7, spacing: 1000 * 604800};
274Dygraph.TICK_PLACEMENT[Dygraph.MONTHLY] = {datefield: Dygraph.DATEFIELD_M, step: 1, spacing: 1000 * 7200 * 365.2524}; // 1e3 * 60 * 60 * 24 * 365.2524 / 12
275Dygraph.TICK_PLACEMENT[Dygraph.QUARTERLY] = {datefield: Dygraph.DATEFIELD_M, step: 3, spacing: 1000 * 21600 * 365.2524}; // 1e3 * 60 * 60 * 24 * 365.2524 / 4
276Dygraph.TICK_PLACEMENT[Dygraph.BIANNUAL] = {datefield: Dygraph.DATEFIELD_M, step: 6, spacing: 1000 * 43200 * 365.2524}; // 1e3 * 60 * 60 * 24 * 365.2524 / 2
277Dygraph.TICK_PLACEMENT[Dygraph.ANNUAL] = {datefield: Dygraph.DATEFIELD_Y, step: 1, spacing: 1000 * 86400 * 365.2524}; // 1e3 * 60 * 60 * 24 * 365.2524 * 1
278Dygraph.TICK_PLACEMENT[Dygraph.DECADAL] = {datefield: Dygraph.DATEFIELD_Y, step: 10, spacing: 1000 * 864000 * 365.2524}; // 1e3 * 60 * 60 * 24 * 365.2524 * 10
279Dygraph.TICK_PLACEMENT[Dygraph.CENTENNIAL] = {datefield: Dygraph.DATEFIELD_Y, step: 100, spacing: 1000 * 8640000 * 365.2524}; // 1e3 * 60 * 60 * 24 * 365.2524 * 100
48e614ac 280
3c1b72e1 281
48e614ac 282/**
48e614ac
DV
283 * This is a list of human-friendly values at which to show tick marks on a log
284 * scale. It is k * 10^n, where k=1..9 and n=-39..+39, so:
285 * ..., 1, 2, 3, 4, 5, ..., 9, 10, 20, 30, ..., 90, 100, 200, 300, ...
286 * NOTE: this assumes that Dygraph.LOG_SCALE = 10.
b2867ee1 287 * @type {Array.<number>}
48e614ac 288 */
3ce712e6 289Dygraph.PREFERRED_LOG_TICK_VALUES = (function() {
48e614ac
DV
290 var vals = [];
291 for (var power = -39; power <= 39; power++) {
292 var range = Math.pow(10, power);
293 for (var mult = 1; mult <= 9; mult++) {
294 var val = range * mult;
295 vals.push(val);
296 }
297 }
298 return vals;
3ce712e6 299})();
48e614ac 300
7a1f1877
AV
301/**
302 * Determine the correct granularity of ticks on a date axis.
303 *
b2867ee1
DV
304 * @param {number} a Left edge of the chart (ms)
305 * @param {number} b Right edge of the chart (ms)
306 * @param {number} pixels Size of the chart in the relevant dimension (width).
872a6a00 307 * @param {function(string):*} opts Function mapping from option name -&gt; value.
b2867ee1
DV
308 * @return {number} The appropriate axis granularity for this chart. See the
309 * enumeration of possible values in dygraph-tickers.js.
7a1f1877
AV
310 */
311Dygraph.pickDateTickGranularity = function(a, b, pixels, opts) {
b2867ee1 312 var pixels_per_tick = /** @type{number} */(opts('pixelsPerLabel'));
7a1f1877
AV
313 for (var i = 0; i < Dygraph.NUM_GRANULARITIES; i++) {
314 var num_ticks = Dygraph.numDateTicks(a, b, i);
315 if (pixels / num_ticks >= pixels_per_tick) {
316 return i;
317 }
318 }
319 return -1;
320};
321
b2867ee1 322/**
872a6a00 323 * Compute the number of ticks on a date axis for a given granularity.
b2867ee1
DV
324 * @param {number} start_time
325 * @param {number} end_time
326 * @param {number} granularity (one of the granularities enumerated above)
872a6a00 327 * @return {number} (Approximate) number of ticks that would result.
b2867ee1 328 */
48e614ac 329Dygraph.numDateTicks = function(start_time, end_time, granularity) {
872a6a00
DV
330 var spacing = Dygraph.TICK_PLACEMENT[granularity].spacing;
331 return Math.round(1.0 * (end_time - start_time) / spacing);
48e614ac
DV
332};
333
b2867ee1 334/**
872a6a00 335 * Compute the positions and labels of ticks on a date axis for a given granularity.
b2867ee1
DV
336 * @param {number} start_time
337 * @param {number} end_time
338 * @param {number} granularity (one of the granularities enumerated above)
339 * @param {function(string):*} opts Function mapping from option name -&gt; value.
340 * @param {Dygraph=} dg
341 * @return {!Dygraph.TickList}
342 */
48e614ac 343Dygraph.getDateAxis = function(start_time, end_time, granularity, opts, dg) {
d67a4279 344 var formatter = /** @type{AxisLabelFormatter} */(
b2867ee1 345 opts("axisLabelFormatter"));
8c0599e3 346 var utc = opts("labelsUTC");
1e7f8af0
JPB
347 var accessors = utc ? Dygraph.DateAccessorsUTC : Dygraph.DateAccessorsLocal;
348
872a6a00 349 var datefield = Dygraph.TICK_PLACEMENT[granularity].datefield;
f921ded5
JPB
350 var step = Dygraph.TICK_PLACEMENT[granularity].step;
351 var spacing = Dygraph.TICK_PLACEMENT[granularity].spacing;
1e7f8af0 352
872a6a00
DV
353 // Choose a nice tick position before the initial instant.
354 // Currently, this code deals properly with the existent daily granularities:
355 // DAILY (with step of 1) and WEEKLY (with step of 7 but specially handled).
356 // Other daily granularities (say TWO_DAILY) should also be handled specially
357 // by setting the start_date_offset to 0.
358 var start_date = new Date(start_time);
1e7f8af0
JPB
359 var date_array = [];
360 date_array[Dygraph.DATEFIELD_Y] = accessors.getFullYear(start_date);
361 date_array[Dygraph.DATEFIELD_M] = accessors.getMonth(start_date);
362 date_array[Dygraph.DATEFIELD_D] = accessors.getDate(start_date);
363 date_array[Dygraph.DATEFIELD_HH] = accessors.getHours(start_date);
364 date_array[Dygraph.DATEFIELD_MM] = accessors.getMinutes(start_date);
365 date_array[Dygraph.DATEFIELD_SS] = accessors.getSeconds(start_date);
366 date_array[Dygraph.DATEFIELD_MS] = accessors.getMilliseconds(start_date);
367
872a6a00
DV
368 var start_date_offset = date_array[datefield] % step;
369 if (granularity == Dygraph.WEEKLY) {
370 // This will put the ticks on Sundays.
1e7f8af0 371 start_date_offset = accessors.getDay(start_date);
872a6a00 372 }
1e7f8af0 373
872a6a00
DV
374 date_array[datefield] -= start_date_offset;
375 for (var df = datefield + 1; df < Dygraph.NUM_DATEFIELDS; df++) {
376 // The minimum value is 1 for the day of month, and 0 for all other fields.
377 date_array[df] = (df === Dygraph.DATEFIELD_D) ? 1 : 0;
378 }
48e614ac 379
872a6a00 380 // Generate the ticks.
f921ded5
JPB
381 // For granularities not coarser than HOURLY we use the fact that:
382 // the number of milliseconds between ticks is constant
383 // and equal to the defined spacing.
384 // Otherwise we rely on the 'roll over' property of the Date functions:
385 // when some date field is set to a value outside of its logical range,
386 // the excess 'rolls over' the next (more significant) field.
387 // However, when using local time with DST transitions,
388 // there are dates that do not represent any time value at all
389 // (those in the hour skipped at the 'spring forward'),
390 // and the JavaScript engines usually return an equivalent value.
1e7f8af0
JPB
391 // Hence we have to check that the date is properly increased at each step,
392 // returning a date at a nice tick position.
872a6a00 393 var ticks = [];
1e7f8af0
JPB
394 var tick_date = accessors.makeDate.apply(null, date_array);
395 var tick_time = tick_date.getTime();
f921ded5 396 if (granularity <= Dygraph.HOURLY) {
1e7f8af0
JPB
397 if (tick_time < start_time) {
398 tick_time += spacing;
399 tick_date = new Date(tick_time);
f921ded5 400 }
1e7f8af0
JPB
401 while (tick_time <= end_time) {
402 ticks.push({ v: tick_time,
403 label: formatter(tick_date, granularity, opts, dg)
404 });
405 tick_time += spacing;
406 tick_date = new Date(tick_time);
f921ded5 407 }
1e7f8af0
JPB
408 } else {
409 if (tick_time < start_time) {
f921ded5 410 date_array[datefield] += step;
1e7f8af0
JPB
411 tick_date = accessors.makeDate.apply(null, date_array);
412 tick_time = tick_date.getTime();
f921ded5 413 }
1e7f8af0
JPB
414 while (tick_time <= end_time) {
415 if (granularity >= Dygraph.DAILY ||
416 accessors.getHours(tick_date) % step === 0) {
417 ticks.push({ v: tick_time,
418 label: formatter(tick_date, granularity, opts, dg)
f921ded5 419 });
f921ded5
JPB
420 }
421 date_array[datefield] += step;
1e7f8af0
JPB
422 tick_date = accessors.makeDate.apply(null, date_array);
423 tick_time = tick_date.getTime();
48e614ac
DV
424 }
425 }
48e614ac
DV
426 return ticks;
427};
428
4ec7b44a
MF
429// These are set here so that this file can be included after dygraph.js
430// or independently.
4294a33f
MF
431if (Dygraph &&
432 Dygraph.DEFAULT_ATTRS &&
433 Dygraph.DEFAULT_ATTRS['axes'] &&
434 Dygraph.DEFAULT_ATTRS['axes']['x'] &&
435 Dygraph.DEFAULT_ATTRS['axes']['y'] &&
436 Dygraph.DEFAULT_ATTRS['axes']['y2']) {
437 Dygraph.DEFAULT_ATTRS['axes']['x']['ticker'] = Dygraph.dateTicker;
438 Dygraph.DEFAULT_ATTRS['axes']['y']['ticker'] = Dygraph.numericTicks;
439 Dygraph.DEFAULT_ATTRS['axes']['y2']['ticker'] = Dygraph.numericTicks;
440}
3ce712e6
DV
441
442})();