1 // Copyright 2011 Google Inc. All Rights Reserved.
2 // MIT-licensed (http://opensource.org/licenses/MIT
)
5 * @fileoverview Description of this file.
6 * @author danvk@google.com (Dan Vanderkam)
8 * A ticker is a function with the following interface:
10 * function(a, b, pixels, options_view, dygraph, forced_values);
11 * -> [ { v: tick1_v, label: tick1_label[, label_v: label_v1] },
12 * { v: tick2_v, label: tick2_label[, label_v: label_v2] },
16 * The returned value is called a "tick list".
21 * [a, b] is the range of the axis for which ticks are being generated. For a
22 * numeric axis, these will simply be numbers. For a date axis, these will be
23 * millis since epoch (convertable to Date objects using "new Date(a)" and "new
26 * opts provides access to chart- and axis-specific options. It can be used to
27 * access number/date formatting code/options, check for a log scale, etc.
29 * pixels is the length of the axis in pixels. opts('pixelsPerLabel') is the
30 * minimum amount of space to be allotted to each label. For instance, if
31 * pixels=400 and opts('pixelsPerLabel')=40 then the ticker should return
32 * between zero and ten (400/40) ticks.
34 * dygraph is the Dygraph object for which an axis is being constructed.
36 * forced_values is used for secondary y-axes. The tick positions are typically
37 * set by the primary y-axis, so the secondary y-axis has no choice in where to
38 * put these. It simply has to generate labels for these data values.
42 * Typically a tick will have both a grid/tick line and a label at one end of
43 * that line (at the bottom for an x-axis, at left or right for the y-axis).
45 * A tick may be missing one of these two components:
46 * - If "label_v" is specified instead of "v", then there will be no tick or
47 * gridline, just a label.
48 * - Similarly, if "label" is not specified, then there will be a gridline
51 * This flexibility is useful in a few situations:
52 * - For log scales, some of the tick lines may be too close to all have labels.
53 * - For date scales where years are being displayed, it is desirable to display
54 * tick marks at the beginnings of years but labels (e.g. "2006") in the
55 * middle of the years.
58 Dygraph
.numericTicks
= function(a
, b
, pixels
, opts
, dygraph
, vals
) {
59 var pixels_per_tick
= opts('pixelsPerLabel');
62 for (var i
= 0; i
< vals
.length
; i
++) {
63 ticks
.push({v
: vals
[i
]});
66 // TODO(danvk): factor this log-scale block out into a separate function.
67 if (opts("logscale")) {
68 var nTicks
= Math
.floor(pixels
/ pixels_per_tick
);
69 var minIdx
= Dygraph
.binarySearch(a
, Dygraph
.PREFERRED_LOG_TICK_VALUES
, 1);
70 var maxIdx
= Dygraph
.binarySearch(b
, Dygraph
.PREFERRED_LOG_TICK_VALUES
, -1);
75 maxIdx
= Dygraph
.PREFERRED_LOG_TICK_VALUES
.length
- 1;
77 // Count the number of tick values would appear, if we can get at least
78 // nTicks / 4 accept them
.
79 var lastDisplayed
= null;
80 if (maxIdx
- minIdx
>= nTicks
/ 4) {
81 for (var idx
= maxIdx
; idx
>= minIdx
; idx
--) {
82 var tickValue
= Dygraph
.PREFERRED_LOG_TICK_VALUES
[idx
];
83 var pixel_coord
= Math
.log(tickValue
/ a) / Math
.log(b
/ a
) * pixels
;
84 var tick
= { v
: tickValue
};
85 if (lastDisplayed
== null) {
87 tickValue
: tickValue
,
88 pixel_coord
: pixel_coord
91 if (Math
.abs(pixel_coord
- lastDisplayed
.pixel_coord
) >= pixels_per_tick
) {
93 tickValue
: tickValue
,
94 pixel_coord
: pixel_coord
102 // Since we went in backwards order.
107 // ticks.length won't be 0 if the log scale function finds values to insert.
108 if (ticks
.length
== 0) {
110 // Try labels every 1, 2, 5, 10, 20, 50, 100, etc.
111 // Calculate the resulting tick spacing (i.e. this.height_ / nTicks
).
112 // The first spacing greater than pixelsPerYLabel is what we use.
113 // TODO(danvk): version that works on a log scale.
114 var kmg2
= opts("labelsKMG2");
116 var mults
= [1, 2, 4, 8];
118 var mults
= [1, 2, 5];
120 var scale
, low_val
, high_val
, nTicks
;
121 for (var i
= -10; i
< 50; i
++) {
123 var base_scale
= Math
.pow(16, i
);
125 var base_scale
= Math
.pow(10, i
);
127 for (var j
= 0; j
< mults
.length
; j
++) {
128 scale
= base_scale
* mults
[j
];
129 low_val
= Math
.floor(a
/ scale
) * scale
;
130 high_val
= Math
.ceil(b
/ scale
) * scale
;
131 nTicks
= Math
.abs(high_val
- low_val
) / scale
;
132 var spacing
= pixels
/ nTicks
;
133 // wish I could break out of both loops at once...
134 if (spacing
> pixels_per_tick
) break;
136 if (spacing
> pixels_per_tick
) break;
139 // Construct the set of ticks.
140 // Allow reverse y-axis if it's explicitly requested.
141 if (low_val
> high_val
) scale
*= -1;
142 for (var i
= 0; i
< nTicks
; i
++) {
143 var tickV
= low_val
+ i
* scale
;
144 ticks
.push( {v
: tickV
} );
149 // Add formatted labels to the ticks.
152 if (opts("labelsKMB")) {
154 k_labels
= [ "K", "M", "B", "T" ];
156 if (opts("labelsKMG2")) {
157 if (k
) self
.warn("Setting both labelsKMB and labelsKMG2. Pick one!");
159 k_labels
= [ "k", "M", "G", "T" ];
162 var formatter
= opts('axisLabelFormatter');
164 // Add labels to the ticks.
165 for (var i
= 0; i
< ticks
.length
; i
++) {
166 if (ticks
[i
].label
!== undefined
) continue; // Use current label.
167 var tickV
= ticks
[i
].v
;
168 var absTickV
= Math
.abs(tickV
);
169 // TODO(danvk): set granularity to something appropriate here.
170 var label
= formatter(tickV
, 0, opts
, dygraph
);
171 if (k_labels
.length
> 0) {
172 // TODO(danvk): should this be integrated into the axisLabelFormatter?
173 // Round up to an appropriate unit.
175 for (var j
= 3; j
>= 0; j
--, n
/= k
) {
177 label
= Dygraph
.round_(tickV
/ n
, opts('digitsAfterDecimal')) +
183 ticks
[i
].label
= label
;
190 Dygraph
.dateTicker
= function(a
, b
, pixels
, opts
, dygraph
, vals
) {
191 var pixels_per_tick
= opts('pixelsPerLabel');
193 for (var i
= 0; i
< Dygraph
.NUM_GRANULARITIES
; i
++) {
194 var num_ticks
= Dygraph
.numDateTicks(a
, b
, i
);
195 if (pixels
/ num_ticks
>= pixels_per_tick
) {
202 return Dygraph
.getDateAxis(a
, b
, chosen
, opts
, dygraph
);
204 // this can happen if self.width_ is zero.
209 // Time granularity enumeration
210 Dygraph
.SECONDLY
= 0;
211 Dygraph
.TWO_SECONDLY
= 1;
212 Dygraph
.FIVE_SECONDLY
= 2;
213 Dygraph
.TEN_SECONDLY
= 3;
214 Dygraph
.THIRTY_SECONDLY
= 4;
215 Dygraph
.MINUTELY
= 5;
216 Dygraph
.TWO_MINUTELY
= 6;
217 Dygraph
.FIVE_MINUTELY
= 7;
218 Dygraph
.TEN_MINUTELY
= 8;
219 Dygraph
.THIRTY_MINUTELY
= 9;
221 Dygraph
.TWO_HOURLY
= 11;
222 Dygraph
.SIX_HOURLY
= 12;
225 Dygraph
.MONTHLY
= 15;
226 Dygraph
.QUARTERLY
= 16;
227 Dygraph
.BIANNUAL
= 17;
229 Dygraph
.DECADAL
= 19;
230 Dygraph
.CENTENNIAL
= 20;
231 Dygraph
.NUM_GRANULARITIES
= 21;
233 Dygraph
.SHORT_SPACINGS
= [];
234 Dygraph
.SHORT_SPACINGS
[Dygraph
.SECONDLY
] = 1000 * 1;
235 Dygraph
.SHORT_SPACINGS
[Dygraph
.TWO_SECONDLY
] = 1000 * 2;
236 Dygraph
.SHORT_SPACINGS
[Dygraph
.FIVE_SECONDLY
] = 1000 * 5;
237 Dygraph
.SHORT_SPACINGS
[Dygraph
.TEN_SECONDLY
] = 1000 * 10;
238 Dygraph
.SHORT_SPACINGS
[Dygraph
.THIRTY_SECONDLY
] = 1000 * 30;
239 Dygraph
.SHORT_SPACINGS
[Dygraph
.MINUTELY
] = 1000 * 60;
240 Dygraph
.SHORT_SPACINGS
[Dygraph
.TWO_MINUTELY
] = 1000 * 60 * 2;
241 Dygraph
.SHORT_SPACINGS
[Dygraph
.FIVE_MINUTELY
] = 1000 * 60 * 5;
242 Dygraph
.SHORT_SPACINGS
[Dygraph
.TEN_MINUTELY
] = 1000 * 60 * 10;
243 Dygraph
.SHORT_SPACINGS
[Dygraph
.THIRTY_MINUTELY
] = 1000 * 60 * 30;
244 Dygraph
.SHORT_SPACINGS
[Dygraph
.HOURLY
] = 1000 * 3600;
245 Dygraph
.SHORT_SPACINGS
[Dygraph
.TWO_HOURLY
] = 1000 * 3600 * 2;
246 Dygraph
.SHORT_SPACINGS
[Dygraph
.SIX_HOURLY
] = 1000 * 3600 * 6;
247 Dygraph
.SHORT_SPACINGS
[Dygraph
.DAILY
] = 1000 * 86400;
248 Dygraph
.SHORT_SPACINGS
[Dygraph
.WEEKLY
] = 1000 * 604800;
252 * This is a list of human-friendly values at which to show tick marks on a log
253 * scale. It is k * 10^n, where k=1..9 and n=-39..+39, so:
254 * ..., 1, 2, 3, 4, 5, ..., 9, 10, 20, 30, ..., 90, 100, 200, 300, ...
255 * NOTE: this assumes that Dygraph.LOG_SCALE = 10.
257 Dygraph
.PREFERRED_LOG_TICK_VALUES
= function() {
259 for (var power
= -39; power
<= 39; power
++) {
260 var range
= Math
.pow(10, power
);
261 for (var mult
= 1; mult
<= 9; mult
++) {
262 var val
= range
* mult
;
269 Dygraph
.numDateTicks
= function(start_time
, end_time
, granularity
) {
270 if (granularity
< Dygraph
.MONTHLY
) {
271 // Generate one tick mark for every fixed interval of time.
272 var spacing
= Dygraph
.SHORT_SPACINGS
[granularity
];
273 return Math
.floor(0.5 + 1.0 * (end_time
- start_time
) / spacing
);
275 var year_mod
= 1; // e.g. to only print one point every 10 years.
277 if (granularity
== Dygraph
.QUARTERLY
) num_months
= 3;
278 if (granularity
== Dygraph
.BIANNUAL
) num_months
= 2;
279 if (granularity
== Dygraph
.ANNUAL
) num_months
= 1;
280 if (granularity
== Dygraph
.DECADAL
) { num_months
= 1; year_mod
= 10; }
281 if (granularity
== Dygraph
.CENTENNIAL
) { num_months
= 1; year_mod
= 100; }
283 var msInYear
= 365.2524 * 24 * 3600 * 1000;
284 var num_years
= 1.0 * (end_time
- start_time
) / msInYear
;
285 return Math
.floor(0.5 + 1.0 * num_years
* num_months
/ year_mod
);
289 Dygraph
.getDateAxis
= function(start_time
, end_time
, granularity
, opts
, dg
) {
290 var formatter
= opts("axisLabelFormatter");
292 if (granularity
< Dygraph
.MONTHLY
) {
293 // Generate one tick mark for every fixed interval of time.
294 var spacing
= Dygraph
.SHORT_SPACINGS
[granularity
];
295 var format
= '%d%b'; // e.g. "1Jan"
297 // Find a time less than start_time which occurs on a "nice" time boundary
298 // for this granularity.
299 var g
= spacing
/ 1000;
300 var d
= new Date(start_time
);
301 if (g
<= 60) { // seconds
302 var x
= d
.getSeconds(); d
.setSeconds(x
- x
% g
);
306 if (g
<= 60) { // minutes
307 var x
= d
.getMinutes(); d
.setMinutes(x
- x
% g
);
312 if (g
<= 24) { // days
313 var x
= d
.getHours(); d
.setHours(x
- x
% g
);
318 if (g
== 7) { // one week
319 d
.setDate(d
.getDate() - d
.getDay());
324 start_time
= d
.getTime();
326 for (var t
= start_time
; t
<= end_time
; t
+= spacing
) {
328 label
: formatter(new Date(t
), granularity
, opts
, dg
)
332 // Display a tick mark on the first of a set of months of each year.
333 // Years get a tick mark iff y % year_mod == 0. This is useful for
334 // displaying a tick mark once every 10 years, say, on long time scales.
336 var year_mod
= 1; // e.g. to only print one point every 10 years.
338 if (granularity
== Dygraph
.MONTHLY
) {
339 months
= [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 ];
340 } else if (granularity
== Dygraph
.QUARTERLY
) {
341 months
= [ 0, 3, 6, 9 ];
342 } else if (granularity
== Dygraph
.BIANNUAL
) {
344 } else if (granularity
== Dygraph
.ANNUAL
) {
346 } else if (granularity
== Dygraph
.DECADAL
) {
349 } else if (granularity
== Dygraph
.CENTENNIAL
) {
353 Dygraph
.warn("Span of dates is too long");
356 var start_year
= new Date(start_time
).getFullYear();
357 var end_year
= new Date(end_time
).getFullYear();
358 var zeropad
= Dygraph
.zeropad
;
359 for (var i
= start_year
; i
<= end_year
; i
++) {
360 if (i
% year_mod
!= 0) continue;
361 for (var j
= 0; j
< months
.length
; j
++) {
362 var date_str
= i
+ "/" + zeropad(1 + months[j]) + "/01";
363 var t
= Dygraph
.dateStrToMillis(date_str
);
364 if (t
< start_time
|| t
> end_time
) continue;
366 label
: formatter(new Date(t
), granularity
, opts
, dg
)
375 // These are set here so that this file can be included after dygraph.js.
376 Dygraph
.DEFAULT_ATTRS
.axes
.x
.ticker
= Dygraph
.dateTicker
;
377 Dygraph
.DEFAULT_ATTRS
.axes
.y
.ticker
= Dygraph
.numericTicks
;
378 Dygraph
.DEFAULT_ATTRS
.axes
.y2
.ticker
= Dygraph
.numericTicks
;