src/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 "use strict";
  45
  46 /**
  47  *
  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
  51  * @constructor
  52  */
  53 var DygraphDataHandler = function () {
  54 };
  55
  56 var handler = DygraphDataHandler;
  57
  58 /**
  59  * X-value array index constant for unified data samples.
  60  * @const
  61  * @type {number}
  62  */
  63 handler.X = 0;
  64
  65 /**
  66  * Y-value array index constant for unified data samples.
  67  * @const
  68  * @type {number}
  69  */
  70 handler.Y = 1;
  71
  72 /**
  73  * Extras-value array index constant for unified data samples.
  74  * @const
  75  * @type {number}
  76  */
  77 handler.EXTRAS = 2;
  78
  79 /**
  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.
  85  *
  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}].
  93  */
  94 handler.prototype.extractSeries = function(rawData, seriesIndex, options) {
  95 };
  96
  97 /**
  98  * Converts a series to a Point array.  The resulting point array must be
  99  * returned in increasing order of idx property.
 100  *
 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.
 107  */
 108 handler.prototype.seriesToPoints = function(series, setName, boundaryIdStart) {
 109   // TODO(bhs): these loops are a hot-spot for high-point-count charts. In
 110   // fact,
 111   // on chrome+linux, they are 6 times more expensive than iterating through
 112   // the
 113   // points and drawing the lines. The brunt of the cost comes from allocating
 114   // the |point| structures.
 115   var points = [];
 116   for ( var i = 0; i < series.length; ++i) {
 117     var item = series[i];
 118     var yraw = item[1];
 119     var yval = yraw === null ? null : handler.parseFloat(yraw);
 120     var point = {
 121       x : NaN,
 122       y : NaN,
 123       xval : handler.parseFloat(item[0]),
 124       yval : yval,
 125       name : setName, // TODO(danvk): is this really necessary?
 126       idx : i + boundaryIdStart
 127     };
 128     points.push(point);
 129   }
 130   this.onPointsCreated_(series, points);
 131   return points;
 132 };
 133
 134 /**
 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].
 140  *
 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
 144  *     to the plotter.
 145  * @protected
 146  */
 147 handler.prototype.onPointsCreated_ = function(series, points) {
 148 };
 149
 150 /**
 151  * Calculates the rolling average of a data set.
 152  *
 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.
 158  */
 159 handler.prototype.rollingAverage = function(series, rollPeriod, options) {
 160 };
 161
 162 /**
 163  * Computes the range of the data series (including confidence intervals).
 164  *
 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].
 172  */
 173 handler.prototype.getExtremeYValues = function(series, dateWindow, options) {
 174 };
 175
 176 /**
 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.
 180  *
 181  * @param {!Array.<Dygraph.PointType>} points The points passed to
 182  *          the plotter.
 183  * @param {!Object} axis The axis on which the series will be plotted.
 184  * @param {!boolean} logscale Weather or not to use a logscale.
 185  */
 186 handler.prototype.onLineEvaluated = function(points, axis, logscale) {
 187 };
 188
 189 /**
 190  * Helper method that computes the y value of a line defined by the points p1
 191  * and p2 and a given x value.
 192  *
 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.
 197  * @private
 198  */
 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;
 205 };
 206
 207 /**
 208  * Helper method that returns the first and the last index of the given series
 209  * that lie inside the given dateWindow.
 210  *
 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.
 217  * @private
 218  */
 219 handler.prototype.getIndexesInWindow_ = function(series, dateWindow) {
 220   var firstIdx = 0, lastIdx = series.length - 1;
 221   if (dateWindow) {
 222     var idx = 0;
 223     var low = dateWindow[0];
 224     var high = dateWindow[1];
 225
 226     // Start from each side of the array to minimize the performance
 227     // needed.
 228     while (idx < series.length - 1 && series[idx][0] < low) {
 229       firstIdx++;
 230       idx++;
 231     }
 232     idx = series.length - 1;
 233     while (idx > 0 && series[idx][0] > high) {
 234       lastIdx--;
 235       idx--;
 236     }
 237   }
 238   if (firstIdx <= lastIdx) {
 239     return [ firstIdx, lastIdx ];
 240   } else {
 241     return [ 0, series.length - 1 ];
 242   }
 243 };
 244
 245 /**
 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
 249  * @return {number}
 250  * @protected
 251  */
 252 handler.parseFloat = function(val) {
 253   // parseFloat(null) is NaN
 254   if (val === null) {
 255     return NaN;
 256   }
 257
 258   // Assume it's a number or NaN. If it's something else, I'll be shocked.
 259   return val;
 260 };
 261
 262 export default DygraphDataHandler;