rubyvis 0.1.0 → 0.1.1

data/vendor/src/data/Nest.js

@@ -0,0 +1,257 @@
+/**
+ * Returns a {@link pv.Nest} operator for the specified array. This is a
+ * convenience factory method, equivalent to <tt>new pv.Nest(array)</tt>.
+ *
+ * @see pv.Nest
+ * @param {array} array an array of elements to nest.
+ * @returns {pv.Nest} a nest operator for the specified array.
+ */
+pv.nest = function(array) {
+  return new pv.Nest(array);
+};
+
+/**
+ * Constructs a nest operator for the specified array. This constructor should
+ * not be invoked directly; use {@link pv.nest} instead.
+ *
+ * @class Represents a {@link Nest} operator for the specified array. Nesting
+ * allows elements in an array to be grouped into a hierarchical tree
+ * structure. The levels in the tree are specified by <i>key</i> functions. The
+ * leaf nodes of the tree can be sorted by value, while the internal nodes can
+ * be sorted by key. Finally, the tree can be returned either has a
+ * multidimensional array via {@link #entries}, or as a hierarchical map via
+ * {@link #map}. The {@link #rollup} routine similarly returns a map, collapsing
+ * the elements in each leaf node using a summary function.
+ *
+ * <p>For example, consider the following tabular data structure of Barley
+ * yields, from various sites in Minnesota during 1931-2:
+ *
+ * <pre>{ yield: 27.00, variety: "Manchuria", year: 1931, site: "University Farm" },
+ * { yield: 48.87, variety: "Manchuria", year: 1931, site: "Waseca" },
+ * { yield: 27.43, variety: "Manchuria", year: 1931, site: "Morris" }, ...</pre>
+ *
+ * To facilitate visualization, it may be useful to nest the elements first by
+ * year, and then by variety, as follows:
+ *
+ * <pre>var nest = pv.nest(yields)
+ *     .key(function(d) d.year)
+ *     .key(function(d) d.variety)
+ *     .entries();</pre>
+ *
+ * This returns a nested array. Each element of the outer array is a key-values
+ * pair, listing the values for each distinct key:
+ *
+ * <pre>{ key: 1931, values: [
+ *   { key: "Manchuria", values: [
+ *       { yield: 27.00, variety: "Manchuria", year: 1931, site: "University Farm" },
+ *       { yield: 48.87, variety: "Manchuria", year: 1931, site: "Waseca" },
+ *       { yield: 27.43, variety: "Manchuria", year: 1931, site: "Morris" },
+ *       ...
+ *     ] },
+ *   { key: "Glabron", values: [
+ *       { yield: 43.07, variety: "Glabron", year: 1931, site: "University Farm" },
+ *       { yield: 55.20, variety: "Glabron", year: 1931, site: "Waseca" },
+ *       ...
+ *     ] },
+ *   ] },
+ * { key: 1932, values: ... }</pre>
+ *
+ * Further details, including sorting and rollup, is provided below on the
+ * corresponding methods.
+ *
+ * @param {array} array an array of elements to nest.
+ */
+pv.Nest = function(array) {
+  this.array = array;
+  this.keys = [];
+};
+
+/**
+ * Nests using the specified key function. Multiple keys may be added to the
+ * nest; the array elements will be nested in the order keys are specified.
+ *
+ * @param {function} key a key function; must return a string or suitable map
+ * key.
+ * @returns {pv.Nest} this.
+ */
+pv.Nest.prototype.key = function(key) {
+  this.keys.push(key);
+  return this;
+};
+
+/**
+ * Sorts the previously-added keys. The natural sort order is used by default
+ * (see {@link pv.naturalOrder}); if an alternative order is desired,
+ * <tt>order</tt> should be a comparator function. If this method is not called
+ * (i.e., keys are <i>unsorted</i>), keys will appear in the order they appear
+ * in the underlying elements array. For example,
+ *
+ * <pre>pv.nest(yields)
+ *     .key(function(d) d.year)
+ *     .key(function(d) d.variety)
+ *     .sortKeys()
+ *     .entries()</pre>
+ *
+ * groups yield data by year, then variety, and sorts the variety groups
+ * lexicographically (since the variety attribute is a string).
+ *
+ * <p>Key sort order is only used in conjunction with {@link #entries}, which
+ * returns an array of key-values pairs. If the nest is used to construct a
+ * {@link #map} instead, keys are unsorted.
+ *
+ * @param {function} [order] an optional comparator function.
+ * @returns {pv.Nest} this.
+ */
+pv.Nest.prototype.sortKeys = function(order) {
+  this.keys[this.keys.length - 1].order = order || pv.naturalOrder;
+  return this;
+};
+
+/**
+ * Sorts the leaf values. The natural sort order is used by default (see
+ * {@link pv.naturalOrder}); if an alternative order is desired, <tt>order</tt>
+ * should be a comparator function. If this method is not called (i.e., values
+ * are <i>unsorted</i>), values will appear in the order they appear in the
+ * underlying elements array. For example,
+ *
+ * <pre>pv.nest(yields)
+ *     .key(function(d) d.year)
+ *     .key(function(d) d.variety)
+ *     .sortValues(function(a, b) a.yield - b.yield)
+ *     .entries()</pre>
+ *
+ * groups yield data by year, then variety, and sorts the values for each
+ * variety group by yield.
+ *
+ * <p>Value sort order, unlike keys, applies to both {@link #entries} and
+ * {@link #map}. It has no effect on {@link #rollup}.
+ *
+ * @param {function} [order] an optional comparator function.
+ * @returns {pv.Nest} this.
+ */
+pv.Nest.prototype.sortValues = function(order) {
+  this.order = order || pv.naturalOrder;
+  return this;
+};
+
+/**
+ * Returns a hierarchical map of values. Each key adds one level to the
+ * hierarchy. With only a single key, the returned map will have a key for each
+ * distinct value of the key function; the correspond value with be an array of
+ * elements with that key value. If a second key is added, this will be a nested
+ * map. For example:
+ *
+ * <pre>pv.nest(yields)
+ *     .key(function(d) d.variety)
+ *     .key(function(d) d.site)
+ *     .map()</pre>
+ *
+ * returns a map <tt>m</tt> such that <tt>m[variety][site]</tt> is an array, a subset of
+ * <tt>yields</tt>, with each element having the given variety and site.
+ *
+ * @returns a hierarchical map of values.
+ */
+pv.Nest.prototype.map = function() {
+  var map = {}, values = [];
+
+  /* Build the map. */
+  for (var i, j = 0; j < this.array.length; j++) {
+    var x = this.array[j];
+    var m = map;
+    for (i = 0; i < this.keys.length - 1; i++) {
+      var k = this.keys[i](x);
+      if (!m[k]) m[k] = {};
+      m = m[k];
+    }
+    k = this.keys[i](x);
+    if (!m[k]) {
+      var a = [];
+      values.push(a);
+      m[k] = a;
+    }
+    m[k].push(x);
+  }
+
+  /* Sort each leaf array. */
+  if (this.order) {
+    for (var i = 0; i < values.length; i++) {
+      values[i].sort(this.order);
+    }
+  }
+
+  return map;
+};
+
+/**
+ * Returns a hierarchical nested array. This method is similar to
+ * {@link pv.entries}, but works recursively on the entire hierarchy. Rather
+ * than returning a map like {@link #map}, this method returns a nested
+ * array. Each element of the array has a <tt>key</tt> and <tt>values</tt>
+ * field. For leaf nodes, the <tt>values</tt> array will be a subset of the
+ * underlying elements array; for non-leaf nodes, the <tt>values</tt> array will
+ * contain more key-values pairs.
+ *
+ * <p>For an example usage, see the {@link Nest} constructor.
+ *
+ * @returns a hierarchical nested array.
+ */
+pv.Nest.prototype.entries = function() {
+
+  /** Recursively extracts the entries for the given map. */
+  function entries(map) {
+    var array = [];
+    for (var k in map) {
+      var v = map[k];
+      array.push({ key: k, values: (v instanceof Array) ? v : entries(v) });
+    };
+    return array;
+  }
+
+  /** Recursively sorts the values for the given key-values array. */
+  function sort(array, i) {
+    var o = this.keys[i].order;
+    if (o) array.sort(function(a, b) { return o(a.key, b.key); });
+    if (++i < this.keys.length) {
+      for (var j = 0; j < array.length; j++) {
+        sort.call(this, array[j].values, i);
+      }
+    }
+    return array;
+  }
+
+  return sort.call(this, entries(this.map()), 0);
+};
+
+/**
+ * Returns a rollup map. The behavior of this method is the same as
+ * {@link #map}, except that the leaf values are replaced with the return value
+ * of the specified rollup function <tt>f</tt>. For example,
+ *
+ * <pre>pv.nest(yields)
+ *      .key(function(d) d.site)
+ *      .rollup(function(v) pv.median(v, function(d) d.yield))</pre>
+ *
+ * first groups yield data by site, and then returns a map from site to median
+ * yield for the given site.
+ *
+ * @see #map
+ * @param {function} f a rollup function.
+ * @returns a hierarchical map, with the leaf values computed by <tt>f</tt>.
+ */
+pv.Nest.prototype.rollup = function(f) {
+
+  /** Recursively descends to the leaf nodes (arrays) and does rollup. */
+  function rollup(map) {
+    for (var key in map) {
+      var value = map[key];
+      if (value instanceof Array) {
+        map[key] = f(value);
+      } else {
+        rollup(value);
+      }
+    }
+    return map;
+  }
+
+  return rollup(this.map());
+};

data/vendor/src/data/Numbers.js

@@ -0,0 +1,313 @@
+/**
+ * Returns an array of numbers, starting at <tt>start</tt>, incrementing by
+ * <tt>step</tt>, until <tt>stop</tt> is reached. The stop value is
+ * exclusive. If only a single argument is specified, this value is interpeted
+ * as the <i>stop</i> value, with the <i>start</i> value as zero. If only two
+ * arguments are specified, the step value is implied to be one.
+ *
+ * <p>The method is modeled after the built-in <tt>range</tt> method from
+ * Python. See the Python documentation for more details.
+ *
+ * @see <a href="http://docs.python.org/library/functions.html#range">Python range</a>
+ * @param {number} [start] the start value.
+ * @param {number} stop the stop value.
+ * @param {number} [step] the step value.
+ * @returns {number[]} an array of numbers.
+ */
+pv.range = function(start, stop, step) {
+  if (arguments.length == 1) {
+    stop = start;
+    start = 0;
+  }
+  if (step == undefined) step = 1;
+  if ((stop - start) / step == Infinity) throw new Error("range must be finite");
+  var array = [], i = 0, j;
+  stop -= (stop - start) * 1e-10; // floating point precision!
+  if (step < 0) {
+    while ((j = start + step * i++) > stop) {
+      array.push(j);
+    }
+  } else {
+    while ((j = start + step * i++) < stop) {
+      array.push(j);
+    }
+  }
+  return array;
+};
+
+/**
+ * Returns a random number in the range [<tt>start</tt>, <tt>stop</tt>) that is
+ * a multiple of <tt>step</tt>. More specifically, the returned number is of the
+ * form <tt>start</tt> + <i>n</i> * <tt>step</tt>, where <i>n</i> is a
+ * nonnegative integer. If <tt>step</tt> is not specified, it defaults to 1,
+ * returning a random integer if <tt>start</tt> is also an integer.
+ *
+ * @param {number} [start] the start value value.
+ * @param {number} stop the stop value.
+ * @param {number} [step] the step value.
+ * @returns {number} a random number between <i>start</i> and <i>stop</i>.
+ */
+pv.random = function(start, stop, step) {
+  if (arguments.length == 1) {
+    stop = start;
+    start = 0;
+  }
+  if (step == undefined) step = 1;
+  return step
+      ? (Math.floor(Math.random() * (stop - start) / step) * step + start)
+      : (Math.random() * (stop - start) + start);
+};
+
+/**
+ * Returns the sum of the specified array. If the specified array is not an
+ * array of numbers, an optional accessor function <tt>f</tt> can be specified
+ * to map the elements to numbers. See {@link #normalize} for an example.
+ * Accessor functions can refer to <tt>this.index</tt>.
+ *
+ * @param {array} array an array of objects, or numbers.
+ * @param {function} [f] an optional accessor function.
+ * @returns {number} the sum of the specified array.
+ */
+pv.sum = function(array, f) {
+  var o = {};
+  return array.reduce(f
+      ? function(p, d, i) { o.index = i; return p + f.call(o, d); }
+      : function(p, d) { return p + d; }, 0);
+};
+
+/**
+ * Returns the maximum value of the specified array. If the specified array is
+ * not an array of numbers, an optional accessor function <tt>f</tt> can be
+ * specified to map the elements to numbers. See {@link #normalize} for an
+ * example. Accessor functions can refer to <tt>this.index</tt>.
+ *
+ * @param {array} array an array of objects, or numbers.
+ * @param {function} [f] an optional accessor function.
+ * @returns {number} the maximum value of the specified array.
+ */
+pv.max = function(array, f) {
+  if (f == pv.index) return array.length - 1;
+  return Math.max.apply(null, f ? pv.map(array, f) : array);
+};
+
+/**
+ * Returns the index of the maximum value of the specified array. If the
+ * specified array is not an array of numbers, an optional accessor function
+ * <tt>f</tt> can be specified to map the elements to numbers. See
+ * {@link #normalize} for an example. Accessor functions can refer to
+ * <tt>this.index</tt>.
+ *
+ * @param {array} array an array of objects, or numbers.
+ * @param {function} [f] an optional accessor function.
+ * @returns {number} the index of the maximum value of the specified array.
+ */
+pv.max.index = function(array, f) {
+  if (!array.length) return -1;
+  if (f == pv.index) return array.length - 1;
+  if (!f) f = pv.identity;
+  var maxi = 0, maxx = -Infinity, o = {};
+  for (var i = 0; i < array.length; i++) {
+    o.index = i;
+    var x = f.call(o, array[i]);
+    if (x > maxx) {
+      maxx = x;
+      maxi = i;
+    }
+  }
+  return maxi;
+}
+
+/**
+ * Returns the minimum value of the specified array of numbers. If the specified
+ * array is not an array of numbers, an optional accessor function <tt>f</tt>
+ * can be specified to map the elements to numbers. See {@link #normalize} for
+ * an example. Accessor functions can refer to <tt>this.index</tt>.
+ *
+ * @param {array} array an array of objects, or numbers.
+ * @param {function} [f] an optional accessor function.
+ * @returns {number} the minimum value of the specified array.
+ */
+pv.min = function(array, f) {
+  if (f == pv.index) return 0;
+  return Math.min.apply(null, f ? pv.map(array, f) : array);
+};
+
+/**
+ * Returns the index of the minimum value of the specified array. If the
+ * specified array is not an array of numbers, an optional accessor function
+ * <tt>f</tt> can be specified to map the elements to numbers. See
+ * {@link #normalize} for an example. Accessor functions can refer to
+ * <tt>this.index</tt>.
+ *
+ * @param {array} array an array of objects, or numbers.
+ * @param {function} [f] an optional accessor function.
+ * @returns {number} the index of the minimum value of the specified array.
+ */
+pv.min.index = function(array, f) {
+  if (!array.length) return -1;
+  if (f == pv.index) return 0;
+  if (!f) f = pv.identity;
+  var mini = 0, minx = Infinity, o = {};
+  for (var i = 0; i < array.length; i++) {
+    o.index = i;
+    var x = f.call(o, array[i]);
+    if (x < minx) {
+      minx = x;
+      mini = i;
+    }
+  }
+  return mini;
+}
+
+/**
+ * Returns the arithmetic mean, or average, of the specified array. If the
+ * specified array is not an array of numbers, an optional accessor function
+ * <tt>f</tt> can be specified to map the elements to numbers. See
+ * {@link #normalize} for an example. Accessor functions can refer to
+ * <tt>this.index</tt>.
+ *
+ * @param {array} array an array of objects, or numbers.
+ * @param {function} [f] an optional accessor function.
+ * @returns {number} the mean of the specified array.
+ */
+pv.mean = function(array, f) {
+  return pv.sum(array, f) / array.length;
+};
+
+/**
+ * Returns the median of the specified array. If the specified array is not an
+ * array of numbers, an optional accessor function <tt>f</tt> can be specified
+ * to map the elements to numbers. See {@link #normalize} for an example.
+ * Accessor functions can refer to <tt>this.index</tt>.
+ *
+ * @param {array} array an array of objects, or numbers.
+ * @param {function} [f] an optional accessor function.
+ * @returns {number} the median of the specified array.
+ */
+pv.median = function(array, f) {
+  if (f == pv.index) return (array.length - 1) / 2;
+  array = pv.map(array, f).sort(pv.naturalOrder);
+  if (array.length % 2) return array[Math.floor(array.length / 2)];
+  var i = array.length / 2;
+  return (array[i - 1] + array[i]) / 2;
+};
+
+/**
+ * Returns the unweighted variance of the specified array. If the specified
+ * array is not an array of numbers, an optional accessor function <tt>f</tt>
+ * can be specified to map the elements to numbers. See {@link #normalize} for
+ * an example. Accessor functions can refer to <tt>this.index</tt>.
+ *
+ * @param {array} array an array of objects, or numbers.
+ * @param {function} [f] an optional accessor function.
+ * @returns {number} the variance of the specified array.
+ */
+pv.variance = function(array, f) {
+  if (array.length < 1) return NaN;
+  if (array.length == 1) return 0;
+  var mean = pv.mean(array, f), sum = 0, o = {};
+  if (!f) f = pv.identity;
+  for (var i = 0; i < array.length; i++) {
+    o.index = i;
+    var d = f.call(o, array[i]) - mean;
+    sum += d * d;
+  }
+  return sum;
+};
+
+/**
+ * Returns an unbiased estimation of the standard deviation of a population,
+ * given the specified random sample. If the specified array is not an array of
+ * numbers, an optional accessor function <tt>f</tt> can be specified to map the
+ * elements to numbers. See {@link #normalize} for an example. Accessor
+ * functions can refer to <tt>this.index</tt>.
+ *
+ * @param {array} array an array of objects, or numbers.
+ * @param {function} [f] an optional accessor function.
+ * @returns {number} the standard deviation of the specified array.
+ */
+pv.deviation = function(array, f) {
+  return Math.sqrt(pv.variance(array, f) / (array.length - 1));
+};
+
+/**
+ * Returns the logarithm with a given base value.
+ *
+ * @param {number} x the number for which to compute the logarithm.
+ * @param {number} b the base of the logarithm.
+ * @returns {number} the logarithm value.
+ */
+pv.log = function(x, b) {
+  return Math.log(x) / Math.log(b);
+};
+
+/**
+ * Computes a zero-symmetric logarithm. Computes the logarithm of the absolute
+ * value of the input, and determines the sign of the output according to the
+ * sign of the input value.
+ *
+ * @param {number} x the number for which to compute the logarithm.
+ * @param {number} b the base of the logarithm.
+ * @returns {number} the symmetric log value.
+ */
+pv.logSymmetric = function(x, b) {
+  return (x == 0) ? 0 : ((x < 0) ? -pv.log(-x, b) : pv.log(x, b));
+};
+
+/**
+ * Computes a zero-symmetric logarithm, with adjustment to values between zero
+ * and the logarithm base. This adjustment introduces distortion for values less
+ * than the base number, but enables simultaneous plotting of log-transformed
+ * data involving both positive and negative numbers.
+ *
+ * @param {number} x the number for which to compute the logarithm.
+ * @param {number} b the base of the logarithm.
+ * @returns {number} the adjusted, symmetric log value.
+ */
+pv.logAdjusted = function(x, b) {
+  if (!isFinite(x)) return x;
+  var negative = x < 0;
+  if (x < b) x += (b - x) / b;
+  return negative ? -pv.log(x, b) : pv.log(x, b);
+};
+
+/**
+ * Rounds an input value down according to its logarithm. The method takes the
+ * floor of the logarithm of the value and then uses the resulting value as an
+ * exponent for the base value.
+ *
+ * @param {number} x the number for which to compute the logarithm floor.
+ * @param {number} b the base of the logarithm.
+ * @returns {number} the rounded-by-logarithm value.
+ */
+pv.logFloor = function(x, b) {
+  return (x > 0)
+      ? Math.pow(b, Math.floor(pv.log(x, b)))
+      : -Math.pow(b, -Math.floor(-pv.log(-x, b)));
+};
+
+/**
+ * Rounds an input value up according to its logarithm. The method takes the
+ * ceiling of the logarithm of the value and then uses the resulting value as an
+ * exponent for the base value.
+ *
+ * @param {number} x the number for which to compute the logarithm ceiling.
+ * @param {number} b the base of the logarithm.
+ * @returns {number} the rounded-by-logarithm value.
+ */
+pv.logCeil = function(x, b) {
+  return (x > 0)
+      ? Math.pow(b, Math.ceil(pv.log(x, b)))
+      : -Math.pow(b, -Math.ceil(-pv.log(-x, b)));
+};
+
+(function() {
+  var radians = Math.PI / 180,
+      degrees = 180 / Math.PI;
+
+  /** Returns the number of radians corresponding to the specified degrees. */
+  pv.radians = function(degrees) { return radians * degrees; };
+
+  /** Returns the number of degrees corresponding to the specified radians. */
+  pv.degrees = function(radians) { return degrees * radians; };
+})();