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.
62 /*global Dygraph:false */
65 import * as utils from
'./dygraph-utils';
67 /** @typedef {Array.<{v:number, label:string, label_v:(string|undefined)}>} */
68 var TickList
= undefined
; // the ' = undefined' keeps jshint happy.
70 /** @typedef {function(
79 var Ticker
= undefined
; // the ' = undefined' keeps jshint happy.
82 export var numericLinearTicks
= function(a
, b
, pixels
, opts
, dygraph
, vals
) {
83 var nonLogscaleOpts
= function(opt
) {
84 if (opt
=== 'logscale') return false;
87 return numericTicks(a
, b
, pixels
, nonLogscaleOpts
, dygraph
, vals
);
91 export var numericTicks
= function(a
, b
, pixels
, opts
, dygraph
, vals
) {
92 var pixels_per_tick
= /** @type{number} */(opts('pixelsPerLabel'));
94 var i
, j
, tickV
, nTicks
;
96 for (i
= 0; i
< vals
.length
; i
++) {
97 ticks
.push({v
: vals
[i
]});
100 // TODO(danvk): factor this log-scale block out into a separate function.
101 if (opts("logscale")) {
102 nTicks
= Math
.floor(pixels
/ pixels_per_tick
);
103 var minIdx
= utils
.binarySearch(a
, PREFERRED_LOG_TICK_VALUES
, 1);
104 var maxIdx
= utils
.binarySearch(b
, PREFERRED_LOG_TICK_VALUES
, -1);
109 maxIdx
= PREFERRED_LOG_TICK_VALUES
.length
- 1;
111 // Count the number of tick values would appear, if we can get at least
112 // nTicks / 4 accept them
.
113 var lastDisplayed
= null;
114 if (maxIdx
- minIdx
>= nTicks
/ 4) {
115 for (var idx
= maxIdx
; idx
>= minIdx
; idx
--) {
116 var tickValue
= PREFERRED_LOG_TICK_VALUES
[idx
];
117 var pixel_coord
= Math
.log(tickValue
/ a) / Math
.log(b
/ a
) * pixels
;
118 var tick
= { v
: tickValue
};
119 if (lastDisplayed
=== null) {
121 tickValue
: tickValue
,
122 pixel_coord
: pixel_coord
125 if (Math
.abs(pixel_coord
- lastDisplayed
.pixel_coord
) >= pixels_per_tick
) {
127 tickValue
: tickValue
,
128 pixel_coord
: pixel_coord
136 // Since we went in backwards order.
141 // ticks.length won't be 0 if the log scale function finds values to insert.
142 if (ticks
.length
=== 0) {
144 // Try labels every 1, 2, 5, 10, 20, 50, 100, etc.
145 // Calculate the resulting tick spacing (i.e. this.height_ / nTicks
).
146 // The first spacing greater than pixelsPerYLabel is what we use.
147 // TODO(danvk): version that works on a log scale.
148 var kmg2
= opts("labelsKMG2");
151 mults
= [1, 2, 4, 8, 16, 32, 64, 128, 256];
154 mults
= [1, 2, 5, 10, 20, 50, 100];
158 // Get the maximum number of permitted ticks based on the
159 // graph's pixel size and pixels_per_tick setting.
160 var max_ticks
= Math
.ceil(pixels
/ pixels_per_tick
);
162 // Now calculate the data unit equivalent of this tick spacing.
163 // Use abs() since graphs may have a reversed Y axis.
164 var units_per_tick
= Math
.abs(b
- a
) / max_ticks
;
166 // Based on this, get a starting scale which is the largest
167 // integer power of the chosen base (10 or 16) that still remains
168 // below the requested pixels_per_tick spacing.
169 var base_power
= Math
.floor(Math
.log(units_per_tick
) / Math
.log(base
));
170 var base_scale
= Math
.pow(base
, base_power
);
172 // Now try multiples of the starting scale until we find one
173 // that results in tick marks spaced sufficiently far apart.
174 // The "mults" array should cover the range 1 .. base^2 to
175 // adjust for rounding and edge effects.
176 var scale
, low_val
, high_val
, spacing
;
177 for (j
= 0; j
< mults
.length
; j
++) {
178 scale
= base_scale
* mults
[j
];
179 low_val
= Math
.floor(a
/ scale
) * scale
;
180 high_val
= Math
.ceil(b
/ scale
) * scale
;
181 nTicks
= Math
.abs(high_val
- low_val
) / scale
;
182 spacing
= pixels
/ nTicks
;
183 if (spacing
> pixels_per_tick
) break;
186 // Construct the set of ticks.
187 // Allow reverse y-axis if it's explicitly requested.
188 if (low_val
> high_val
) scale
*= -1;
189 for (i
= 0; i
<= nTicks
; i
++) {
190 tickV
= low_val
+ i
* scale
;
191 ticks
.push( {v
: tickV
} );
196 var formatter
= /**@type{AxisLabelFormatter}*/(opts('axisLabelFormatter'));
198 // Add labels to the ticks.
199 for (i
= 0; i
< ticks
.length
; i
++) {
200 if (ticks
[i
].label
!== undefined
) continue; // Use current label.
201 // TODO(danvk): set granularity to something appropriate here.
202 ticks
[i
].label
= formatter
.call(dygraph
, ticks
[i
].v
, 0, opts
, dygraph
);
209 /** @type {Ticker} */
210 export var dateTicker
= function(a
, b
, pixels
, opts
, dygraph
, vals
) {
211 var chosen
= pickDateTickGranularity(a
, b
, pixels
, opts
);
214 return getDateAxis(a
, b
, chosen
, opts
, dygraph
);
216 // this can happen if self.width_ is zero.
221 // Time granularity enumeration
222 export var Granularity
= {
224 TWO_MILLISECONDLY
: 1,
225 FIVE_MILLISECONDLY
: 2,
226 TEN_MILLISECONDLY
: 3,
227 FIFTY_MILLISECONDLY
: 4,
228 HUNDRED_MILLISECONDLY
: 5,
229 FIVE_HUNDRED_MILLISECONDLY
: 6,
252 NUM_GRANULARITIES
: 29
255 // Date components enumeration (in the order of the arguments in Date)
256 // TODO: make this an @enum
270 * The value of datefield will start at an even multiple of "step", i.e.
271 * if datefield=SS and step=5 then the first tick will be on a multiple of 5s.
273 * For granularities <= HOURLY, ticks are generated every `spacing` ms.
275 * At coarser granularities, ticks are generated by incrementing `datefield` by
276 * `step`. In this case, the `spacing` value is only used to estimate the
277 * number of ticks. It should roughly correspond to the spacing between
280 * @type {Array.<{datefield:number, step:number, spacing:number}>}
282 var TICK_PLACEMENT
= [];
283 TICK_PLACEMENT
[Granularity
.MILLISECONDLY
] = {datefield
: DateField
.DATEFIELD_MS
, step
: 1, spacing
: 1};
284 TICK_PLACEMENT
[Granularity
.TWO_MILLISECONDLY
] = {datefield
: DateField
.DATEFIELD_MS
, step
: 2, spacing
: 2};
285 TICK_PLACEMENT
[Granularity
.FIVE_MILLISECONDLY
] = {datefield
: DateField
.DATEFIELD_MS
, step
: 5, spacing
: 5};
286 TICK_PLACEMENT
[Granularity
.TEN_MILLISECONDLY
] = {datefield
: DateField
.DATEFIELD_MS
, step
: 10, spacing
: 10};
287 TICK_PLACEMENT
[Granularity
.FIFTY_MILLISECONDLY
] = {datefield
: DateField
.DATEFIELD_MS
, step
: 50, spacing
: 50};
288 TICK_PLACEMENT
[Granularity
.HUNDRED_MILLISECONDLY
] = {datefield
: DateField
.DATEFIELD_MS
, step
: 100, spacing
: 100};
289 TICK_PLACEMENT
[Granularity
.FIVE_HUNDRED_MILLISECONDLY
] = {datefield
: DateField
.DATEFIELD_MS
, step
: 500, spacing
: 500};
290 TICK_PLACEMENT
[Granularity
.SECONDLY
] = {datefield
: DateField
.DATEFIELD_SS
, step
: 1, spacing
: 1000 * 1};
291 TICK_PLACEMENT
[Granularity
.TWO_SECONDLY
] = {datefield
: DateField
.DATEFIELD_SS
, step
: 2, spacing
: 1000 * 2};
292 TICK_PLACEMENT
[Granularity
.FIVE_SECONDLY
] = {datefield
: DateField
.DATEFIELD_SS
, step
: 5, spacing
: 1000 * 5};
293 TICK_PLACEMENT
[Granularity
.TEN_SECONDLY
] = {datefield
: DateField
.DATEFIELD_SS
, step
: 10, spacing
: 1000 * 10};
294 TICK_PLACEMENT
[Granularity
.THIRTY_SECONDLY
] = {datefield
: DateField
.DATEFIELD_SS
, step
: 30, spacing
: 1000 * 30};
295 TICK_PLACEMENT
[Granularity
.MINUTELY
] = {datefield
: DateField
.DATEFIELD_MM
, step
: 1, spacing
: 1000 * 60};
296 TICK_PLACEMENT
[Granularity
.TWO_MINUTELY
] = {datefield
: DateField
.DATEFIELD_MM
, step
: 2, spacing
: 1000 * 60 * 2};
297 TICK_PLACEMENT
[Granularity
.FIVE_MINUTELY
] = {datefield
: DateField
.DATEFIELD_MM
, step
: 5, spacing
: 1000 * 60 * 5};
298 TICK_PLACEMENT
[Granularity
.TEN_MINUTELY
] = {datefield
: DateField
.DATEFIELD_MM
, step
: 10, spacing
: 1000 * 60 * 10};
299 TICK_PLACEMENT
[Granularity
.THIRTY_MINUTELY
] = {datefield
: DateField
.DATEFIELD_MM
, step
: 30, spacing
: 1000 * 60 * 30};
300 TICK_PLACEMENT
[Granularity
.HOURLY
] = {datefield
: DateField
.DATEFIELD_HH
, step
: 1, spacing
: 1000 * 3600};
301 TICK_PLACEMENT
[Granularity
.TWO_HOURLY
] = {datefield
: DateField
.DATEFIELD_HH
, step
: 2, spacing
: 1000 * 3600 * 2};
302 TICK_PLACEMENT
[Granularity
.SIX_HOURLY
] = {datefield
: DateField
.DATEFIELD_HH
, step
: 6, spacing
: 1000 * 3600 * 6};
303 TICK_PLACEMENT
[Granularity
.DAILY
] = {datefield
: DateField
.DATEFIELD_D
, step
: 1, spacing
: 1000 * 86400};
304 TICK_PLACEMENT
[Granularity
.TWO_DAILY
] = {datefield
: DateField
.DATEFIELD_D
, step
: 2, spacing
: 1000 * 86400 * 2};
305 TICK_PLACEMENT
[Granularity
.WEEKLY
] = {datefield
: DateField
.DATEFIELD_D
, step
: 7, spacing
: 1000 * 604800};
306 TICK_PLACEMENT
[Granularity
.MONTHLY
] = {datefield
: DateField
.DATEFIELD_M
, step
: 1, spacing
: 1000 * 7200 * 365.2524}; // 1e3 * 60 * 60 * 24 * 365.2524 / 12
307 TICK_PLACEMENT
[Granularity
.QUARTERLY
] = {datefield
: DateField
.DATEFIELD_M
, step
: 3, spacing
: 1000 * 21600 * 365.2524}; // 1e3 * 60 * 60 * 24 * 365.2524 / 4
308 TICK_PLACEMENT
[Granularity
.BIANNUAL
] = {datefield
: DateField
.DATEFIELD_M
, step
: 6, spacing
: 1000 * 43200 * 365.2524}; // 1e3 * 60 * 60 * 24 * 365.2524 / 2
309 TICK_PLACEMENT
[Granularity
.ANNUAL
] = {datefield
: DateField
.DATEFIELD_Y
, step
: 1, spacing
: 1000 * 86400 * 365.2524}; // 1e3 * 60 * 60 * 24 * 365.2524 * 1
310 TICK_PLACEMENT
[Granularity
.DECADAL
] = {datefield
: DateField
.DATEFIELD_Y
, step
: 10, spacing
: 1000 * 864000 * 365.2524}; // 1e3 * 60 * 60 * 24 * 365.2524 * 10
311 TICK_PLACEMENT
[Granularity
.CENTENNIAL
] = {datefield
: DateField
.DATEFIELD_Y
, step
: 100, spacing
: 1000 * 8640000 * 365.2524}; // 1e3 * 60 * 60 * 24 * 365.2524 * 100
315 * This is a list of human-friendly values at which to show tick marks on a log
316 * scale. It is k * 10^n, where k=1..9 and n=-39..+39, so:
317 * ..., 1, 2, 3, 4, 5, ..., 9, 10, 20, 30, ..., 90, 100, 200, 300, ...
318 * NOTE: this assumes that utils.LOG_SCALE = 10.
319 * @type {Array.<number>}
321 var PREFERRED_LOG_TICK_VALUES
= (function() {
323 for (var power
= -39; power
<= 39; power
++) {
324 var range
= Math
.pow(10, power
);
325 for (var mult
= 1; mult
<= 9; mult
++) {
326 var val
= range
* mult
;
334 * Determine the correct granularity of ticks on a date axis.
336 * @param {number} a Left edge of the chart (ms)
337 * @param {number} b Right edge of the chart (ms)
338 * @param {number} pixels Size of the chart in the relevant dimension (width).
339 * @param {function(string):*} opts Function mapping from option name -> value.
340 * @return {number} The appropriate axis granularity for this chart. See the
341 * enumeration of possible values in dygraph-tickers.js.
343 var pickDateTickGranularity
= function(a
, b
, pixels
, opts
) {
344 var pixels_per_tick
= /** @type{number} */(opts('pixelsPerLabel'));
345 for (var i
= 0; i
< Granularity
.NUM_GRANULARITIES
; i
++) {
346 var num_ticks
= numDateTicks(a
, b
, i
);
347 if (pixels
/ num_ticks
>= pixels_per_tick
) {
355 * Compute the number of ticks on a date axis for a given granularity.
356 * @param {number} start_time
357 * @param {number} end_time
358 * @param {number} granularity (one of the granularities enumerated above)
359 * @return {number} (Approximate) number of ticks that would result.
361 var numDateTicks
= function(start_time
, end_time
, granularity
) {
362 var spacing
= TICK_PLACEMENT
[granularity
].spacing
;
363 return Math
.round(1.0 * (end_time
- start_time
) / spacing
);
367 * Compute the positions and labels of ticks on a date axis for a given granularity.
368 * @param {number} start_time
369 * @param {number} end_time
370 * @param {number} granularity (one of the granularities enumerated above)
371 * @param {function(string):*} opts Function mapping from option name -> value.
372 * @param {Dygraph=} dg
373 * @return {!TickList}
375 export var getDateAxis
= function(start_time
, end_time
, granularity
, opts
, dg
) {
376 var formatter
= /** @type{AxisLabelFormatter} */(
377 opts("axisLabelFormatter"));
378 var utc
= opts("labelsUTC");
379 var accessors
= utc
? utils
.DateAccessorsUTC
: utils
.DateAccessorsLocal
;
381 var datefield
= TICK_PLACEMENT
[granularity
].datefield
;
382 var step
= TICK_PLACEMENT
[granularity
].step
;
383 var spacing
= TICK_PLACEMENT
[granularity
].spacing
;
385 // Choose a nice tick position before the initial instant.
386 // Currently, this code deals properly with the existent daily granularities:
387 // DAILY (with step of 1) and WEEKLY (with step of 7 but specially handled).
388 // Other daily granularities (say TWO_DAILY) should also be handled specially
389 // by setting the start_date_offset to 0.
390 var start_date
= new Date(start_time
);
392 date_array
[DateField
.DATEFIELD_Y
] = accessors
.getFullYear(start_date
);
393 date_array
[DateField
.DATEFIELD_M
] = accessors
.getMonth(start_date
);
394 date_array
[DateField
.DATEFIELD_D
] = accessors
.getDate(start_date
);
395 date_array
[DateField
.DATEFIELD_HH
] = accessors
.getHours(start_date
);
396 date_array
[DateField
.DATEFIELD_MM
] = accessors
.getMinutes(start_date
);
397 date_array
[DateField
.DATEFIELD_SS
] = accessors
.getSeconds(start_date
);
398 date_array
[DateField
.DATEFIELD_MS
] = accessors
.getMilliseconds(start_date
);
400 var start_date_offset
= date_array
[datefield
] % step
;
401 if (granularity
== Granularity
.WEEKLY
) {
402 // This will put the ticks on Sundays.
403 start_date_offset
= accessors
.getDay(start_date
);
406 date_array
[datefield
] -= start_date_offset
;
407 for (var df
= datefield
+ 1; df
< DateField
.NUM_DATEFIELDS
; df
++) {
408 // The minimum value is 1 for the day of month, and 0 for all other fields.
409 date_array
[df
] = (df
=== DateField
.DATEFIELD_D
) ? 1 : 0;
412 // Generate the ticks.
413 // For granularities not coarser than HOURLY we use the fact that:
414 // the number of milliseconds between ticks is constant
415 // and equal to the defined spacing.
416 // Otherwise we rely on the 'roll over' property of the Date functions:
417 // when some date field is set to a value outside of its logical range,
418 // the excess 'rolls over' the next (more significant) field.
419 // However, when using local time with DST transitions,
420 // there are dates that do not represent any time value at all
421 // (those in the hour skipped at the 'spring forward'),
422 // and the JavaScript engines usually return an equivalent value.
423 // Hence we have to check that the date is properly increased at each step,
424 // returning a date at a nice tick position.
426 var tick_date
= accessors
.makeDate
.apply(null, date_array
);
427 var tick_time
= tick_date
.getTime();
428 if (granularity
<= Granularity
.HOURLY
) {
429 if (tick_time
< start_time
) {
430 tick_time
+= spacing
;
431 tick_date
= new Date(tick_time
);
433 while (tick_time
<= end_time
) {
434 ticks
.push({ v
: tick_time
,
435 label
: formatter
.call(dg
, tick_date
, granularity
, opts
, dg
)
437 tick_time
+= spacing
;
438 tick_date
= new Date(tick_time
);
441 if (tick_time
< start_time
) {
442 date_array
[datefield
] += step
;
443 tick_date
= accessors
.makeDate
.apply(null, date_array
);
444 tick_time
= tick_date
.getTime();
446 while (tick_time
<= end_time
) {
447 if (granularity
>= Granularity
.DAILY
||
448 accessors
.getHours(tick_date
) % step
=== 0) {
449 ticks
.push({ v
: tick_time
,
450 label
: formatter
.call(dg
, tick_date
, granularity
, opts
, dg
)
453 date_array
[datefield
] += step
;
454 tick_date
= accessors
.makeDate
.apply(null, date_array
);
455 tick_time
= tick_date
.getTime();