3 * Copyright 2011 Dan Vanderkam (danvdk@gmail.com)
4 * MIT-licensed (http://opensource.org/licenses/MIT)
8 * @fileoverview Description of this file.
9 * @author danvk@google.com (Dan Vanderkam)
11 * A ticker is a function with the following interface:
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] },
19 * The returned value is called a "tick list".
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
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.
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.
37 * dygraph is the Dygraph object for which an axis is being constructed.
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.
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).
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
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.
61 /*jshint globalstrict:true, sub:true */
62 /*global Dygraph:false */
65 /** @typedef {Array.<{v:number, label:string, label_v:(string|undefined)}>} */
66 Dygraph
.TickList
= undefined
; // the ' = undefined' keeps jshint happy.
68 /** @typedef {function(
75 * ): Dygraph.TickList}
77 Dygraph
.Ticker
= undefined
; // the ' = undefined' keeps jshint happy.
79 /** @type {Dygraph.Ticker} */
80 Dygraph
.numericLinearTicks
= function(a
, b
, pixels
, opts
, dygraph
, vals
) {
81 var nonLogscaleOpts
= function(opt
) {
82 if (opt
=== 'logscale') return false;
85 return Dygraph
.numericTicks(a
, b
, pixels
, nonLogscaleOpts
, dygraph
, vals
);
88 /** @type {Dygraph.Ticker} */
89 Dygraph
.numericTicks
= function(a
, b
, pixels
, opts
, dygraph
, vals
) {
90 var pixels_per_tick
= /** @type{number} */(opts('pixelsPerLabel'));
92 var i
, j
, tickV
, nTicks
;
94 for (i
= 0; i
< vals
.length
; i
++) {
95 ticks
.push({v
: vals
[i
]});
98 // TODO(danvk): factor this log-scale block out into a separate function.
99 if (opts("logscale")) {
100 nTicks
= Math
.floor(pixels
/ pixels_per_tick
);
101 var minIdx
= Dygraph
.binarySearch(a
, Dygraph
.PREFERRED_LOG_TICK_VALUES
, 1);
102 var maxIdx
= Dygraph
.binarySearch(b
, Dygraph
.PREFERRED_LOG_TICK_VALUES
, -1);
107 maxIdx
= Dygraph
.PREFERRED_LOG_TICK_VALUES
.length
- 1;
109 // Count the number of tick values would appear, if we can get at least
110 // nTicks / 4 accept them
.
111 var lastDisplayed
= null;
112 if (maxIdx
- minIdx
>= nTicks
/ 4) {
113 for (var idx
= maxIdx
; idx
>= minIdx
; idx
--) {
114 var tickValue
= Dygraph
.PREFERRED_LOG_TICK_VALUES
[idx
];
115 var pixel_coord
= Math
.log(tickValue
/ a) / Math
.log(b
/ a
) * pixels
;
116 var tick
= { v
: tickValue
};
117 if (lastDisplayed
=== null) {
119 tickValue
: tickValue
,
120 pixel_coord
: pixel_coord
123 if (Math
.abs(pixel_coord
- lastDisplayed
.pixel_coord
) >= pixels_per_tick
) {
125 tickValue
: tickValue
,
126 pixel_coord
: pixel_coord
134 // Since we went in backwards order.
139 // ticks.length won't be 0 if the log scale function finds values to insert.
140 if (ticks
.length
=== 0) {
142 // Try labels every 1, 2, 5, 10, 20, 50, 100, etc.
143 // Calculate the resulting tick spacing (i.e. this.height_ / nTicks
).
144 // The first spacing greater than pixelsPerYLabel is what we use.
145 // TODO(danvk): version that works on a log scale.
146 var kmg2
= opts("labelsKMG2");
149 mults
= [1, 2, 4, 8, 16, 32, 64, 128, 256];
152 mults
= [1, 2, 5, 10, 20, 50, 100];
156 // Get the maximum number of permitted ticks based on the
157 // graph's pixel size and pixels_per_tick setting.
158 var max_ticks
= Math
.ceil(pixels
/ pixels_per_tick
);
160 // Now calculate the data unit equivalent of this tick spacing.
161 // Use abs() since graphs may have a reversed Y axis.
162 var units_per_tick
= Math
.abs(b
- a
) / max_ticks
;
164 // Based on this, get a starting scale which is the largest
165 // integer power of the chosen base (10 or 16) that still remains
166 // below the requested pixels_per_tick spacing.
167 var base_power
= Math
.floor(Math
.log(units_per_tick
) / Math
.log(base
));
168 var base_scale
= Math
.pow(base
, base_power
);
170 // Now try multiples of the starting scale until we find one
171 // that results in tick marks spaced sufficiently far apart.
172 // The "mults" array should cover the range 1 .. base^2 to
173 // adjust for rounding and edge effects.
174 var scale
, low_val
, high_val
, spacing
;
175 for (j
= 0; j
< mults
.length
; j
++) {
176 scale
= base_scale
* mults
[j
];
177 low_val
= Math
.floor(a
/ scale
) * scale
;
178 high_val
= Math
.ceil(b
/ scale
) * scale
;
179 nTicks
= Math
.abs(high_val
- low_val
) / scale
;
180 spacing
= pixels
/ nTicks
;
181 if (spacing
> pixels_per_tick
) break;
184 // Construct the set of ticks.
185 // Allow reverse y-axis if it's explicitly requested.
186 if (low_val
> high_val
) scale
*= -1;
187 for (i
= 0; i
<= nTicks
; i
++) {
188 tickV
= low_val
+ i
* scale
;
189 ticks
.push( {v
: tickV
} );
194 var formatter
= /**@type{AxisLabelFormatter}*/(opts('axisLabelFormatter'));
196 // Add labels to the ticks.
197 for (i
= 0; i
< ticks
.length
; i
++) {
198 if (ticks
[i
].label
!== undefined
) continue; // Use current label.
199 // TODO(danvk): set granularity to something appropriate here.
200 ticks
[i
].label
= formatter(ticks
[i
].v
, 0, opts
, dygraph
);
207 /** @type {Dygraph.Ticker} */
208 Dygraph
.dateTicker
= function(a
, b
, pixels
, opts
, dygraph
, vals
) {
209 var chosen
= Dygraph
.pickDateTickGranularity(a
, b
, pixels
, opts
);
212 return Dygraph
.getDateAxis(a
, b
, chosen
, opts
, dygraph
);
214 // this can happen if self.width_ is zero.
219 // Time granularity enumeration
220 // TODO(danvk): make this an @enum
221 Dygraph
.SECONDLY
= 0;
222 Dygraph
.TWO_SECONDLY
= 1;
223 Dygraph
.FIVE_SECONDLY
= 2;
224 Dygraph
.TEN_SECONDLY
= 3;
225 Dygraph
.THIRTY_SECONDLY
= 4;
226 Dygraph
.MINUTELY
= 5;
227 Dygraph
.TWO_MINUTELY
= 6;
228 Dygraph
.FIVE_MINUTELY
= 7;
229 Dygraph
.TEN_MINUTELY
= 8;
230 Dygraph
.THIRTY_MINUTELY
= 9;
232 Dygraph
.TWO_HOURLY
= 11;
233 Dygraph
.SIX_HOURLY
= 12;
236 Dygraph
.MONTHLY
= 15;
237 Dygraph
.QUARTERLY
= 16;
238 Dygraph
.BIANNUAL
= 17;
240 Dygraph
.DECADAL
= 19;
241 Dygraph
.CENTENNIAL
= 20;
242 Dygraph
.NUM_GRANULARITIES
= 21;
244 // Date components enumeration (in the order of the arguments in Date)
245 // TODO: make this an @enum
246 Dygraph
.DATEFIELD_Y
= 0;
247 Dygraph
.DATEFIELD_M
= 1;
248 Dygraph
.DATEFIELD_D
= 2;
249 Dygraph
.DATEFIELD_HH
= 3;
250 Dygraph
.DATEFIELD_MM
= 4;
251 Dygraph
.DATEFIELD_SS
= 5;
252 Dygraph
.DATEFIELD_MS
= 6;
253 Dygraph
.NUM_DATEFIELDS
= 7;
256 /** @type {Array.<{datefield:number, step:number, spacing:number}>} */
257 Dygraph
.TICK_PLACEMENT
= [];
258 Dygraph
.TICK_PLACEMENT
[Dygraph
.SECONDLY
] = {datefield
: Dygraph
.DATEFIELD_SS
, step
: 1, spacing
: 1000 * 1};
259 Dygraph
.TICK_PLACEMENT
[Dygraph
.TWO_SECONDLY
] = {datefield
: Dygraph
.DATEFIELD_SS
, step
: 2, spacing
: 1000 * 2};
260 Dygraph
.TICK_PLACEMENT
[Dygraph
.FIVE_SECONDLY
] = {datefield
: Dygraph
.DATEFIELD_SS
, step
: 5, spacing
: 1000 * 5};
261 Dygraph
.TICK_PLACEMENT
[Dygraph
.TEN_SECONDLY
] = {datefield
: Dygraph
.DATEFIELD_SS
, step
: 10, spacing
: 1000 * 10};
262 Dygraph
.TICK_PLACEMENT
[Dygraph
.THIRTY_SECONDLY
] = {datefield
: Dygraph
.DATEFIELD_SS
, step
: 30, spacing
: 1000 * 30};
263 Dygraph
.TICK_PLACEMENT
[Dygraph
.MINUTELY
] = {datefield
: Dygraph
.DATEFIELD_MM
, step
: 1, spacing
: 1000 * 60};
264 Dygraph
.TICK_PLACEMENT
[Dygraph
.TWO_MINUTELY
] = {datefield
: Dygraph
.DATEFIELD_MM
, step
: 2, spacing
: 1000 * 60 * 2};
265 Dygraph
.TICK_PLACEMENT
[Dygraph
.FIVE_MINUTELY
] = {datefield
: Dygraph
.DATEFIELD_MM
, step
: 5, spacing
: 1000 * 60 * 5};
266 Dygraph
.TICK_PLACEMENT
[Dygraph
.TEN_MINUTELY
] = {datefield
: Dygraph
.DATEFIELD_MM
, step
: 10, spacing
: 1000 * 60 * 10};
267 Dygraph
.TICK_PLACEMENT
[Dygraph
.THIRTY_MINUTELY
] = {datefield
: Dygraph
.DATEFIELD_MM
, step
: 30, spacing
: 1000 * 60 * 30};
268 Dygraph
.TICK_PLACEMENT
[Dygraph
.HOURLY
] = {datefield
: Dygraph
.DATEFIELD_HH
, step
: 1, spacing
: 1000 * 3600};
269 Dygraph
.TICK_PLACEMENT
[Dygraph
.TWO_HOURLY
] = {datefield
: Dygraph
.DATEFIELD_HH
, step
: 2, spacing
: 1000 * 3600 * 2};
270 Dygraph
.TICK_PLACEMENT
[Dygraph
.SIX_HOURLY
] = {datefield
: Dygraph
.DATEFIELD_HH
, step
: 6, spacing
: 1000 * 3600 * 6};
271 Dygraph
.TICK_PLACEMENT
[Dygraph
.DAILY
] = {datefield
: Dygraph
.DATEFIELD_D
, step
: 1, spacing
: 1000 * 86400};
272 Dygraph
.TICK_PLACEMENT
[Dygraph
.WEEKLY
] = {datefield
: Dygraph
.DATEFIELD_D
, step
: 7, spacing
: 1000 * 604800};
273 Dygraph
.TICK_PLACEMENT
[Dygraph
.MONTHLY
] = {datefield
: Dygraph
.DATEFIELD_M
, step
: 1, spacing
: 1000 * 7200 * 365.2524}; // 1e3 * 60 * 60 * 24 * 365.2524 / 12
274 Dygraph
.TICK_PLACEMENT
[Dygraph
.QUARTERLY
] = {datefield
: Dygraph
.DATEFIELD_M
, step
: 3, spacing
: 1000 * 21600 * 365.2524}; // 1e3 * 60 * 60 * 24 * 365.2524 / 4
275 Dygraph
.TICK_PLACEMENT
[Dygraph
.BIANNUAL
] = {datefield
: Dygraph
.DATEFIELD_M
, step
: 6, spacing
: 1000 * 43200 * 365.2524}; // 1e3 * 60 * 60 * 24 * 365.2524 / 2
276 Dygraph
.TICK_PLACEMENT
[Dygraph
.ANNUAL
] = {datefield
: Dygraph
.DATEFIELD_Y
, step
: 1, spacing
: 1000 * 86400 * 365.2524}; // 1e3 * 60 * 60 * 24 * 365.2524 * 1
277 Dygraph
.TICK_PLACEMENT
[Dygraph
.DECADAL
] = {datefield
: Dygraph
.DATEFIELD_Y
, step
: 10, spacing
: 1000 * 864000 * 365.2524}; // 1e3 * 60 * 60 * 24 * 365.2524 * 10
278 Dygraph
.TICK_PLACEMENT
[Dygraph
.CENTENNIAL
] = {datefield
: Dygraph
.DATEFIELD_Y
, step
: 100, spacing
: 1000 * 8640000 * 365.2524}; // 1e3 * 60 * 60 * 24 * 365.2524 * 100
282 * This is a list of human-friendly values at which to show tick marks on a log
283 * scale. It is k * 10^n, where k=1..9 and n=-39..+39, so:
284 * ..., 1, 2, 3, 4, 5, ..., 9, 10, 20, 30, ..., 90, 100, 200, 300, ...
285 * NOTE: this assumes that Dygraph.LOG_SCALE = 10.
286 * @type {Array.<number>}
288 Dygraph
.PREFERRED_LOG_TICK_VALUES
= function() {
290 for (var power
= -39; power
<= 39; power
++) {
291 var range
= Math
.pow(10, power
);
292 for (var mult
= 1; mult
<= 9; mult
++) {
293 var val
= range
* mult
;
301 * Determine the correct granularity of ticks on a date axis.
303 * @param {number} a Left edge of the chart (ms)
304 * @param {number} b Right edge of the chart (ms)
305 * @param {number} pixels Size of the chart in the relevant dimension (width).
306 * @param {function(string):*} opts Function mapping from option name -> value.
307 * @return {number} The appropriate axis granularity for this chart. See the
308 * enumeration of possible values in dygraph-tickers.js.
310 Dygraph
.pickDateTickGranularity
= function(a
, b
, pixels
, opts
) {
311 var pixels_per_tick
= /** @type{number} */(opts('pixelsPerLabel'));
312 for (var i
= 0; i
< Dygraph
.NUM_GRANULARITIES
; i
++) {
313 var num_ticks
= Dygraph
.numDateTicks(a
, b
, i
);
314 if (pixels
/ num_ticks
>= pixels_per_tick
) {
322 * Compute the number of ticks on a date axis for a given granularity.
323 * @param {number} start_time
324 * @param {number} end_time
325 * @param {number} granularity (one of the granularities enumerated above)
326 * @return {number} (Approximate) number of ticks that would result.
328 Dygraph
.numDateTicks
= function(start_time
, end_time
, granularity
) {
329 var spacing
= Dygraph
.TICK_PLACEMENT
[granularity
].spacing
;
330 return Math
.round(1.0 * (end_time
- start_time
) / spacing
);
334 * Compute the positions and labels of ticks on a date axis for a given granularity.
335 * @param {number} start_time
336 * @param {number} end_time
337 * @param {number} granularity (one of the granularities enumerated above)
338 * @param {function(string):*} opts Function mapping from option name -> value.
339 * @param {Dygraph=} dg
340 * @return {!Dygraph.TickList}
342 Dygraph
.getDateAxis
= function(start_time
, end_time
, granularity
, opts
, dg
) {
343 var formatter
= /** @type{AxisLabelFormatter} */(
344 opts("axisLabelFormatter"));
345 var utc
= opts("labelsDateUTC");
347 var step
= Dygraph
.TICK_PLACEMENT
[granularity
].step
;
348 var datefield
= Dygraph
.TICK_PLACEMENT
[granularity
].datefield
;
350 // Choose appropiate date methods according to UTC or local time option.
351 // weekday: return the day of week from a Date object.
352 // decompose_date: decompose a Date object into an array of datefields.
353 // compose_date: compose a Date object from an array of date fields.
354 var compose_date
, decompose_date
, weekday
;
356 weekday
= function (d
) {
357 return d
.getUTCDay();
359 decompose_date
= function (d
) {
361 a
[Dygraph
.DATEFIELD_Y
] = d
.getUTCFullYear();
362 a
[Dygraph
.DATEFIELD_M
] = d
.getUTCMonth();
363 a
[Dygraph
.DATEFIELD_D
] = d
.getUTCDate();
364 a
[Dygraph
.DATEFIELD_HH
] = d
.getUTCHours();
365 a
[Dygraph
.DATEFIELD_MM
] = d
.getUTCMinutes();
366 a
[Dygraph
.DATEFIELD_SS
] = d
.getUTCSeconds();
367 a
[Dygraph
.DATEFIELD_MS
] = d
.getUTCMilliseconds();
370 compose_date
= function (a
) {
371 var d
= new Date(Date
.UTC(a
[Dygraph
.DATEFIELD_Y
],
372 a
[Dygraph
.DATEFIELD_M
],
373 a
[Dygraph
.DATEFIELD_D
],
374 a
[Dygraph
.DATEFIELD_HH
],
375 a
[Dygraph
.DATEFIELD_MM
],
376 a
[Dygraph
.DATEFIELD_SS
],
377 a
[Dygraph
.DATEFIELD_MS
]));
381 weekday
= function(d
) {
384 decompose_date
= function (d
) {
386 a
[Dygraph
.DATEFIELD_Y
] = d
.getFullYear();
387 a
[Dygraph
.DATEFIELD_M
] = d
.getMonth();
388 a
[Dygraph
.DATEFIELD_D
] = d
.getDate();
389 a
[Dygraph
.DATEFIELD_HH
] = d
.getHours();
390 a
[Dygraph
.DATEFIELD_MM
] = d
.getMinutes();
391 a
[Dygraph
.DATEFIELD_SS
] = d
.getSeconds();
392 a
[Dygraph
.DATEFIELD_MS
] = d
.getMilliseconds();
395 compose_date
= function (a
) {
396 var d
= new Date(a
[Dygraph
.DATEFIELD_Y
],
397 a
[Dygraph
.DATEFIELD_M
],
398 a
[Dygraph
.DATEFIELD_D
],
399 a
[Dygraph
.DATEFIELD_HH
],
400 a
[Dygraph
.DATEFIELD_MM
],
401 a
[Dygraph
.DATEFIELD_SS
],
402 a
[Dygraph
.DATEFIELD_MS
]);
407 // Choose a nice tick position before the initial instant.
408 // Currently, this code deals properly with the existent daily granularities:
409 // DAILY (with step of 1) and WEEKLY (with step of 7 but specially handled).
410 // Other daily granularities (say TWO_DAILY) should also be handled specially
411 // by setting the start_date_offset to 0.
412 var start_date
= new Date(start_time
);
413 var date_array
= decompose_date(start_date
);
414 var start_date_offset
= date_array
[datefield
] % step
;
415 if (granularity
== Dygraph
.WEEKLY
) {
416 // This will put the ticks on Sundays.
417 start_date_offset
= weekday(start_date
);
419 date_array
[datefield
] -= start_date_offset
;
420 for (var df
= datefield
+ 1; df
< Dygraph
.NUM_DATEFIELDS
; df
++) {
421 // The minimum value is 1 for the day of month, and 0 for all other fields.
422 date_array
[df
] = (df
=== Dygraph
.DATEFIELD_D
) ? 1 : 0;
425 // Generate the ticks.
426 // This relies on the roll over property of the Date functions:
427 // when some date field is set to a value outside of its logical range,
428 // the excess 'rolls over' the next (more significant) field.
429 // When using local time with DST transitions, different dates may represent
430 // the same time instant, so do not repeat the tick. At each step,
431 // we have to check that the date is effectively increased because native
432 // JS date functions do not assert that on DST transitions.
433 // Since start_date is no later than start_time (but possibly equal),
434 // assuming a previous tick just before start_time also removes an spurious
435 // tick outside the given time range.
437 var next_tick_date
= compose_date(date_array
);
438 var next_tick_time
= next_tick_date
.getTime();
439 var prev_tick_time
= start_time
- 1;
440 while (next_tick_time
<= end_time
) {
441 if (next_tick_time
> prev_tick_time
) {
442 ticks
.push({ v
: next_tick_time
,
443 label
: formatter(next_tick_date
, granularity
, opts
, dg
)
445 prev_tick_time
= next_tick_time
;
447 date_array
[datefield
] += step
;
448 next_tick_date
= compose_date(date_array
);
449 next_tick_time
= next_tick_date
.getTime();
454 // These are set here so that this file can be included after dygraph.js
457 Dygraph
.DEFAULT_ATTRS
&&
458 Dygraph
.DEFAULT_ATTRS
['axes'] &&
459 Dygraph
.DEFAULT_ATTRS
['axes']['x'] &&
460 Dygraph
.DEFAULT_ATTRS
['axes']['y'] &&
461 Dygraph
.DEFAULT_ATTRS
['axes']['y2']) {
462 Dygraph
.DEFAULT_ATTRS
['axes']['x']['ticker'] = Dygraph
.dateTicker
;
463 Dygraph
.DEFAULT_ATTRS
['axes']['y']['ticker'] = Dygraph
.numericTicks
;
464 Dygraph
.DEFAULT_ATTRS
['axes']['y2']['ticker'] = Dygraph
.numericTicks
;