Commit | Line | Data |
---|---|---|
a49c164a DE |
1 | /** |
2 | * @license | |
3 | * Copyright 2013 David Eberlein (david.eberlein@ch.sauter-bc.com) | |
4 | * MIT-licensed (http://opensource.org/licenses/MIT) | |
5 | */ | |
6 | ||
7 | /** | |
8 | * @fileoverview This file contains the managment of data handlers | |
9 | * @author David Eberlein (david.eberlein@ch.sauter-bc.com) | |
10 | * | |
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 | |
20 | * system). | |
21 | * | |
22 | * | |
23 | * The unified data format returend by each handler is defined as so: | |
24 | * series[n][point] = [x,y,(extras)] | |
25 | * | |
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. | |
30 | * | |
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 | |
34 | * any type. | |
35 | * | |
36 | * In practice this might look something like this: | |
37 | * default: [x, yVal] | |
38 | * errorBar / customBar: [x, yVal, [yTopVariance, yBottomVariance] ] | |
39 | * | |
40 | */ | |
41 | /*jshint globalstrict: true */ | |
42 | /*global Dygraph:false */ | |
43 | /*global DygraphLayout:false */ | |
44 | "use strict"; | |
45 | ||
46 | /** | |
47 | * A collection of functions to create and retrieve data handlers. | |
48 | */ | |
49 | Dygraph.DataHandlers = {}; | |
50 | ||
51 | /** | |
52 | * All registered data handlers are stored here. | |
53 | * | |
54 | * @private | |
55 | */ | |
56 | Dygraph.DataHandlers.handlers_ = {}; | |
57 | ||
58 | /** | |
59 | * @param name {!string} The name the data handler should be registered to. | |
60 | * Registers a data handler by the given name and makes it publicly | |
61 | * accessible. | |
62 | * @param handler {!Dygraph.DataHandler} DataHandler implementation which must be an | |
63 | * instance of Dygraph.DataHandler. | |
64 | * @public | |
65 | */ | |
66 | Dygraph.DataHandlers.registerHandler = function(name, handler) { | |
67 | if (!handler instanceof Dygraph.DataHandler) { | |
68 | throw ("the handler must be a prototype of Dygraph.DataHandler"); | |
69 | } | |
70 | Dygraph.DataHandlers.handlers_[name] = handler; | |
71 | }; | |
72 | ||
73 | /** | |
74 | * Returns the data handler registered to the given name. | |
75 | * Note this is the data handler constructor method. | |
76 | * | |
77 | * @param name {!string} The name, the handler was registered to. | |
78 | * @returns {Dygraph.DataHandler} The data handler constructor. | |
79 | * @public | |
80 | */ | |
81 | Dygraph.DataHandlers.getHandler = function(name) { | |
82 | return Dygraph.DataHandlers.handlers_[name]; | |
83 | }; | |
84 | ||
85 | /** | |
86 | * Returns the cunstructed data handler registered to the given name. | |
87 | * | |
88 | * @param name {!string} The name, the handler was registered to. | |
89 | * @returns {Dygraph.DataHandler} A constructed instance of the data handler. | |
90 | * @public | |
91 | */ | |
92 | Dygraph.DataHandlers.createHandler = function(name) { | |
93 | return new Dygraph.DataHandlers.handlers_[name](); | |
94 | }; | |
95 | ||
96 | /** | |
97 | * | |
98 | * The data handler is responsible for all data specific operations. All of the | |
99 | * series data it receives and returns is always in the unified data format. | |
100 | * Initially the unified data is created by the extractSeries method | |
101 | * | |
102 | * @class | |
103 | */ | |
104 | Dygraph.DataHandler = function () { | |
105 | /** | |
106 | * Constructor for all data handlers. | |
107 | * @constructor | |
108 | */ | |
109 | var handler = function() { | |
110 | return this; | |
111 | }; | |
112 | ||
113 | /** | |
114 | * X-value array index constant for unified data samples. | |
115 | * @const | |
116 | * @type {number} | |
117 | */ | |
118 | handler.X = 0; | |
119 | ||
120 | /** | |
121 | * Y-value array index constant for unified data samples. | |
122 | * @const | |
123 | * @type {number} | |
124 | */ | |
125 | handler.Y = 1; | |
126 | ||
127 | /** | |
128 | * Extras-value array index constant for unified data samples. | |
129 | * @const | |
130 | * @type {number} | |
131 | */ | |
132 | handler.EXTRAS = 2; | |
133 | ||
134 | /** | |
135 | * Extracts one series from the raw data (a 2D array) into an array of the | |
136 | * unified data format. | |
137 | * This is where undesirable points (i.e. negative values on log scales and | |
138 | * missing values through which we wish to connect lines) are dropped. | |
139 | * TODO(danvk): the "missing values" bit above doesn't seem right. | |
140 | * | |
141 | * @param rawData {!Array.<Array>} The raw data passed into dygraphs where | |
142 | * rawData[i] = [x,ySeries1,...,ySeriesN]. | |
143 | * @param seriesIndex {!number} Index of the series to extract. All other series should | |
144 | * be ignored. | |
145 | * @param options {!DygraphOptions} Dygraph options. | |
146 | * @returns {Array.<[!number,?number,?]>} The series in the unified data format | |
147 | * where series[i] = [x,y,{extras}]. | |
148 | * @public | |
149 | */ | |
150 | handler.prototype.extractSeries = function(rawData, seriesIndex, options) { | |
151 | }; | |
152 | ||
153 | /** | |
154 | * Converts a series to a Point array. | |
155 | * | |
156 | * @param {!Array.<[!number,?number,?]>} series The series in the unified | |
157 | * data format where series[i] = [x,y,{extras}]. | |
158 | * @param {!string} setName Name of the series. | |
159 | * @param {!number} boundaryIdStart Index offset of the first point, equal to the | |
160 | * number of skipped points left of the date window minimum (if any). | |
161 | * @return {!Array.<Dygraph.PointType>} List of points for this series. | |
162 | * @public | |
163 | */ | |
164 | handler.prototype.seriesToPoints = function(series, setName, boundaryIdStart) { | |
165 | // TODO(bhs): these loops are a hot-spot for high-point-count charts. In | |
166 | // fact, | |
167 | // on chrome+linux, they are 6 times more expensive than iterating through | |
168 | // the | |
169 | // points and drawing the lines. The brunt of the cost comes from allocating | |
170 | // the |point| structures. | |
171 | var points = []; | |
172 | for ( var i = 0; i < series.length; ++i) { | |
173 | var item = series[i]; | |
174 | var yraw = item[1]; | |
175 | var yval = yraw === null ? null : DygraphLayout.parseFloat_(yraw); | |
176 | var point = { | |
177 | x : NaN, | |
178 | y : NaN, | |
179 | xval : DygraphLayout.parseFloat_(item[0]), | |
180 | yval : yval, | |
181 | name : setName, // TODO(danvk): is this really necessary? | |
182 | idx : i + boundaryIdStart | |
183 | }; | |
184 | points.push(point); | |
185 | } | |
186 | handler.prototype.onPointsCreated_(series, points); | |
187 | return points; | |
188 | }; | |
189 | ||
190 | /** | |
191 | * Callback called for each series after the series points have been generated | |
192 | * which will later be used by the plotters to draw the graph. | |
193 | * Here data may be added to the seriesPoints which is needed by the plotters. | |
194 | * The indexes of series and points are in sync meaning the original data | |
195 | * sample for series[i] is points[i]. | |
196 | * | |
197 | * @param {!Array.<[!number,?number,?]>} series The series in the unified | |
198 | * data format where series[i] = [x,y,{extras}]. | |
199 | * @param {!Array.<Dygraph.PointType>} points The corresponding points passed | |
200 | * to the plotter. | |
201 | * @private | |
202 | */ | |
203 | handler.prototype.onPointsCreated_ = function(series, points) { | |
204 | }; | |
205 | ||
206 | /** | |
207 | * Calculates the rolling average of a data set. | |
208 | * | |
209 | * @param {!Array.<[!number,?number,?]>} series The series in the unified | |
210 | * data format where series[i] = [x,y,{extras}]. | |
211 | * @param {!number} rollPeriod The number of points over which to average the data | |
212 | * @param {!DygraphOptions} options The dygraph options. | |
213 | * @return the rolled series. | |
214 | * @public | |
215 | */ | |
216 | handler.prototype.rollingAverage = function(series, rollPeriod, options) { | |
217 | }; | |
218 | ||
219 | /** | |
220 | * Computes the range of the data series (including confidence intervals). | |
221 | * | |
222 | * @param {!Array.<[!number,?number,?]>} series The series in the unified | |
223 | * data format where series[i] = [x,y,{extras}]. | |
224 | * @param {!Array.<number>} dateWindow The x-value range to display with | |
225 | * the format: [min,max]. | |
226 | * @param {!DygraphOptions} options The dygraph options. | |
227 | * @return {Array.<number>} The low and high extremes of the series in the given window with | |
228 | * the format: [low, high]. | |
229 | * @public | |
230 | */ | |
231 | handler.prototype.getExtremeYValues = function(series, dateWindow, options) { | |
232 | }; | |
233 | ||
234 | /** | |
235 | * Callback called for each series after the layouting data has been | |
236 | * calculated before the series is drawn. Here normalized positioning data | |
237 | * should be calculated for the extras of each point. | |
238 | * | |
239 | * @param {!Array.<Dygraph.PointType>} points The points passed to | |
240 | * the plotter. | |
241 | * @param {!Object} axis The axis on which the series will be plotted. | |
242 | * @param {!boolean} logscale Weather or not to use a logscale. | |
243 | * @public | |
244 | */ | |
245 | handler.prototype.onLineEvaluated = function(points, axis, logscale) { | |
246 | }; | |
247 | ||
248 | /** | |
249 | * Helper method that computes the y value of a line defined by the points p1 | |
250 | * and p2 and a given x value. | |
251 | * | |
252 | * @param {!Array.<number>} p1 left point ([x,y]). | |
253 | * @param {!Array.<number>} p2 right point ([x,y]). | |
254 | * @param {!number} xValue The x value to compute the y-intersection for. | |
255 | * @return {number} corresponding y value to x on the line defined by p1 and p2. | |
256 | * @private | |
257 | */ | |
258 | handler.prototype.computeYInterpolation_ = function(p1, p2, xValue) { | |
259 | var deltaY = p2[1] - p1[1]; | |
260 | var deltaX = p2[0] - p1[0]; | |
261 | var gradient = deltaY / deltaX; | |
262 | var growth = (xValue - p1[0]) * gradient; | |
263 | return p1[1] + growth; | |
264 | }; | |
265 | ||
266 | /** | |
267 | * Helper method that returns the first and the last index of the given series | |
268 | * that lie inside the given dateWindow. | |
269 | * | |
270 | * @param {!Array.<[!number,?number,?]>} series The series in the unified | |
271 | * data format where series[i] = [x,y,{extras}]. | |
272 | * @param {!Array.<number>} dateWindow The x-value range to display with | |
273 | * the format: [min,max]. | |
274 | * @return {!Array.<[!number,?number,?]>} The samples of the series that | |
275 | * are in the given date window. | |
276 | * @private | |
277 | */ | |
278 | handler.prototype.getIndexesInWindow_ = function(series, dateWindow) { | |
279 | var firstIdx = 0, lastIdx = series.length - 1; | |
280 | if (dateWindow) { | |
281 | var idx = 0; | |
282 | var low = dateWindow[0]; | |
283 | var high = dateWindow[1]; | |
284 | ||
285 | // Start from each side of the array to minimize the performance | |
286 | // needed. | |
287 | while (idx < series.length - 1 && series[idx][0] < low) { | |
288 | firstIdx++; | |
289 | idx++; | |
290 | } | |
291 | idx = series.length - 1; | |
292 | while (idx > 0 && series[idx][0] > high) { | |
293 | lastIdx--; | |
294 | idx--; | |
295 | } | |
296 | } | |
297 | if (firstIdx <= lastIdx) { | |
298 | return [ firstIdx, lastIdx ]; | |
299 | } else { | |
300 | return [ 0, series.length - 1 ]; | |
301 | } | |
302 | }; | |
303 | ||
304 | return handler; | |
305 | }; |