datahandler/datahandler.js

   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 /*global Dygraph:false */
  42 /*global DygraphLayout:false */
  43
  44 /**
  45  *
  46  * The data handler is responsible for all data specific operations. All of the
  47  * series data it receives and returns is always in the unified data format.
  48  * Initially the unified data is created by the extractSeries method
  49  * @constructor
  50  */
  51 Dygraph.DataHandler = function () {
  52 };
  53
  54 /**
  55  * A collection of functions to create and retrieve data handlers.
  56  * @type {Object.<!Dygraph.DataHandler>}
  57  */
  58 Dygraph.DataHandlers = {};
  59
  60 (function() {
  61
  62 "use strict";
  63
  64 var handler = Dygraph.DataHandler;
  65
  66 /**
  67  * X-value array index constant for unified data samples.
  68  * @const
  69  * @type {number}
  70  */
  71 handler.X = 0;
  72
  73 /**
  74  * Y-value array index constant for unified data samples.
  75  * @const
  76  * @type {number}
  77  */
  78 handler.Y = 1;
  79
  80 /**
  81  * Extras-value array index constant for unified data samples.
  82  * @const
  83  * @type {number}
  84  */
  85 handler.EXTRAS = 2;
  86
  87 /**
  88  * Extracts one series from the raw data (a 2D array) into an array of the
  89  * unified data format.
  90  * This is where undesirable points (i.e. negative values on log scales and
  91  * missing values through which we wish to connect lines) are dropped.
  92  * TODO(danvk): the "missing values" bit above doesn't seem right.
  93  *
  94  * @param {!Array.<Array>} rawData The raw data passed into dygraphs where
  95  *     rawData[i] = [x,ySeries1,...,ySeriesN].
  96  * @param {!number} seriesIndex Index of the series to extract. All other
  97  *     series should be ignored.
  98  * @param {!DygraphOptions} options Dygraph options.
  99  * @return {Array.<[!number,?number,?]>} The series in the unified data format
 100  *     where series[i] = [x,y,{extras}].
 101  */
 102 handler.prototype.extractSeries = function(rawData, seriesIndex, options) {
 103 };
 104
 105 /**
 106  * Converts a series to a Point array.
 107  *
 108  * @param {!Array.<[!number,?number,?]>} series The series in the unified
 109  *          data format where series[i] = [x,y,{extras}].
 110  * @param {!string} setName Name of the series.
 111  * @param {!number} boundaryIdStart Index offset of the first point, equal to the
 112  *          number of skipped points left of the date window minimum (if any).
 113  * @return {!Array.<Dygraph.PointType>} List of points for this series.
 114  */
 115 handler.prototype.seriesToPoints = function(series, setName, boundaryIdStart) {
 116   // TODO(bhs): these loops are a hot-spot for high-point-count charts. In
 117   // fact,
 118   // on chrome+linux, they are 6 times more expensive than iterating through
 119   // the
 120   // points and drawing the lines. The brunt of the cost comes from allocating
 121   // the |point| structures.
 122   var points = [];
 123   for ( var i = 0; i < series.length; ++i) {
 124     var item = series[i];
 125     var yraw = item[1];
 126     var yval = yraw === null ? null : handler.parseFloat(yraw);
 127     var point = {
 128       x : NaN,
 129       y : NaN,
 130       xval : handler.parseFloat(item[0]),
 131       yval : yval,
 132       name : setName, // TODO(danvk): is this really necessary?
 133       idx : i + boundaryIdStart
 134     };
 135     points.push(point);
 136   }
 137   this.onPointsCreated_(series, points);
 138   return points;
 139 };
 140
 141 /**
 142  * Callback called for each series after the series points have been generated
 143  * which will later be used by the plotters to draw the graph.
 144  * Here data may be added to the seriesPoints which is needed by the plotters.
 145  * The indexes of series and points are in sync meaning the original data
 146  * sample for series[i] is points[i].
 147  *
 148  * @param {!Array.<[!number,?number,?]>} series The series in the unified
 149  *     data format where series[i] = [x,y,{extras}].
 150  * @param {!Array.<Dygraph.PointType>} points The corresponding points passed
 151  *     to the plotter.
 152  * @protected
 153  */
 154 handler.prototype.onPointsCreated_ = function(series, points) {
 155 };
 156
 157 /**
 158  * Calculates the rolling average of a data set.
 159  *
 160  * @param {!Array.<[!number,?number,?]>} series The series in the unified
 161  *          data format where series[i] = [x,y,{extras}].
 162  * @param {!number} rollPeriod The number of points over which to average the data
 163  * @param {!DygraphOptions} options The dygraph options.
 164  * @return {!Array.<[!number,?number,?]>} the rolled series.
 165  */
 166 handler.prototype.rollingAverage = function(series, rollPeriod, options) {
 167 };
 168
 169 /**
 170  * Computes the range of the data series (including confidence intervals).
 171  *
 172  * @param {!Array.<[!number,?number,?]>} series The series in the unified
 173  *     data format where series[i] = [x, y, {extras}].
 174  * @param {!Array.<number>} dateWindow The x-value range to display with
 175  *     the format: [min, max].
 176  * @param {!DygraphOptions} options The dygraph options.
 177  * @return {Array.<number>} The low and high extremes of the series in the
 178  *     given window with the format: [low, high].
 179  */
 180 handler.prototype.getExtremeYValues = function(series, dateWindow, options) {
 181 };
 182
 183 /**
 184  * Callback called for each series after the layouting data has been
 185  * calculated before the series is drawn. Here normalized positioning data
 186  * should be calculated for the extras of each point.
 187  *
 188  * @param {!Array.<Dygraph.PointType>} points The points passed to
 189  *          the plotter.
 190  * @param {!Object} axis The axis on which the series will be plotted.
 191  * @param {!boolean} logscale Weather or not to use a logscale.
 192  */
 193 handler.prototype.onLineEvaluated = function(points, axis, logscale) {
 194 };
 195
 196 /**
 197  * Helper method that computes the y value of a line defined by the points p1
 198  * and p2 and a given x value.
 199  *
 200  * @param {!Array.<number>} p1 left point ([x,y]).
 201  * @param {!Array.<number>} p2 right point ([x,y]).
 202  * @param {!number} xValue The x value to compute the y-intersection for.
 203  * @return {number} corresponding y value to x on the line defined by p1 and p2.
 204  * @private
 205  */
 206 handler.prototype.computeYInterpolation_ = function(p1, p2, xValue) {
 207   var deltaY = p2[1] - p1[1];
 208   var deltaX = p2[0] - p1[0];
 209   var gradient = deltaY / deltaX;
 210   var growth = (xValue - p1[0]) * gradient;
 211   return p1[1] + growth;
 212 };
 213
 214 /**
 215  * Helper method that returns the first and the last index of the given series
 216  * that lie inside the given dateWindow.
 217  *
 218  * @param {!Array.<[!number,?number,?]>} series The series in the unified
 219  *     data format where series[i] = [x,y,{extras}].
 220  * @param {!Array.<number>} dateWindow The x-value range to display with
 221  *     the format: [min,max].
 222  * @return {!Array.<[!number,?number,?]>} The samples of the series that
 223  *     are in the given date window.
 224  * @private
 225  */
 226 handler.prototype.getIndexesInWindow_ = function(series, dateWindow) {
 227   var firstIdx = 0, lastIdx = series.length - 1;
 228   if (dateWindow) {
 229     var idx = 0;
 230     var low = dateWindow[0];
 231     var high = dateWindow[1];
 232
 233     // Start from each side of the array to minimize the performance
 234     // needed.
 235     while (idx < series.length - 1 && series[idx][0] < low) {
 236       firstIdx++;
 237       idx++;
 238     }
 239     idx = series.length - 1;
 240     while (idx > 0 && series[idx][0] > high) {
 241       lastIdx--;
 242       idx--;
 243     }
 244   }
 245   if (firstIdx <= lastIdx) {
 246     return [ firstIdx, lastIdx ];
 247   } else {
 248     return [ 0, series.length - 1 ];
 249   }
 250 };
 251
 252 /**
 253  * Optimized replacement for parseFloat, which was way too slow when almost
 254  * all values were type number, with few edge cases, none of which were strings.
 255  * @param {?number} val
 256  * @return {number}
 257  * @protected
 258  */
 259 handler.parseFloat = function(val) {
 260   // parseFloat(null) is NaN
 261   if (val === null) {
 262     return NaN;
 263   }
 264
 265   // Assume it's a number or NaN. If it's something else, I'll be shocked.
 266   return val;
 267 };
 268
 269 })();