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 /**
  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.  The resulting point array must be
 107  * returned in increasing order of idx property.
 108  *
 109  * @param {!Array.<[!number,?number,?]>} series The series in the unified
 110  *          data format where series[i] = [x,y,{extras}].
 111  * @param {!string} setName Name of the series.
 112  * @param {!number} boundaryIdStart Index offset of the first point, equal to the
 113  *          number of skipped points left of the date window minimum (if any).
 114  * @return {!Array.<Dygraph.PointType>} List of points for this series.
 115  */
 116 handler.prototype.seriesToPoints = function(series, setName, boundaryIdStart) {
 117   // TODO(bhs): these loops are a hot-spot for high-point-count charts. In
 118   // fact,
 119   // on chrome+linux, they are 6 times more expensive than iterating through
 120   // the
 121   // points and drawing the lines. The brunt of the cost comes from allocating
 122   // the |point| structures.
 123   var points = [];
 124   for ( var i = 0; i < series.length; ++i) {
 125     var item = series[i];
 126     var yraw = item[1];
 127     var yval = yraw === null ? null : handler.parseFloat(yraw);
 128     var point = {
 129       x : NaN,
 130       y : NaN,
 131       xval : handler.parseFloat(item[0]),
 132       yval : yval,
 133       name : setName, // TODO(danvk): is this really necessary?
 134       idx : i + boundaryIdStart
 135     };
 136     points.push(point);
 137   }
 138   this.onPointsCreated_(series, points);
 139   return points;
 140 };
 141
 142 /**
 143  * Callback called for each series after the series points have been generated
 144  * which will later be used by the plotters to draw the graph.
 145  * Here data may be added to the seriesPoints which is needed by the plotters.
 146  * The indexes of series and points are in sync meaning the original data
 147  * sample for series[i] is points[i].
 148  *
 149  * @param {!Array.<[!number,?number,?]>} series The series in the unified
 150  *     data format where series[i] = [x,y,{extras}].
 151  * @param {!Array.<Dygraph.PointType>} points The corresponding points passed
 152  *     to the plotter.
 153  * @protected
 154  */
 155 handler.prototype.onPointsCreated_ = function(series, points) {
 156 };
 157
 158 /**
 159  * Calculates the rolling average of a data set.
 160  *
 161  * @param {!Array.<[!number,?number,?]>} series The series in the unified
 162  *          data format where series[i] = [x,y,{extras}].
 163  * @param {!number} rollPeriod The number of points over which to average the data
 164  * @param {!DygraphOptions} options The dygraph options.
 165  * @return {!Array.<[!number,?number,?]>} the rolled series.
 166  */
 167 handler.prototype.rollingAverage = function(series, rollPeriod, options) {
 168 };
 169
 170 /**
 171  * Computes the range of the data series (including confidence intervals).
 172  *
 173  * @param {!Array.<[!number,?number,?]>} series The series in the unified
 174  *     data format where series[i] = [x, y, {extras}].
 175  * @param {!Array.<number>} dateWindow The x-value range to display with
 176  *     the format: [min, max].
 177  * @param {!DygraphOptions} options The dygraph options.
 178  * @return {Array.<number>} The low and high extremes of the series in the
 179  *     given window with the format: [low, high].
 180  */
 181 handler.prototype.getExtremeYValues = function(series, dateWindow, options) {
 182 };
 183
 184 /**
 185  * Callback called for each series after the layouting data has been
 186  * calculated before the series is drawn. Here normalized positioning data
 187  * should be calculated for the extras of each point.
 188  *
 189  * @param {!Array.<Dygraph.PointType>} points The points passed to
 190  *          the plotter.
 191  * @param {!Object} axis The axis on which the series will be plotted.
 192  * @param {!boolean} logscale Weather or not to use a logscale.
 193  */
 194 handler.prototype.onLineEvaluated = function(points, axis, logscale) {
 195 };
 196
 197 /**
 198  * Helper method that computes the y value of a line defined by the points p1
 199  * and p2 and a given x value.
 200  *
 201  * @param {!Array.<number>} p1 left point ([x,y]).
 202  * @param {!Array.<number>} p2 right point ([x,y]).
 203  * @param {!number} xValue The x value to compute the y-intersection for.
 204  * @return {number} corresponding y value to x on the line defined by p1 and p2.
 205  * @private
 206  */
 207 handler.prototype.computeYInterpolation_ = function(p1, p2, xValue) {
 208   var deltaY = p2[1] - p1[1];
 209   var deltaX = p2[0] - p1[0];
 210   var gradient = deltaY / deltaX;
 211   var growth = (xValue - p1[0]) * gradient;
 212   return p1[1] + growth;
 213 };
 214
 215 /**
 216  * Helper method that returns the first and the last index of the given series
 217  * that lie inside the given dateWindow.
 218  *
 219  * @param {!Array.<[!number,?number,?]>} series The series in the unified
 220  *     data format where series[i] = [x,y,{extras}].
 221  * @param {!Array.<number>} dateWindow The x-value range to display with
 222  *     the format: [min,max].
 223  * @return {!Array.<[!number,?number,?]>} The samples of the series that
 224  *     are in the given date window.
 225  * @private
 226  */
 227 handler.prototype.getIndexesInWindow_ = function(series, dateWindow) {
 228   var firstIdx = 0, lastIdx = series.length - 1;
 229   if (dateWindow) {
 230     var idx = 0;
 231     var low = dateWindow[0];
 232     var high = dateWindow[1];
 233
 234     // Start from each side of the array to minimize the performance
 235     // needed.
 236     while (idx < series.length - 1 && series[idx][0] < low) {
 237       firstIdx++;
 238       idx++;
 239     }
 240     idx = series.length - 1;
 241     while (idx > 0 && series[idx][0] > high) {
 242       lastIdx--;
 243       idx--;
 244     }
 245   }
 246   if (firstIdx <= lastIdx) {
 247     return [ firstIdx, lastIdx ];
 248   } else {
 249     return [ 0, series.length - 1 ];
 250   }
 251 };
 252
 253 /**
 254  * Optimized replacement for parseFloat, which was way too slow when almost
 255  * all values were type number, with few edge cases, none of which were strings.
 256  * @param {?number} val
 257  * @return {number}
 258  * @protected
 259  */
 260 handler.parseFloat = function(val) {
 261   // parseFloat(null) is NaN
 262   if (val === null) {
 263     return NaN;
 264   }
 265
 266   // Assume it's a number or NaN. If it's something else, I'll be shocked.
 267   return val;
 268 };
 269
 270 })();