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