3 * Copyright 2013 David Eberlein (david.eberlein@ch.sauter-bc.com)
4 * MIT-licensed (http://opensource.org/licenses/MIT)
8 * @fileoverview This file contains the managment of data handlers
9 * @author David Eberlein (david.eberlein@ch.sauter-bc.com)
11 * The idea is to define a common, generic data format that works for all data
12 * structures supported by dygraphs. To make this possible, the DataHandler
13 * interface is introduced. This makes it possible, that dygraph itself can work
14 * with the same logic for every data type independent of the actual format and
15 * the DataHandler takes care of the data format specific jobs.
16 * DataHandlers are implemented for all data types supported by Dygraphs and
17 * return Dygraphs compliant formats.
18 * By default the correct DataHandler is chosen based on the options set.
19 * Optionally the user may use his own DataHandler (similar to the plugin
23 * The unified data format returend by each handler is defined as so:
24 * series[n][point] = [x,y,(extras)]
26 * This format contains the common basis that is needed to draw a simple line
27 * series extended by optional extras for more complex graphing types. It
28 * contains a primitive x value as first array entry, a primitive y value as
29 * second array entry and an optional extras object for additional data needed.
31 * x must always be a number.
32 * y must always be a number, NaN of type number or null.
33 * extras is optional and must be interpreted by the DataHandler. It may be of
36 * In practice this might look something like this:
38 * errorBar / customBar: [x, yVal, [yTopVariance, yBottomVariance] ]
41 /*global Dygraph:false */
42 /*global DygraphLayout:false */
48 * The data handler is responsible for all data specific operations. All of the
49 * series data it receives and returns is always in the unified data format.
50 * Initially the unified data is created by the extractSeries method
53 var DygraphDataHandler
= function () {
56 var handler
= DygraphDataHandler
;
59 * X-value array index constant for unified data samples.
66 * Y-value array index constant for unified data samples.
73 * Extras-value array index constant for unified data samples.
80 * Extracts one series from the raw data (a 2D array) into an array of the
81 * unified data format.
82 * This is where undesirable points (i.e. negative values on log scales and
83 * missing values through which we wish to connect lines) are dropped.
84 * TODO(danvk): the "missing values" bit above doesn't seem right.
86 * @param {!Array.<Array>} rawData The raw data passed into dygraphs where
87 * rawData[i] = [x,ySeries1,...,ySeriesN].
88 * @param {!number} seriesIndex Index of the series to extract. All other
89 * series should be ignored.
90 * @param {!DygraphOptions} options Dygraph options.
91 * @return {Array.<[!number,?number,?]>} The series in the unified data format
92 * where series[i] = [x,y,{extras}].
94 handler
.prototype.extractSeries
= function(rawData
, seriesIndex
, options
) {
98 * Converts a series to a Point array. The resulting point array must be
99 * returned in increasing order of idx property.
101 * @param {!Array.<[!number,?number,?]>} series The series in the unified
102 * data format where series[i] = [x,y,{extras}].
103 * @param {!string} setName Name of the series.
104 * @param {!number} boundaryIdStart Index offset of the first point, equal to the
105 * number of skipped points left of the date window minimum (if any).
106 * @return {!Array.<Dygraph.PointType>} List of points for this series.
108 handler
.prototype.seriesToPoints
= function(series
, setName
, boundaryIdStart
) {
109 // TODO(bhs): these loops are a hot-spot for high-point-count charts. In
111 // on chrome+linux, they are 6 times more expensive than iterating through
113 // points and drawing the lines. The brunt of the cost comes from allocating
114 // the |point| structures.
116 for ( var i
= 0; i
< series
.length
; ++i
) {
117 var item
= series
[i
];
119 var yval
= yraw
=== null ? null : handler
.parseFloat(yraw
);
123 xval
: handler
.parseFloat(item
[0]),
125 name
: setName
, // TODO(danvk): is this really necessary?
126 idx
: i
+ boundaryIdStart
130 this.onPointsCreated_(series
, points
);
135 * Callback called for each series after the series points have been generated
136 * which will later be used by the plotters to draw the graph.
137 * Here data may be added to the seriesPoints which is needed by the plotters.
138 * The indexes of series and points are in sync meaning the original data
139 * sample for series[i] is points[i].
141 * @param {!Array.<[!number,?number,?]>} series The series in the unified
142 * data format where series[i] = [x,y,{extras}].
143 * @param {!Array.<Dygraph.PointType>} points The corresponding points passed
147 handler
.prototype.onPointsCreated_
= function(series
, points
) {
151 * Calculates the rolling average of a data set.
153 * @param {!Array.<[!number,?number,?]>} series The series in the unified
154 * data format where series[i] = [x,y,{extras}].
155 * @param {!number} rollPeriod The number of points over which to average the data
156 * @param {!DygraphOptions} options The dygraph options.
157 * @return {!Array.<[!number,?number,?]>} the rolled series.
159 handler
.prototype.rollingAverage
= function(series
, rollPeriod
, options
) {
163 * Computes the range of the data series (including confidence intervals).
165 * @param {!Array.<[!number,?number,?]>} series The series in the unified
166 * data format where series[i] = [x, y, {extras}].
167 * @param {!Array.<number>} dateWindow The x-value range to display with
168 * the format: [min, max].
169 * @param {!DygraphOptions} options The dygraph options.
170 * @return {Array.<number>} The low and high extremes of the series in the
171 * given window with the format: [low, high].
173 handler
.prototype.getExtremeYValues
= function(series
, dateWindow
, options
) {
177 * Callback called for each series after the layouting data has been
178 * calculated before the series is drawn. Here normalized positioning data
179 * should be calculated for the extras of each point.
181 * @param {!Array.<Dygraph.PointType>} points The points passed to
183 * @param {!Object} axis The axis on which the series will be plotted.
184 * @param {!boolean} logscale Weather or not to use a logscale.
186 handler
.prototype.onLineEvaluated
= function(points
, axis
, logscale
) {
190 * Helper method that computes the y value of a line defined by the points p1
191 * and p2 and a given x value.
193 * @param {!Array.<number>} p1 left point ([x,y]).
194 * @param {!Array.<number>} p2 right point ([x,y]).
195 * @param {!number} xValue The x value to compute the y-intersection for.
196 * @return {number} corresponding y value to x on the line defined by p1 and p2.
199 handler
.prototype.computeYInterpolation_
= function(p1
, p2
, xValue
) {
200 var deltaY
= p2
[1] - p1
[1];
201 var deltaX
= p2
[0] - p1
[0];
202 var gradient
= deltaY
/ deltaX
;
203 var growth
= (xValue
- p1
[0]) * gradient
;
204 return p1
[1] + growth
;
208 * Helper method that returns the first and the last index of the given series
209 * that lie inside the given dateWindow.
211 * @param {!Array.<[!number,?number,?]>} series The series in the unified
212 * data format where series[i] = [x,y,{extras}].
213 * @param {!Array.<number>} dateWindow The x-value range to display with
214 * the format: [min,max].
215 * @return {!Array.<[!number,?number,?]>} The samples of the series that
216 * are in the given date window.
219 handler
.prototype.getIndexesInWindow_
= function(series
, dateWindow
) {
220 var firstIdx
= 0, lastIdx
= series
.length
- 1;
223 var low
= dateWindow
[0];
224 var high
= dateWindow
[1];
226 // Start from each side of the array to minimize the performance
228 while (idx
< series
.length
- 1 && series
[idx
][0] < low
) {
232 idx
= series
.length
- 1;
233 while (idx
> 0 && series
[idx
][0] > high
) {
238 if (firstIdx
<= lastIdx
) {
239 return [ firstIdx
, lastIdx
];
241 return [ 0, series
.length
- 1 ];
246 * Optimized replacement for parseFloat, which was way too slow when almost
247 * all values were type number, with few edge cases, none of which were strings.
248 * @param {?number} val
252 handler
.parseFloat
= function(val
) {
253 // parseFloat(null) is NaN
258 // Assume it's a number or NaN. If it's something else, I'll be shocked.
262 export default DygraphDataHandler
;