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 // This masks some numeric issues in older versions of Firefox,
91 // where 1.0/Math
.pow(10,2) != Math
.pow(10,-2).
92 /** @type {function(number,number):number} */
93 var pow
= function(base
, exp
) {
95 return 1.0 / Math
.pow(base
, -exp
);
97 return Math
.pow(base
, exp
);
100 var pixels_per_tick
= /** @type{number} */(opts('pixelsPerLabel'));
102 var i
, j
, tickV
, nTicks
;
104 for (i
= 0; i
< vals
.length
; i
++) {
105 ticks
.push({v
: vals
[i
]});
108 // TODO(danvk): factor this log-scale block out into a separate function.
109 if (opts("logscale")) {
110 nTicks
= Math
.floor(pixels
/ pixels_per_tick
);
111 var minIdx
= Dygraph
.binarySearch(a
, Dygraph
.PREFERRED_LOG_TICK_VALUES
, 1);
112 var maxIdx
= Dygraph
.binarySearch(b
, Dygraph
.PREFERRED_LOG_TICK_VALUES
, -1);
117 maxIdx
= Dygraph
.PREFERRED_LOG_TICK_VALUES
.length
- 1;
119 // Count the number of tick values would appear, if we can get at least
120 // nTicks / 4 accept them
.
121 var lastDisplayed
= null;
122 if (maxIdx
- minIdx
>= nTicks
/ 4) {
123 for (var idx
= maxIdx
; idx
>= minIdx
; idx
--) {
124 var tickValue
= Dygraph
.PREFERRED_LOG_TICK_VALUES
[idx
];
125 var pixel_coord
= Math
.log(tickValue
/ a) / Math
.log(b
/ a
) * pixels
;
126 var tick
= { v
: tickValue
};
127 if (lastDisplayed
=== null) {
129 tickValue
: tickValue
,
130 pixel_coord
: pixel_coord
133 if (Math
.abs(pixel_coord
- lastDisplayed
.pixel_coord
) >= pixels_per_tick
) {
135 tickValue
: tickValue
,
136 pixel_coord
: pixel_coord
144 // Since we went in backwards order.
149 // ticks.length won't be 0 if the log scale function finds values to insert.
150 if (ticks
.length
=== 0) {
152 // Try labels every 1, 2, 5, 10, 20, 50, 100, etc.
153 // Calculate the resulting tick spacing (i.e. this.height_ / nTicks
).
154 // The first spacing greater than pixelsPerYLabel is what we use.
155 // TODO(danvk): version that works on a log scale.
156 var kmg2
= opts("labelsKMG2");
159 mults
= [1, 2, 4, 8, 16, 32, 64, 128, 256];
162 mults
= [1, 2, 5, 10, 20, 50, 100];
166 // Get the maximum number of permitted ticks based on the
167 // graph's pixel size and pixels_per_tick setting.
168 var max_ticks
= Math
.ceil(pixels
/ pixels_per_tick
);
170 // Now calculate the data unit equivalent of this tick spacing.
171 // Use abs() since graphs may have a reversed Y axis.
172 var units_per_tick
= Math
.abs(b
- a
) / max_ticks
;
174 // Based on this, get a starting scale which is the largest
175 // integer power of the chosen base (10 or 16) that still remains
176 // below the requested pixels_per_tick spacing.
177 var base_power
= Math
.floor(Math
.log(units_per_tick
) / Math
.log(base
));
178 var base_scale
= Math
.pow(base
, base_power
);
180 // Now try multiples of the starting scale until we find one
181 // that results in tick marks spaced sufficiently far apart.
182 // The "mults" array should cover the range 1 .. base^2 to
183 // adjust for rounding and edge effects.
184 var scale
, low_val
, high_val
, spacing
;
185 for (j
= 0; j
< mults
.length
; j
++) {
186 scale
= base_scale
* mults
[j
];
187 low_val
= Math
.floor(a
/ scale
) * scale
;
188 high_val
= Math
.ceil(b
/ scale
) * scale
;
189 nTicks
= Math
.abs(high_val
- low_val
) / scale
;
190 spacing
= pixels
/ nTicks
;
191 if (spacing
> pixels_per_tick
) break;
194 // Construct the set of ticks.
195 // Allow reverse y-axis if it's explicitly requested.
196 if (low_val
> high_val
) scale
*= -1;
197 for (i
= 0; i
< nTicks
; i
++) {
198 tickV
= low_val
+ i
* scale
;
199 ticks
.push( {v
: tickV
} );
204 // Add formatted labels to the ticks.
208 if (opts("labelsKMB")) {
210 k_labels
= [ "K", "M", "B", "T", "Q" ];
212 if (opts("labelsKMG2")) {
213 if (k
) Dygraph
.warn("Setting both labelsKMB and labelsKMG2. Pick one!");
215 k_labels
= [ "k", "M", "G", "T", "P", "E", "Z", "Y" ];
216 m_labels
= [ "m", "u", "n", "p", "f", "a", "z", "y" ];
219 k
= k
|| 1; // If neither option is specified.
221 var formatter
= /**@type{AxisLabelFormatter}*/(opts('axisLabelFormatter'));
223 // Add labels to the ticks.
224 var digitsAfterDecimal
= /** @type{number} */(opts('digitsAfterDecimal'));
225 for (i
= 0; i
< ticks
.length
; i
++) {
226 if (ticks
[i
].label
!== undefined
) continue; // Use current label.
228 var absTickV
= Math
.abs(tickV
);
229 // TODO(danvk): set granularity to something appropriate here.
230 var label
= formatter(tickV
, 0, opts
, dygraph
);
231 if (k_labels
.length
> 0) {
232 // TODO(danvk): should this be integrated into the axisLabelFormatter?
233 // Round up to an appropriate unit.
234 var n
= pow(k
, k_labels
.length
);
235 for (j
= k_labels
.length
- 1; j
>= 0; j
--, n
/= k
) {
237 label
= Dygraph
.round_(tickV
/ n
, digitsAfterDecimal
) + k_labels
[j
];
242 if(opts("labelsKMG2")){
243 tickV
= String(tickV
.toExponential());
244 if(tickV
.split('e-').length
=== 2 && tickV
.split('e-')[1] >= 3 && tickV
.split('e-')[1] <= 24){
245 if(tickV
.split('e-')[1] % 3 > 0) {
246 label
= Dygraph
.round_(tickV
.split('e-')[0] /
247 pow(10,(tickV
.split('e-')[1] % 3)),
250 label
= Number(tickV
.split('e-')[0]).toFixed(2);
252 label
+= m_labels
[Math
.floor(tickV
.split('e-')[1] / 3) - 1];
255 ticks
[i
].label
= label
;
262 /** @type {Dygraph.Ticker} */
263 Dygraph
.dateTicker
= function(a
, b
, pixels
, opts
, dygraph
, vals
) {
264 var chosen
= Dygraph
.pickDateTickGranularity(a
, b
, pixels
, opts
);
267 return Dygraph
.getDateAxis(a
, b
, chosen
, opts
, dygraph
);
269 // this can happen if self.width_ is zero.
274 // Time granularity enumeration
275 // TODO(danvk): make this an @enum
276 Dygraph
.SECONDLY
= 0;
277 Dygraph
.TWO_SECONDLY
= 1;
278 Dygraph
.FIVE_SECONDLY
= 2;
279 Dygraph
.TEN_SECONDLY
= 3;
280 Dygraph
.THIRTY_SECONDLY
= 4;
281 Dygraph
.MINUTELY
= 5;
282 Dygraph
.TWO_MINUTELY
= 6;
283 Dygraph
.FIVE_MINUTELY
= 7;
284 Dygraph
.TEN_MINUTELY
= 8;
285 Dygraph
.THIRTY_MINUTELY
= 9;
287 Dygraph
.TWO_HOURLY
= 11;
288 Dygraph
.SIX_HOURLY
= 12;
291 Dygraph
.MONTHLY
= 15;
292 Dygraph
.QUARTERLY
= 16;
293 Dygraph
.BIANNUAL
= 17;
295 Dygraph
.DECADAL
= 19;
296 Dygraph
.CENTENNIAL
= 20;
297 Dygraph
.NUM_GRANULARITIES
= 21;
299 /** @type {Array.<number>} */
300 Dygraph
.SHORT_SPACINGS
= [];
301 Dygraph
.SHORT_SPACINGS
[Dygraph
.SECONDLY
] = 1000 * 1;
302 Dygraph
.SHORT_SPACINGS
[Dygraph
.TWO_SECONDLY
] = 1000 * 2;
303 Dygraph
.SHORT_SPACINGS
[Dygraph
.FIVE_SECONDLY
] = 1000 * 5;
304 Dygraph
.SHORT_SPACINGS
[Dygraph
.TEN_SECONDLY
] = 1000 * 10;
305 Dygraph
.SHORT_SPACINGS
[Dygraph
.THIRTY_SECONDLY
] = 1000 * 30;
306 Dygraph
.SHORT_SPACINGS
[Dygraph
.MINUTELY
] = 1000 * 60;
307 Dygraph
.SHORT_SPACINGS
[Dygraph
.TWO_MINUTELY
] = 1000 * 60 * 2;
308 Dygraph
.SHORT_SPACINGS
[Dygraph
.FIVE_MINUTELY
] = 1000 * 60 * 5;
309 Dygraph
.SHORT_SPACINGS
[Dygraph
.TEN_MINUTELY
] = 1000 * 60 * 10;
310 Dygraph
.SHORT_SPACINGS
[Dygraph
.THIRTY_MINUTELY
] = 1000 * 60 * 30;
311 Dygraph
.SHORT_SPACINGS
[Dygraph
.HOURLY
] = 1000 * 3600;
312 Dygraph
.SHORT_SPACINGS
[Dygraph
.TWO_HOURLY
] = 1000 * 3600 * 2;
313 Dygraph
.SHORT_SPACINGS
[Dygraph
.SIX_HOURLY
] = 1000 * 3600 * 6;
314 Dygraph
.SHORT_SPACINGS
[Dygraph
.DAILY
] = 1000 * 86400;
315 Dygraph
.SHORT_SPACINGS
[Dygraph
.WEEKLY
] = 1000 * 604800;
318 * This is a list of human-friendly values at which to show tick marks on a log
319 * scale. It is k * 10^n, where k=1..9 and n=-39..+39, so:
320 * ..., 1, 2, 3, 4, 5, ..., 9, 10, 20, 30, ..., 90, 100, 200, 300, ...
321 * NOTE: this assumes that Dygraph.LOG_SCALE = 10.
322 * @type {Array.<number>}
324 Dygraph
.PREFERRED_LOG_TICK_VALUES
= function() {
326 for (var power
= -39; power
<= 39; power
++) {
327 var range
= Math
.pow(10, power
);
328 for (var mult
= 1; mult
<= 9; mult
++) {
329 var val
= range
* mult
;
337 * Determine the correct granularity of ticks on a date axis.
339 * @param {number} a Left edge of the chart (ms)
340 * @param {number} b Right edge of the chart (ms)
341 * @param {number} pixels Size of the chart in the relevant dimension (width).
342 * @param {function(string):*} opts Function mapping from option name ->
344 * @return {number} The appropriate axis granularity for this chart. See the
345 * enumeration of possible values in dygraph-tickers.js.
347 Dygraph
.pickDateTickGranularity
= function(a
, b
, pixels
, opts
) {
348 var pixels_per_tick
= /** @type{number} */(opts('pixelsPerLabel'));
349 for (var i
= 0; i
< Dygraph
.NUM_GRANULARITIES
; i
++) {
350 var num_ticks
= Dygraph
.numDateTicks(a
, b
, i
);
351 if (pixels
/ num_ticks
>= pixels_per_tick
) {
359 * @param {number} start_time
360 * @param {number} end_time
361 * @param {number} granularity (one of the granularities enumerated above)
362 * @return {number} Number of ticks that would result.
364 Dygraph
.numDateTicks
= function(start_time
, end_time
, granularity
) {
365 if (granularity
< Dygraph
.MONTHLY
) {
366 // Generate one tick mark for every fixed interval of time.
367 var spacing
= Dygraph
.SHORT_SPACINGS
[granularity
];
368 return Math
.floor(0.5 + 1.0 * (end_time
- start_time
) / spacing
);
370 var year_mod
= 1; // e.g. to only print one point every 10 years.
372 if (granularity
== Dygraph
.QUARTERLY
) num_months
= 3;
373 if (granularity
== Dygraph
.BIANNUAL
) num_months
= 2;
374 if (granularity
== Dygraph
.ANNUAL
) num_months
= 1;
375 if (granularity
== Dygraph
.DECADAL
) { num_months
= 1; year_mod
= 10; }
376 if (granularity
== Dygraph
.CENTENNIAL
) { num_months
= 1; year_mod
= 100; }
378 var msInYear
= 365.2524 * 24 * 3600 * 1000;
379 var num_years
= 1.0 * (end_time
- start_time
) / msInYear
;
380 return Math
.floor(0.5 + 1.0 * num_years
* num_months
/ year_mod
);
385 * @param {number} start_time
386 * @param {number} end_time
387 * @param {number} granularity (one of the granularities enumerated above)
388 * @param {function(string):*} opts Function mapping from option name -> value.
389 * @param {Dygraph=} dg
390 * @return {!Dygraph.TickList}
392 Dygraph
.getDateAxis
= function(start_time
, end_time
, granularity
, opts
, dg
) {
393 var formatter
= /** @type{AxisLabelFormatter} */(
394 opts("axisLabelFormatter"));
398 if (granularity
< Dygraph
.MONTHLY
) {
399 // Generate one tick mark for every fixed interval of time.
400 var spacing
= Dygraph
.SHORT_SPACINGS
[granularity
];
402 // Find a time less than start_time which occurs on a "nice" time boundary
403 // for this granularity.
404 var g
= spacing
/ 1000;
405 var d
= new Date(start_time
);
406 d
.setMilliseconds(0);
408 if (g
<= 60) { // seconds
409 x
= d
.getSeconds(); d
.setSeconds(x
- x
% g
);
413 if (g
<= 60) { // minutes
414 x
= d
.getMinutes(); d
.setMinutes(x
- x
% g
);
419 if (g
<= 24) { // days
420 x
= d
.getHours(); d
.setHours(x
- x
% g
);
425 if (g
== 7) { // one week
426 d
.setDate(d
.getDate() - d
.getDay());
431 start_time
= d
.getTime();
433 for (t
= start_time
; t
<= end_time
; t
+= spacing
) {
435 label
: formatter(new Date(t
), granularity
, opts
, dg
)
439 // Display a tick mark on the first of a set of months of each year.
440 // Years get a tick mark iff y % year_mod == 0. This is useful for
441 // displaying a tick mark once every 10 years, say, on long time scales.
443 var year_mod
= 1; // e.g. to only print one point every 10 years.
445 if (granularity
== Dygraph
.MONTHLY
) {
446 months
= [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11 ];
447 } else if (granularity
== Dygraph
.QUARTERLY
) {
448 months
= [ 0, 3, 6, 9 ];
449 } else if (granularity
== Dygraph
.BIANNUAL
) {
451 } else if (granularity
== Dygraph
.ANNUAL
) {
453 } else if (granularity
== Dygraph
.DECADAL
) {
456 } else if (granularity
== Dygraph
.CENTENNIAL
) {
460 Dygraph
.warn("Span of dates is too long");
463 var start_year
= new Date(start_time
).getFullYear();
464 var end_year
= new Date(end_time
).getFullYear();
465 var zeropad
= Dygraph
.zeropad
;
466 for (var i
= start_year
; i
<= end_year
; i
++) {
467 if (i
% year_mod
!== 0) continue;
468 for (var j
= 0; j
< months
.length
; j
++) {
469 var date_str
= i
+ "/" + zeropad(1 + months[j]) + "/01";
470 t
= Dygraph
.dateStrToMillis(date_str
);
471 if (t
< start_time
|| t
> end_time
) continue;
473 label
: formatter(new Date(t
), granularity
, opts
, dg
)
482 // These are set here so that this file can be included after dygraph.js.
483 Dygraph
.DEFAULT_ATTRS
['axes']['x']['ticker'] = Dygraph
.dateTicker
;
484 Dygraph
.DEFAULT_ATTRS
['axes']['y']['ticker'] = Dygraph
.numericTicks
;
485 Dygraph
.DEFAULT_ATTRS
['axes']['y2']['ticker'] = Dygraph
.numericTicks
;