rubyvis 0.1.0 → 0.1.1

data/vendor/src/data/Flatten.js

@@ -0,0 +1,146 @@
+/**
+ * Returns a {@link pv.Flatten} operator for the specified map. This is a
+ * convenience factory method, equivalent to <tt>new pv.Flatten(map)</tt>.
+ *
+ * @see pv.Flatten
+ * @param map a map to flatten.
+ * @returns {pv.Flatten} a flatten operator for the specified map.
+ */
+pv.flatten = function(map) {
+  return new pv.Flatten(map);
+};
+
+/**
+ * Constructs a flatten operator for the specified map. This constructor should
+ * not be invoked directly; use {@link pv.flatten} instead.
+ *
+ * @class Represents a flatten operator for the specified array. Flattening
+ * allows hierarchical maps to be flattened into an array. The levels in the
+ * input tree are specified by <i>key</i> functions.
+ *
+ * <p>For example, consider the following hierarchical data structure of Barley
+ * yields, from various sites in Minnesota during 1931-2:
+ *
+ * <pre>{ 1931: {
+ *     Manchuria: {
+ *       "University Farm": 27.00,
+ *       "Waseca": 48.87,
+ *       "Morris": 27.43,
+ *       ... },
+ *     Glabron: {
+ *       "University Farm": 43.07,
+ *       "Waseca": 55.20,
+ *       ... } },
+ *   1932: {
+ *     ... } }</pre>
+ *
+ * To facilitate visualization, it may be useful to flatten the tree into a
+ * tabular array:
+ *
+ * <pre>var array = pv.flatten(yields)
+ *     .key("year")
+ *     .key("variety")
+ *     .key("site")
+ *     .key("yield")
+ *     .array();</pre>
+ *
+ * This returns an array of object elements. Each element in the array has
+ * attributes corresponding to this flatten operator's keys:
+ *
+ * <pre>{ site: "University Farm", variety: "Manchuria", year: 1931, yield: 27 },
+ * { site: "Waseca", variety: "Manchuria", year: 1931, yield: 48.87 },
+ * { site: "Morris", variety: "Manchuria", year: 1931, yield: 27.43 },
+ * { site: "University Farm", variety: "Glabron", year: 1931, yield: 43.07 },
+ * { site: "Waseca", variety: "Glabron", year: 1931, yield: 55.2 }, ...</pre>
+ *
+ * <p>The flatten operator is roughly the inverse of the {@link pv.Nest} and
+ * {@link pv.Tree} operators.
+ *
+ * @param map a map to flatten.
+ */
+pv.Flatten = function(map) {
+  this.map = map;
+  this.keys = [];
+};
+
+/**
+ * Flattens using the specified key function. Multiple keys may be added to the
+ * flatten; the tiers of the underlying tree must correspond to the specified
+ * keys, in order. The order of the returned array is undefined; however, you
+ * can easily sort it.
+ *
+ * @param {string} key the key name.
+ * @param {function} [f] an optional value map function.
+ * @returns {pv.Nest} this.
+ */
+pv.Flatten.prototype.key = function(key, f) {
+  this.keys.push({name: key, value: f});
+  delete this.$leaf;
+  return this;
+};
+
+/**
+ * Flattens using the specified leaf function. This is an alternative to
+ * specifying an explicit set of keys; the tiers of the underlying tree will be
+ * determined dynamically by recursing on the values, and the resulting keys
+ * will be stored in the entries <tt>keys</tt> attribute. The leaf function must
+ * return true for leaves, and false for internal nodes.
+ *
+ * @param {function} f a leaf function.
+ * @returns {pv.Nest} this.
+ */
+pv.Flatten.prototype.leaf = function(f) {
+  this.keys.length = 0;
+  this.$leaf = f;
+  return this;
+};
+
+/**
+ * Returns the flattened array. Each entry in the array is an object; each
+ * object has attributes corresponding to this flatten operator's keys.
+ *
+ * @returns an array of elements from the flattened map.
+ */
+pv.Flatten.prototype.array = function() {
+  var entries = [], stack = [], keys = this.keys, leaf = this.$leaf;
+
+  /* Recursively visit using the leaf function. */
+  if (leaf) {
+    function recurse(value, i) {
+      if (leaf(value)) {
+        entries.push({keys: stack.slice(), value: value});
+      } else {
+        for (var key in value) {
+          stack.push(key);
+          recurse(value[key], i + 1);
+          stack.pop();
+        }
+      }
+    }
+    recurse(this.map, 0);
+    return entries;
+  }
+
+  /* Recursively visits the specified value. */
+  function visit(value, i) {
+    if (i < keys.length - 1) {
+      for (var key in value) {
+        stack.push(key);
+        visit(value[key], i + 1);
+        stack.pop();
+      }
+    } else {
+      entries.push(stack.concat(value));
+    }
+  }
+
+  visit(this.map, 0);
+  return entries.map(function(stack) {
+      var m = {};
+      for (var i = 0; i < keys.length; i++) {
+        var k = keys[i], v = stack[i];
+        m[k.name] = k.value ? k.value.call(null, v) : v;
+      }
+      return m;
+    });
+};

data/vendor/src/data/Histogram.js

@@ -0,0 +1,120 @@
+/**
+ * Returns a histogram operator for the specified data, with an optional
+ * accessor function. If the data specified is not an array of numbers, an
+ * accessor function must be specified to map the data to numeric values.
+ *
+ * @class Represents a histogram operator.
+ *
+ * @param {array} data an array of numbers or objects.
+ * @param {function} [f] an optional accessor function.
+ */
+pv.histogram = function(data, f) {
+  var frequency = true;
+  return {
+
+    /**
+     * Returns the computed histogram bins. An optional array of numbers,
+     * <tt>ticks</tt>, may be specified as the break points. If the ticks are
+     * not specified, default ticks will be computed using a linear scale on the
+     * data domain.
+     *
+     * <p>The returned array contains {@link pv.histogram.Bin}s. The <tt>x</tt>
+     * attribute corresponds to the bin's start value (inclusive), while the
+     * <tt>dx</tt> attribute stores the bin size (end - start). The <tt>y</tt>
+     * attribute stores either the frequency count or probability, depending on
+     * how the histogram operator has been configured.
+     *
+     * <p>The {@link pv.histogram.Bin} objects are themselves arrays, containing
+     * the data elements present in each bin, i.e., the elements in the
+     * <tt>data</tt> array (prior to invoking the accessor function, if any).
+     * For example, if the data represented countries, and the accessor function
+     * returned the GDP of each country, the returned bins would be arrays of
+     * countries (not GDPs).
+     *
+     * @function
+     * @name pv.histogram.prototype.bins
+     * @param {array} [ticks]
+     * @returns {array}
+     */ /** @private */
+    bins: function(ticks) {
+      var x = pv.map(data, f), bins = [];
+
+      /* Initialize default ticks. */
+      if (!arguments.length) ticks = pv.Scale.linear(x).ticks();
+
+      /* Initialize the bins. */
+      for (var i = 0; i < ticks.length - 1; i++) {
+        var bin = bins[i] = [];
+        bin.x = ticks[i];
+        bin.dx = ticks[i + 1] - ticks[i];
+        bin.y = 0;
+      }
+
+      /* Count the number of samples per bin. */
+      for (var i = 0; i < x.length; i++) {
+        var j = pv.search.index(ticks, x[i]) - 1,
+            bin = bins[Math.max(0, Math.min(bins.length - 1, j))];
+        bin.y++;
+        bin.push(data[i]);
+      }
+
+      /* Convert frequencies to probabilities. */
+      if (!frequency) for (var i = 0; i < bins.length; i++) {
+        bins[i].y /= x.length;
+      }
+
+      return bins;
+    },
+
+    /**
+     * Sets or gets whether this histogram operator returns frequencies or
+     * probabilities.
+     *
+     * @function
+     * @name pv.histogram.prototype.frequency
+     * @param {boolean} [x]
+     * @returns {pv.histogram} this.
+     */ /** @private */
+    frequency: function(x) {
+      if (arguments.length) {
+        frequency = Boolean(x);
+        return this;
+      }
+      return frequency;
+    }
+  };
+};
+
+/**
+ * @class Represents a bin returned by the {@link pv.histogram} operator. Bins
+ * are themselves arrays containing the data elements present in the given bin
+ * (prior to the accessor function being invoked to convert the data object to a
+ * numeric value). These bin arrays have additional attributes with meta
+ * information about the bin.
+ *
+ * @name pv.histogram.Bin
+ * @extends array
+ * @see pv.histogram
+ */
+
+/**
+ * The start value of the bin's range.
+ *
+ * @type number
+ * @name pv.histogram.Bin.prototype.x
+ */
+
+/**
+ * The magnitude value of the bin's range; end - start.
+ *
+ * @type number
+ * @name pv.histogram.Bin.prototype.dx
+ */
+
+/**
+ * The frequency or probability of the bin, depending on how the histogram
+ * operator was configured.
+ *
+ * @type number
+ * @name pv.histogram.Bin.prototype.y
+ */

data/vendor/src/data/LinearScale.js

@@ -0,0 +1,54 @@
+/**
+ * Returns a linear scale for the specified domain. The arguments to this
+ * constructor are optional, and equivalent to calling {@link #domain}.
+ * The default domain and range are [0,1].
+ *
+ * @class Represents a linear scale; a function that performs a linear
+ * transformation. <style type="text/css">sub{line-height:0}</style> Most
+ * commonly, a linear scale represents a 1-dimensional linear transformation
+ * from a numeric domain of input data [<i>d<sub>0</sub></i>,
+ * <i>d<sub>1</sub></i>] to a numeric range of pixels [<i>r<sub>0</sub></i>,
+ * <i>r<sub>1</sub></i>]. The equation for such a scale is:
+ *
+ * <blockquote><i>f(x) = (x - d<sub>0</sub>) / (d<sub>1</sub> - d<sub>0</sub>) *
+ * (r<sub>1</sub> - r<sub>0</sub>) + r<sub>0</sub></i></blockquote>
+ *
+ * For example, a linear scale from the domain [0, 100] to range [0, 640]:
+ *
+ * <blockquote><i>f(x) = (x - 0) / (100 - 0) * (640 - 0) + 0</i><br>
+ * <i>f(x) = x / 100 * 640</i><br>
+ * <i>f(x) = x * 6.4</i><br>
+ * </blockquote>
+ *
+ * Thus, saying
+ *
+ * <pre>    .height(function(d) d * 6.4)</pre>
+ *
+ * is identical to
+ *
+ * <pre>    .height(pv.Scale.linear(0, 100).range(0, 640))</pre>
+ *
+ * Note that the scale is itself a function, and thus can be used as a property
+ * directly, assuming that the data associated with a mark is a number. While
+ * this is convenient for single-use scales, frequently it is desirable to
+ * define scales globally:
+ *
+ * <pre>var y = pv.Scale.linear(0, 100).range(0, 640);</pre>
+ *
+ * The <tt>y</tt> scale can now be equivalently referenced within a property:
+ *
+ * <pre>    .height(function(d) y(d))</pre>
+ *
+ * Alternatively, if the data are not simple numbers, the appropriate value can
+ * be passed to the <tt>y</tt> scale (e.g., <tt>d.foo</tt>). The {@link #by}
+ * method similarly allows the data to be mapped to a numeric value before
+ * performing the linear transformation.
+ *
+ * @param {number...} domain... optional domain values.
+ * @extends pv.Scale.quantitative
+ */
+pv.Scale.linear = function() {
+  var scale = pv.Scale.quantitative();
+  scale.domain.apply(scale, arguments);
+  return scale;
+};

data/vendor/src/data/LogScale.js

@@ -0,0 +1,142 @@
+/**
+ * Returns a log scale for the specified domain. The arguments to this
+ * constructor are optional, and equivalent to calling {@link #domain}.
+ * The default domain is [1,10] and the default range is [0,1].
+ *
+ * @class Represents a log scale. <style
+ * type="text/css">sub{line-height:0}</style> Most commonly, a log scale
+ * represents a 1-dimensional log transformation from a numeric domain of input
+ * data [<i>d<sub>0</sub></i>, <i>d<sub>1</sub></i>] to a numeric range of
+ * pixels [<i>r<sub>0</sub></i>, <i>r<sub>1</sub></i>]. The equation for such a
+ * scale is:
+ *
+ * <blockquote><i>f(x) = (log(x) - log(d<sub>0</sub>)) / (log(d<sub>1</sub>) -
+ * log(d<sub>0</sub>)) * (r<sub>1</sub> - r<sub>0</sub>) +
+ * r<sub>0</sub></i></blockquote>
+ *
+ * where <i>log(x)</i> represents the zero-symmetric logarthim of <i>x</i> using
+ * the scale's associated base (default: 10, see {@link pv.logSymmetric}). For
+ * example, a log scale from the domain [1, 100] to range [0, 640]:
+ *
+ * <blockquote><i>f(x) = (log(x) - log(1)) / (log(100) - log(1)) * (640 - 0) + 0</i><br>
+ * <i>f(x) = log(x) / 2 * 640</i><br>
+ * <i>f(x) = log(x) * 320</i><br>
+ * </blockquote>
+ *
+ * Thus, saying
+ *
+ * <pre>    .height(function(d) Math.log(d) * 138.974)</pre>
+ *
+ * is equivalent to
+ *
+ * <pre>    .height(pv.Scale.log(1, 100).range(0, 640))</pre>
+ *
+ * Note that the scale is itself a function, and thus can be used as a property
+ * directly, assuming that the data associated with a mark is a number. While
+ * this is convenient for single-use scales, frequently it is desirable to
+ * define scales globally:
+ *
+ * <pre>var y = pv.Scale.log(1, 100).range(0, 640);</pre>
+ *
+ * The <tt>y</tt> scale can now be equivalently referenced within a property:
+ *
+ * <pre>    .height(function(d) y(d))</pre>
+ *
+ * Alternatively, if the data are not simple numbers, the appropriate value can
+ * be passed to the <tt>y</tt> scale (e.g., <tt>d.foo</tt>). The {@link #by}
+ * method similarly allows the data to be mapped to a numeric value before
+ * performing the log transformation.
+ *
+ * @param {number...} domain... optional domain values.
+ * @extends pv.Scale.quantitative
+ */
+pv.Scale.log = function() {
+  var scale = pv.Scale.quantitative(1, 10),
+      b, // logarithm base
+      p, // cached Math.log(b)
+      /** @ignore */ log = function(x) { return Math.log(x) / p; },
+      /** @ignore */ pow = function(y) { return Math.pow(b, y); };
+
+  /**
+   * Returns an array of evenly-spaced, suitably-rounded values in the input
+   * domain. These values are frequently used in conjunction with
+   * {@link pv.Rule} to display tick marks or grid lines.
+   *
+   * @function
+   * @name pv.Scale.log.prototype.ticks
+   * @returns {number[]} an array input domain values to use as ticks.
+   */
+  scale.ticks = function() {
+    // TODO support non-uniform domains
+    var d = scale.domain(),
+        n = d[0] < 0,
+        i = Math.floor(n ? -log(-d[0]) : log(d[0])),
+        j = Math.ceil(n ? -log(-d[1]) : log(d[1])),
+        ticks = [];
+    if (n) {
+      ticks.push(-pow(-i));
+      for (; i++ < j;) for (var k = b - 1; k > 0; k--) ticks.push(-pow(-i) * k);
+    } else {
+      for (; i < j; i++) for (var k = 1; k < b; k++) ticks.push(pow(i) * k);
+      ticks.push(pow(i));
+    }
+    for (i = 0; ticks[i] < d[0]; i++); // strip small values
+    for (j = ticks.length; ticks[j - 1] > d[1]; j--); // strip big values
+    return ticks.slice(i, j);
+  };
+
+  /**
+   * Formats the specified tick value using the appropriate precision, assuming
+   * base 10.
+   *
+   * @function
+   * @name pv.Scale.log.prototype.tickFormat
+   * @param {number} t a tick value.
+   * @returns {string} a formatted tick value.
+   */
+  scale.tickFormat = function(t) {
+    return t.toPrecision(1);
+  };
+
+  /**
+   * "Nices" this scale, extending the bounds of the input domain to
+   * evenly-rounded values. This method uses {@link pv.logFloor} and
+   * {@link pv.logCeil}. Nicing is useful if the domain is computed dynamically
+   * from data, and may be irregular. For example, given a domain of
+   * [0.20147987687960267, 0.996679553296417], a call to <tt>nice()</tt> might
+   * extend the domain to [0.1, 1].
+   *
+   * <p>This method must be invoked each time after setting the domain (and
+   * base).
+   *
+   * @function
+   * @name pv.Scale.log.prototype.nice
+   * @returns {pv.Scale.log} <tt>this</tt>.
+   */
+  scale.nice = function() {
+    // TODO support non-uniform domains
+    var d = scale.domain();
+    return scale.domain(pv.logFloor(d[0], b), pv.logCeil(d[1], b));
+  };
+
+  /**
+   * Sets or gets the logarithm base. Defaults to 10.
+   *
+   * @function
+   * @name pv.Scale.log.prototype.base
+   * @param {number} [v] the new base.
+   * @returns {pv.Scale.log} <tt>this</tt>, or the current base.
+   */
+  scale.base = function(v) {
+    if (arguments.length) {
+      b = Number(v);
+      p = Math.log(b);
+      scale.transform(log, pow); // update transformed domain
+      return this;
+    }
+    return b;
+  };
+
+  scale.domain.apply(scale, arguments);
+  return scale.base(10);
+};