rubyvis 0.1.0 → 0.1.1

data/vendor/src/data/Objects.js

@@ -0,0 +1,78 @@
+/**
+ * Returns all of the property names (keys) of the specified object (a map). The
+ * order of the returned array is not defined.
+ *
+ * @param map an object.
+ * @returns {string[]} an array of strings corresponding to the keys.
+ * @see #entries
+ */
+pv.keys = function(map) {
+  var array = [];
+  for (var key in map) {
+    array.push(key);
+  }
+  return array;
+};
+
+/**
+ * Returns all of the entries (key-value pairs) of the specified object (a
+ * map). The order of the returned array is not defined. Each key-value pair is
+ * represented as an object with <tt>key</tt> and <tt>value</tt> attributes,
+ * e.g., <tt>{key: "foo", value: 42}</tt>.
+ *
+ * @param map an object.
+ * @returns {array} an array of key-value pairs corresponding to the keys.
+ */
+pv.entries = function(map) {
+  var array = [];
+  for (var key in map) {
+    array.push({ key: key, value: map[key] });
+  }
+  return array;
+};
+
+/**
+ * Returns all of the values (attribute values) of the specified object (a
+ * map). The order of the returned array is not defined.
+ *
+ * @param map an object.
+ * @returns {array} an array of objects corresponding to the values.
+ * @see #entries
+ */
+pv.values = function(map) {
+  var array = [];
+  for (var key in map) {
+    array.push(map[key]);
+  }
+  return array;
+};
+
+/**
+ * Returns a map constructed from the specified <tt>keys</tt>, using the
+ * function <tt>f</tt> to compute the value for each key. The single argument to
+ * the value function is the key. The callback is invoked only for indexes of
+ * the array which have assigned values; it is not invoked for indexes which
+ * have been deleted or which have never been assigned values.
+ *
+ * <p>For example, this expression creates a map from strings to string length:
+ *
+ * <pre>pv.dict(["one", "three", "seventeen"], function(s) s.length)</pre>
+ *
+ * The returned value is <tt>{one: 3, three: 5, seventeen: 9}</tt>. Accessor
+ * functions can refer to <tt>this.index</tt>.
+ *
+ * @param {array} keys an array.
+ * @param {function} f a value function.
+ * @returns a map from keys to values.
+ */
+pv.dict = function(keys, f) {
+  var m = {}, o = {};
+  for (var i = 0; i < keys.length; i++) {
+    if (i in keys) {
+      var k = keys[i];
+      o.index = i;
+      m[k] = f.call(o, k);
+    }
+  }
+  return m;
+};

data/vendor/src/data/OrdinalScale.js

@@ -0,0 +1,267 @@
+/**
+ * Returns an ordinal scale for the specified domain. The arguments to this
+ * constructor are optional, and equivalent to calling {@link #domain}.
+ *
+ * @class Represents an ordinal scale. <style
+ * type="text/css">sub{line-height:0}</style> An ordinal scale represents a
+ * pairwise mapping from <i>n</i> discrete values in the input domain to
+ * <i>n</i> discrete values in the output range. For example, an ordinal scale
+ * might map a domain of species ["setosa", "versicolor", "virginica"] to colors
+ * ["red", "green", "blue"]. Thus, saying
+ *
+ * <pre>    .fillStyle(function(d) {
+ *         switch (d.species) {
+ *           case "setosa": return "red";
+ *           case "versicolor": return "green";
+ *           case "virginica": return "blue";
+ *         }
+ *       })</pre>
+ *
+ * is equivalent to
+ *
+ * <pre>    .fillStyle(pv.Scale.ordinal("setosa", "versicolor", "virginica")
+ *         .range("red", "green", "blue")
+ *         .by(function(d) d.species))</pre>
+ *
+ * If the mapping from species to color does not need to be specified
+ * explicitly, the domain can be omitted. In this case it will be inferred
+ * lazily from the data:
+ *
+ * <pre>    .fillStyle(pv.colors("red", "green", "blue")
+ *         .by(function(d) d.species))</pre>
+ *
+ * When the domain is inferred, the first time the scale is invoked, the first
+ * element from the range will be returned. Subsequent calls with unique values
+ * will return subsequent elements from the range. If the inferred domain grows
+ * larger than the range, range values will be reused. However, it is strongly
+ * recommended that the domain and the range contain the same number of
+ * elements.
+ *
+ * <p>A range can be discretized from a continuous interval (e.g., for pixel
+ * positioning) by using {@link #split}, {@link #splitFlush} or
+ * {@link #splitBanded} after the domain has been set. For example, if
+ * <tt>states</tt> is an array of the fifty U.S. state names, the state name can
+ * be encoded in the left position:
+ *
+ * <pre>    .left(pv.Scale.ordinal(states)
+ *         .split(0, 640)
+ *         .by(function(d) d.state))</pre>
+ *
+ * <p>N.B.: ordinal scales are not invertible (at least not yet), since the
+ * domain and range and discontinuous. A workaround is to use a linear scale.
+ *
+ * @param {...} domain... optional domain values.
+ * @extends pv.Scale
+ * @see pv.colors
+ */
+pv.Scale.ordinal = function() {
+  var d = [], i = {}, r = [], band = 0;
+
+  /** @private */
+  function scale(x) {
+    if (!(x in i)) i[x] = d.push(x) - 1;
+    return r[i[x] % r.length];
+  }
+
+  /**
+   * Sets or gets the input domain. This method can be invoked several ways:
+   *
+   * <p>1. <tt>domain(values...)</tt>
+   *
+   * <p>Specifying the domain as a series of values is the most explicit and
+   * recommended approach. However, if the domain values are derived from data,
+   * you may find the second method more appropriate.
+   *
+   * <p>2. <tt>domain(array, f)</tt>
+   *
+   * <p>Rather than enumerating the domain values as explicit arguments to this
+   * method, you can specify a single argument of an array. In addition, you can
+   * specify an optional accessor function to extract the domain values from the
+   * array.
+   *
+   * <p>3. <tt>domain()</tt>
+   *
+   * <p>Invoking the <tt>domain</tt> method with no arguments returns the
+   * current domain as an array.
+   *
+   * @function
+   * @name pv.Scale.ordinal.prototype.domain
+   * @param {...} domain... domain values.
+   * @returns {pv.Scale.ordinal} <tt>this</tt>, or the current domain.
+   */
+  scale.domain = function(array, f) {
+    if (arguments.length) {
+      array = (array instanceof Array)
+          ? ((arguments.length > 1) ? pv.map(array, f) : array)
+          : Array.prototype.slice.call(arguments);
+
+      /* Filter the specified ordinals to their unique values. */
+      d = [];
+      var seen = {};
+      for (var j = 0; j < array.length; j++) {
+        var o = array[j];
+        if (!(o in seen)) {
+          seen[o] = true;
+          d.push(o);
+        }
+      }
+
+      i = pv.numerate(d);
+      return this;
+    }
+    return d;
+  };
+
+  /**
+   * Sets or gets the output range. This method can be invoked several ways:
+   *
+   * <p>1. <tt>range(values...)</tt>
+   *
+   * <p>Specifying the range as a series of values is the most explicit and
+   * recommended approach. However, if the range values are derived from data,
+   * you may find the second method more appropriate.
+   *
+   * <p>2. <tt>range(array, f)</tt>
+   *
+   * <p>Rather than enumerating the range values as explicit arguments to this
+   * method, you can specify a single argument of an array. In addition, you can
+   * specify an optional accessor function to extract the range values from the
+   * array.
+   *
+   * <p>3. <tt>range()</tt>
+   *
+   * <p>Invoking the <tt>range</tt> method with no arguments returns the
+   * current range as an array.
+   *
+   * @function
+   * @name pv.Scale.ordinal.prototype.range
+   * @param {...} range... range values.
+   * @returns {pv.Scale.ordinal} <tt>this</tt>, or the current range.
+   */
+  scale.range = function(array, f) {
+    if (arguments.length) {
+      r = (array instanceof Array)
+          ? ((arguments.length > 1) ? pv.map(array, f) : array)
+          : Array.prototype.slice.call(arguments);
+      if (typeof r[0] == "string") r = r.map(pv.color);
+      return this;
+    }
+    return r;
+  };
+
+  /**
+   * Sets the range from the given continuous interval. The interval
+   * [<i>min</i>, <i>max</i>] is subdivided into <i>n</i> equispaced points,
+   * where <i>n</i> is the number of (unique) values in the domain. The first
+   * and last point are offset from the edge of the range by half the distance
+   * between points.
+   *
+   * <p>This method must be called <i>after</i> the domain is set.
+   *
+   * @function
+   * @name pv.Scale.ordinal.prototype.split
+   * @param {number} min minimum value of the output range.
+   * @param {number} max maximum value of the output range.
+   * @returns {pv.Scale.ordinal} <tt>this</tt>.
+   * @see #splitFlush
+   * @see #splitBanded
+   */
+  scale.split = function(min, max) {
+    var step = (max - min) / this.domain().length;
+    r = pv.range(min + step / 2, max, step);
+    return this;
+  };
+
+  /**
+   * Sets the range from the given continuous interval. The interval
+   * [<i>min</i>, <i>max</i>] is subdivided into <i>n</i> equispaced points,
+   * where <i>n</i> is the number of (unique) values in the domain. The first
+   * and last point are exactly on the edge of the range.
+   *
+   * <p>This method must be called <i>after</i> the domain is set.
+   *
+   * @function
+   * @name pv.Scale.ordinal.prototype.splitFlush
+   * @param {number} min minimum value of the output range.
+   * @param {number} max maximum value of the output range.
+   * @returns {pv.Scale.ordinal} <tt>this</tt>.
+   * @see #split
+   */
+  scale.splitFlush = function(min, max) {
+    var n = this.domain().length, step = (max - min) / (n - 1);
+    r = (n == 1) ? [(min + max) / 2]
+        : pv.range(min, max + step / 2, step);
+    return this;
+  };
+
+  /**
+   * Sets the range from the given continuous interval. The interval
+   * [<i>min</i>, <i>max</i>] is subdivided into <i>n</i> equispaced bands,
+   * where <i>n</i> is the number of (unique) values in the domain. The first
+   * and last band are offset from the edge of the range by the distance between
+   * bands.
+   *
+   * <p>The band width argument, <tt>band</tt>, is typically in the range [0, 1]
+   * and defaults to 1. This fraction corresponds to the amount of space in the
+   * range to allocate to the bands, as opposed to padding. A value of 0.5 means
+   * that the band width will be equal to the padding width. The computed
+   * absolute band width can be retrieved from the range as
+   * <tt>scale.range().band</tt>.
+   *
+   * <p>If the band width argument is negative, this method will allocate bands
+   * of a <i>fixed</i> width <tt>-band</tt>, rather than a relative fraction of
+   * the available space.
+   *
+   * <p>Tip: to inset the bands by a fixed amount <tt>p</tt>, specify a minimum
+   * value of <tt>min + p</tt> (or simply <tt>p</tt>, if <tt>min</tt> is
+   * 0). Then set the mark width to <tt>scale.range().band - p</tt>.
+   *
+   * <p>This method must be called <i>after</i> the domain is set.
+   *
+   * @function
+   * @name pv.Scale.ordinal.prototype.splitBanded
+   * @param {number} min minimum value of the output range.
+   * @param {number} max maximum value of the output range.
+   * @param {number} [band] the fractional band width in [0, 1]; defaults to 1.
+   * @returns {pv.Scale.ordinal} <tt>this</tt>.
+   * @see #split
+   */
+  scale.splitBanded = function(min, max, band) {
+    if (arguments.length < 3) band = 1;
+    if (band < 0) {
+      var n = this.domain().length,
+          total = -band * n,
+          remaining = max - min - total,
+          padding = remaining / (n + 1);
+      r = pv.range(min + padding, max, padding - band);
+      r.band = -band;
+    } else {
+      var step = (max - min) / (this.domain().length + (1 - band));
+      r = pv.range(min + step * (1 - band), max, step);
+      r.band = step * band;
+    }
+    return this;
+  };
+
+  /**
+   * Returns a view of this scale by the specified accessor function <tt>f</tt>.
+   * Given a scale <tt>y</tt>, <tt>y.by(function(d) d.foo)</tt> is equivalent to
+   * <tt>function(d) y(d.foo)</tt>. This method should be used judiciously; it
+   * is typically more clear to invoke the scale directly, passing in the value
+   * to be scaled.
+   *
+   * @function
+   * @name pv.Scale.ordinal.prototype.by
+   * @param {function} f an accessor function.
+   * @returns {pv.Scale.ordinal} a view of this scale by the specified accessor
+   * function.
+   */
+  scale.by = function(f) {
+    function by() { return scale(f.apply(this, arguments)); }
+    for (var method in scale) by[method] = scale[method];
+    return by;
+  };
+
+  scale.domain.apply(scale, arguments);
+  return scale;
+};

data/vendor/src/data/QuantileScale.js

@@ -0,0 +1,180 @@
+/**
+ * Constructs a default quantile scale. The arguments to this constructor are
+ * optional, and equivalent to calling {@link #domain}. The default domain is
+ * the empty set, and the default range is [0,1].
+ *
+ * @class Represents a quantile scale; a function that maps from a value within
+ * a sortable domain to a quantized numeric range. Typically, the domain is a
+ * set of numbers, but any sortable value (such as strings) can be used as the
+ * domain of a quantile scale. The range defaults to [0,1], with 0 corresponding
+ * to the smallest value in the domain, 1 the largest, .5 the median, etc.
+ *
+ * <p>By default, the number of quantiles in the range corresponds to the number
+ * of values in the domain. The {@link #quantiles} method can be used to specify
+ * an explicit number of quantiles; for example, <tt>quantiles(4)</tt> produces
+ * a standard quartile scale. A quartile scale's range is a set of four discrete
+ * values, such as [0, 1/3, 2/3, 1]. Calling the {@link #range} method will
+ * scale these discrete values accordingly, similar to {@link
+ * pv.Scale.ordinal#splitFlush}.
+ *
+ * <p>For example, given the strings ["c", "a", "b"], a default quantile scale:
+ *
+ * <pre>pv.Scale.quantile("c", "a", "b")</pre>
+ *
+ * will return 0 for "a", .5 for "b", and 1 for "c".
+ *
+ * @extends pv.Scale
+ */
+pv.Scale.quantile = function() {
+  var n = -1, // number of quantiles
+      j = -1, // max quantile index
+      q = [], // quantile boundaries
+      d = [], // domain
+      y = pv.Scale.linear(); // range
+
+  /** @private */
+  function scale(x) {
+    return y(Math.max(0, Math.min(j, pv.search.index(q, x) - 1)) / j);
+  }
+
+  /**
+   * Sets or gets the quantile boundaries. By default, each element in the
+   * domain is in its own quantile. If the argument to this method is a number,
+   * it specifies the number of equal-sized quantiles by which to divide the
+   * domain.
+   *
+   * <p>If no arguments are specified, this method returns the quantile
+   * boundaries; the first element is always the minimum value of the domain,
+   * and the last element is the maximum value of the domain. Thus, the length
+   * of the returned array is always one greater than the number of quantiles.
+   *
+   * @function
+   * @name pv.Scale.quantile.prototype.quantiles
+   * @param {number} x the number of quantiles.
+   */
+  scale.quantiles = function(x) {
+    if (arguments.length) {
+      n = Number(x);
+      if (n < 0) {
+        q = [d[0]].concat(d);
+        j = d.length - 1;
+      } else {
+        q = [];
+        q[0] = d[0];
+        for (var i = 1; i <= n; i++) {
+          q[i] = d[~~(i * (d.length - 1) / n)];
+        }
+        j = n - 1;
+      }
+      return this;
+    }
+    return q;
+  };
+
+  /**
+   * Sets or gets the input domain. This method can be invoked several ways:
+   *
+   * <p>1. <tt>domain(values...)</tt>
+   *
+   * <p>Specifying the domain as a series of values is the most explicit and
+   * recommended approach. However, if the domain values are derived from data,
+   * you may find the second method more appropriate.
+   *
+   * <p>2. <tt>domain(array, f)</tt>
+   *
+   * <p>Rather than enumerating the domain values as explicit arguments to this
+   * method, you can specify a single argument of an array. In addition, you can
+   * specify an optional accessor function to extract the domain values from the
+   * array.
+   *
+   * <p>3. <tt>domain()</tt>
+   *
+   * <p>Invoking the <tt>domain</tt> method with no arguments returns the
+   * current domain as an array.
+   *
+   * @function
+   * @name pv.Scale.quantile.prototype.domain
+   * @param {...} domain... domain values.
+   * @returns {pv.Scale.quantile} <tt>this</tt>, or the current domain.
+   */
+  scale.domain = function(array, f) {
+    if (arguments.length) {
+      d = (array instanceof Array)
+          ? pv.map(array, f)
+          : Array.prototype.slice.call(arguments);
+      d.sort(pv.naturalOrder);
+      scale.quantiles(n); // recompute quantiles
+      return this;
+    }
+    return d;
+  };
+
+  /**
+   * Sets or gets the output range. This method can be invoked several ways:
+   *
+   * <p>1. <tt>range(min, ..., max)</tt>
+   *
+   * <p>The range may be specified as a series of numbers or colors. Most
+   * commonly, two numbers are specified: the minimum and maximum pixel values.
+   * For a color scale, values may be specified as {@link pv.Color}s or
+   * equivalent strings. For a diverging scale, or other subdivided non-uniform
+   * scales, multiple values can be specified. For example:
+   *
+   * <pre>    .range("red", "white", "green")</pre>
+   *
+   * <p>Currently, only numbers and colors are supported as range values. The
+   * number of range values must exactly match the number of domain values, or
+   * the behavior of the scale is undefined.
+   *
+   * <p>2. <tt>range()</tt>
+   *
+   * <p>Invoking the <tt>range</tt> method with no arguments returns the current
+   * range as an array of numbers or colors.
+   *
+   * @function
+   * @name pv.Scale.quantile.prototype.range
+   * @param {...} range... range values.
+   * @returns {pv.Scale.quantile} <tt>this</tt>, or the current range.
+   */
+  scale.range = function() {
+    if (arguments.length) {
+      y.range.apply(y, arguments);
+      return this;
+    }
+    return y.range();
+  };
+
+  /**
+   * Returns a view of this scale by the specified accessor function <tt>f</tt>.
+   * Given a scale <tt>y</tt>, <tt>y.by(function(d) d.foo)</tt> is equivalent to
+   * <tt>function(d) y(d.foo)</tt>.
+   *
+   * <p>This method is provided for convenience, such that scales can be
+   * succinctly defined inline. For example, given an array of data elements
+   * that have a <tt>score</tt> attribute with the domain [0, 1], the height
+   * property could be specified as:
+   *
+   * <pre>.height(pv.Scale.linear().range(0, 480).by(function(d) d.score))</pre>
+   *
+   * This is equivalent to:
+   *
+   * <pre>.height(function(d) d.score * 480)</pre>
+   *
+   * This method should be used judiciously; it is typically more clear to
+   * invoke the scale directly, passing in the value to be scaled.
+   *
+   * @function
+   * @name pv.Scale.quantile.prototype.by
+   * @param {function} f an accessor function.
+   * @returns {pv.Scale.quantile} a view of this scale by the specified
+   * accessor function.
+   */
+  scale.by = function(f) {
+    function by() { return scale(f.apply(this, arguments)); }
+    for (var method in scale) by[method] = scale[method];
+    return by;
+  };
+
+  scale.domain.apply(scale, arguments);
+  return scale;
+};