rubyvis 0.1.0 → 0.1.1

data/vendor/src/layout/Indent.js

@@ -0,0 +1,83 @@
+/**
+ * Constructs a new, empty indent layout. Layouts are not typically constructed
+ * directly; instead, they are added to an existing panel via
+ * {@link pv.Mark#add}.
+ *
+ * @class Implements a hierarchical layout using the indent algorithm. This
+ * layout implements a node-link diagram where the nodes are presented in
+ * preorder traversal, and nodes are indented based on their depth from the
+ * root. This technique is used ubiquitously by operating systems to represent
+ * file directories; although it requires much vertical space, indented trees
+ * allow efficient <i>interactive</i> exploration of trees to find a specific
+ * node. In addition they allow rapid scanning of node labels, and multivariate
+ * data such as file sizes can be displayed adjacent to the hierarchy.
+ *
+ * <p>The indent layout can be configured using the <tt>depth</tt> and
+ * <tt>breadth</tt> properties, which control the increments in pixel space for
+ * each indent and row in the layout. This layout does not support multiple
+ * orientations; the root node is rendered in the top-left, while
+ * <tt>breadth</tt> is a vertical offset from the top, and <tt>depth</tt> is a
+ * horizontal offset from the left.
+ *
+ * <p>For more details on how to use this layout, see
+ * {@link pv.Layout.Hierarchy}.
+ *
+ * @extends pv.Layout.Hierarchy
+ */
+pv.Layout.Indent = function() {
+  pv.Layout.Hierarchy.call(this);
+  this.link.interpolate("step-after");
+};
+
+pv.Layout.Indent.prototype = pv.extend(pv.Layout.Hierarchy)
+    .property("depth", Number)
+    .property("breadth", Number);
+
+/**
+ * The horizontal offset between different levels of the tree; defaults to 15.
+ *
+ * @type number
+ * @name pv.Layout.Indent.prototype.depth
+ */
+
+/**
+ * The vertical offset between nodes; defaults to 15.
+ *
+ * @type number
+ * @name pv.Layout.Indent.prototype.breadth
+ */
+
+/**
+ * Default properties for indent layouts. By default the depth and breadth
+ * offsets are 15 pixels.
+ *
+ * @type pv.Layout.Indent
+ */
+pv.Layout.Indent.prototype.defaults = new pv.Layout.Indent()
+    .extend(pv.Layout.Hierarchy.prototype.defaults)
+    .depth(15)
+    .breadth(15);
+
+/** @private */
+pv.Layout.Indent.prototype.buildImplied = function(s) {
+  if (pv.Layout.Hierarchy.prototype.buildImplied.call(this, s)) return;
+
+  var nodes = s.nodes,
+      bspace = s.breadth,
+      dspace = s.depth,
+      ax = 0,
+      ay = 0;
+
+  /** @private */
+  function position(n, breadth, depth) {
+    n.x = ax + depth++ * dspace;
+    n.y = ay + breadth++ * bspace;
+    n.midAngle = 0;
+    for (var c = n.firstChild; c; c = c.nextSibling) {
+      breadth = position(c, breadth, depth);
+    }
+    return breadth;
+  }
+
+  position(nodes[0], 1, 1);
+};

data/vendor/src/layout/Layout.js

@@ -0,0 +1,56 @@
+/**
+ * Constructs a new, empty layout with default properties. Layouts are not
+ * typically constructed directly; instead, a concrete subclass is added to an
+ * existing panel via {@link pv.Mark#add}.
+ *
+ * @class Represents an abstract layout, encapsulating a visualization technique
+ * such as a streamgraph or treemap. Layouts are themselves containers,
+ * extending from {@link pv.Panel}, and defining a set of mark prototypes as
+ * children. These mark prototypes provide default properties that together
+ * implement the given visualization technique.
+ *
+ * <p>Layouts do not initially contain any marks; any exported marks (such as a
+ * network layout's <tt>link</tt> and <tt>node</tt>) are intended to be used as
+ * prototypes. By adding a concrete mark, such as a {@link pv.Bar}, to the
+ * appropriate mark prototype, the mark is added to the layout and inherits the
+ * given properties. This approach allows further customization of the layout,
+ * either by choosing a different mark type to add, or more simply by overriding
+ * some of the layout's defined properties.
+ *
+ * <p>Each concrete layout, such as treemap or circle-packing, has different
+ * behavior and may export different mark prototypes, depending on what marks
+ * are typically needed to render the desired visualization. Therefore it is
+ * important to understand how each layout is structured, such that the provided
+ * mark prototypes are used appropriately.
+ *
+ * <p>In addition to the mark prototypes, layouts may define custom properties
+ * that affect the overall behavior of the layout. For example, a treemap layout
+ * might use a property to specify which layout algorithm to use. These
+ * properties are just like other mark properties, and can be defined as
+ * constants or as functions. As with panels, the data property can be used to
+ * replicate layouts, and properties can be defined to in terms of layout data.
+ *
+ * @extends pv.Panel
+ */
+pv.Layout = function() {
+  pv.Panel.call(this);
+};
+
+pv.Layout.prototype = pv.extend(pv.Panel);
+
+/**
+ * @private Defines a local property with the specified name and cast. Note that
+ * although the property method is only defined locally, the cast function is
+ * global, which is necessary since properties are inherited!
+ *
+ * @param {string} name the property name.
+ * @param {function} [cast] the cast function for this property.
+ */
+pv.Layout.prototype.property = function(name, cast) {
+  if (!this.hasOwnProperty("properties")) {
+    this.properties = pv.extend(this.properties);
+  }
+  this.properties[name] = true;
+  this.propertyMethod(name, false, pv.Mark.cast[name] = cast);
+  return this;
+};

data/vendor/src/layout/Matrix.js

@@ -0,0 +1,177 @@
+/**
+ * Constructs a new, empty matrix network layout. Layouts are not typically
+ * constructed directly; instead, they are added to an existing panel via
+ * {@link pv.Mark#add}.
+ *
+ * @class Implements a network visualization using a matrix view. This is, in
+ * effect, a visualization of the graph's <i>adjacency matrix</i>: the cell at
+ * row <i>i</i>, column <i>j</i>, corresponds to the link from node <i>i</i> to
+ * node <i>j</i>. The fill color of each cell is binary by default, and
+ * corresponds to whether a link exists between the two nodes. If the underlying
+ * graph has links with variable values, the <tt>fillStyle</tt> property can be
+ * substited to use an appropriate color function, such as {@link pv.ramp}.
+ *
+ * <p>For undirected networks, the matrix is symmetric around the diagonal. For
+ * directed networks, links in opposite directions can be rendered on opposite
+ * sides of the diagonal using <tt>directed(true)</tt>. The graph is assumed to
+ * be undirected by default.
+ *
+ * <p>The mark prototypes for this network layout are slightly different than
+ * other implementations:<ul>
+ *
+ * <li><tt>node</tt> - unsupported; undefined. No mark is needed to visualize
+ * nodes directly, as the nodes are implicit in the location (rows and columns)
+ * of the links.
+ *
+ * <p><li><tt>link</tt> - for rendering links; typically a {@link pv.Bar}. The
+ * link mark is added directly to the layout, with the data property defined as
+ * all possible pairs of nodes. Each pair is represented as a
+ * {@link pv.Network.Layout.Link}, though the <tt>linkValue</tt> attribute may
+ * be 0 if no link exists in the graph.
+ *
+ * <p><li><tt>label</tt> - for rendering node labels; typically a
+ * {@link pv.Label}. The label mark is added directly to the layout, with the
+ * data property defined via the layout's <tt>nodes</tt> property; note,
+ * however, that the nodes are duplicated so as to provide a label across the
+ * top and down the side. Properties such as <tt>strokeStyle</tt> and
+ * <tt>fillStyle</tt> can be overridden to compute properties from node data
+ * dynamically.
+ *
+ * </ul>For more details on how to use this layout, see
+ * {@link pv.Layout.Network}.
+ *
+ * @extends pv.Layout.Network
+ */
+pv.Layout.Matrix = function() {
+  pv.Layout.Network.call(this);
+  var that = this,
+      n, // cached matrix size
+      dx, // cached cell width
+      dy, // cached cell height
+      labels, // cached labels (array of strings)
+      pairs, // cached pairs (array of links)
+      buildImplied = that.buildImplied;
+
+  /** @private Cache layout state to optimize properties. */
+  this.buildImplied = function(s) {
+    buildImplied.call(this, s);
+    n = s.nodes.length;
+    dx = s.width / n;
+    dy = s.height / n;
+    labels = s.$matrix.labels;
+    pairs = s.$matrix.pairs;
+  };
+
+  /* Links are all pairs of nodes. */
+  this.link
+      .data(function() { return pairs; })
+      .left(function() { return dx * (this.index % n); })
+      .top(function() { return dy * Math.floor(this.index / n); })
+      .width(function() { return dx; })
+      .height(function() { return dy; })
+      .lineWidth(1.5)
+      .strokeStyle("#fff")
+      .fillStyle(function(l) { return l.linkValue ? "#555" : "#eee"; })
+      .parent = this;
+
+  /* No special add for links! */
+  delete this.link.add;
+
+  /* Labels are duplicated for top & left. */
+  this.label
+      .data(function() { return labels; })
+      .left(function() { return this.index & 1 ? dx * ((this.index >> 1) + .5) : 0; })
+      .top(function() { return this.index & 1 ? 0 : dy * ((this.index >> 1) + .5); })
+      .textMargin(4)
+      .textAlign(function() { return this.index & 1 ? "left" : "right"; })
+      .textAngle(function() { return this.index & 1 ? -Math.PI / 2 : 0; });
+
+  /* The node mark is unused. */
+  delete this.node;
+};
+
+pv.Layout.Matrix.prototype = pv.extend(pv.Layout.Network)
+    .property("directed", Boolean);
+
+/**
+ * Whether this matrix visualization is directed (bidirectional). By default,
+ * the graph is assumed to be undirected, such that the visualization is
+ * symmetric across the matrix diagonal. If the network is directed, then
+ * forward links are drawn above the diagonal, while reverse links are drawn
+ * below.
+ *
+ * @type boolean
+ * @name pv.Layout.Matrix.prototype.directed
+ */
+
+/**
+ * Specifies an optional sort function. The sort function follows the same
+ * comparator contract required by {@link pv.Dom.Node#sort}. Specifying a sort
+ * function provides an alternative to sort the nodes as they are specified by
+ * the <tt>nodes</tt> property; the main advantage of doing this is that the
+ * comparator function can access implicit fields populated by the network
+ * layout, such as the <tt>linkDegree</tt>.
+ *
+ * <p>Note that matrix visualizations are particularly sensitive to order. This
+ * is referred to as the seriation problem, and many different techniques exist
+ * to find good node orders that emphasize clusters, such as spectral layout and
+ * simulated annealing.
+ *
+ * @param {function} f comparator function for nodes.
+ * @returns {pv.Layout.Matrix} this.
+ */
+pv.Layout.Matrix.prototype.sort = function(f) {
+  this.$sort = f;
+  return this;
+};
+
+/** @private */
+pv.Layout.Matrix.prototype.buildImplied = function(s) {
+  if (pv.Layout.Network.prototype.buildImplied.call(this, s)) return;
+
+  var nodes = s.nodes,
+      links = s.links,
+      sort = this.$sort,
+      n = nodes.length,
+      index = pv.range(n),
+      labels = [],
+      pairs = [],
+      map = {};
+
+  s.$matrix = {labels: labels, pairs: pairs};
+
+  /* Sort the nodes. */
+  if (sort) index.sort(function(a, b) { return sort(nodes[a], nodes[b]); });
+
+  /* Create pairs. */
+  for (var i = 0; i < n; i++) {
+    for (var j = 0; j < n; j++) {
+      var a = index[i],
+          b = index[j],
+          p = {
+            row: i,
+            col: j,
+            sourceNode: nodes[a],
+            targetNode: nodes[b],
+            linkValue: 0
+          };
+      pairs.push(map[a + "." + b] = p);
+    }
+  }
+
+  /* Create labels. */
+  for (var i = 0; i < n; i++) {
+    var a = index[i];
+    labels.push(nodes[a], nodes[a]);
+  }
+
+  /* Accumulate link values. */
+  for (var i = 0; i < links.length; i++) {
+    var l = links[i],
+        source = l.sourceNode.index,
+        target = l.targetNode.index,
+        value = l.linkValue;
+    map[source + "." + target].linkValue += value;
+    if (!s.directed) map[target + "." + source].linkValue += value;
+  }
+};

data/vendor/src/layout/Network.js

@@ -0,0 +1,302 @@
+/**
+ * Constructs a new, empty network layout. Layouts are not typically constructed
+ * directly; instead, they are added to an existing panel via
+ * {@link pv.Mark#add}.
+ *
+ * @class Represents an abstract layout for network diagrams. This class
+ * provides the basic structure for both node-link diagrams (such as
+ * force-directed graph layout) and space-filling network diagrams (such as
+ * sunbursts and treemaps). Note that "network" here is a general term that
+ * includes hierarchical structures; a tree is represented using links from
+ * child to parent.
+ *
+ * <p>Network layouts require the graph data structure to be defined using two
+ * properties:<ul>
+ *
+ * <li><tt>nodes</tt> - an array of objects representing nodes. Objects in this
+ * array must conform to the {@link pv.Layout.Network.Node} interface; which is
+ * to say, be careful to avoid naming collisions with automatic attributes such
+ * as <tt>index</tt> and <tt>linkDegree</tt>. If the nodes property is defined
+ * as an array of primitives, such as numbers or strings, these primitives are
+ * automatically wrapped in an object; the resulting object's <tt>nodeValue</tt>
+ * attribute points to the original primitive value.
+ *
+ * <p><li><tt>links</tt> - an array of objects representing links. Objects in
+ * this array must conform to the {@link pv.Layout.Network.Link} interface; at a
+ * minimum, either <tt>source</tt> and <tt>target</tt> indexes or
+ * <tt>sourceNode</tt> and <tt>targetNode</tt> references must be set. Note that
+ * if the links property is defined after the nodes property, the links can be
+ * defined in terms of <tt>this.nodes()</tt>.
+ *
+ * </ul>
+ *
+ * <p>Three standard mark prototypes are provided:<ul>
+ *
+ * <li><tt>node</tt> - for rendering nodes; typically a {@link pv.Dot}. The node
+ * mark is added directly to the layout, with the data property defined via the
+ * layout's <tt>nodes</tt> property. Properties such as <tt>strokeStyle</tt> and
+ * <tt>fillStyle</tt> can be overridden to compute properties from node data
+ * dynamically.
+ *
+ * <p><li><tt>link</tt> - for rendering links; typically a {@link pv.Line}. The
+ * link mark is added to a child panel, whose data property is defined as
+ * layout's <tt>links</tt> property. The link's data property is then a
+ * two-element array of the source node and target node. Thus, poperties such as
+ * <tt>strokeStyle</tt> and <tt>fillStyle</tt> can be overridden to compute
+ * properties from either the node data (the first argument) or the link data
+ * (the second argument; the parent panel data) dynamically.
+ *
+ * <p><li><tt>label</tt> - for rendering node labels; typically a
+ * {@link pv.Label}. The label mark is added directly to the layout, with the
+ * data property defined via the layout's <tt>nodes</tt> property. Properties
+ * such as <tt>strokeStyle</tt> and <tt>fillStyle</tt> can be overridden to
+ * compute properties from node data dynamically.
+ *
+ * </ul>Note that some network implementations may not support all three
+ * standard mark prototypes; for example, space-filling hierarchical layouts
+ * typically do not use a <tt>link</tt> prototype, as the parent-child links are
+ * implied by the structure of the space-filling <tt>node</tt> marks.  Check the
+ * specific network layout for implementation details.
+ *
+ * <p>Network layout properties, including <tt>nodes</tt> and <tt>links</tt>,
+ * are typically cached rather than re-evaluated with every call to render. This
+ * is a performance optimization, as network layout algorithms can be
+ * expensive. If the network structure changes, call {@link #reset} to clear the
+ * cache before rendering. Note that although the network layout properties are
+ * cached, child mark properties, such as the marks used to render the nodes and
+ * links, <i>are not</i>. Therefore, non-structural changes to the network
+ * layout, such as changing the color of a mark on mouseover, do not need to
+ * reset the layout.
+ *
+ * @see pv.Layout.Hierarchy
+ * @see pv.Layout.Force
+ * @see pv.Layout.Matrix
+ * @see pv.Layout.Arc
+ * @see pv.Layout.Rollup
+ * @extends pv.Layout
+ */
+pv.Layout.Network = function() {
+  pv.Layout.call(this);
+  var that = this;
+
+  /* @private Version tracking to cache layout state, improving performance. */
+  this.$id = pv.id();
+
+  /**
+   * The node prototype. This prototype is intended to be used with a Dot mark
+   * in conjunction with the link prototype.
+   *
+   * @type pv.Mark
+   * @name pv.Layout.Network.prototype.node
+   */
+  (this.node = new pv.Mark()
+      .data(function() { return that.nodes(); })
+      .strokeStyle("#1f77b4")
+      .fillStyle("#fff")
+      .left(function(n) { return n.x; })
+      .top(function(n) { return n.y; })).parent = this;
+
+  /**
+   * The link prototype, which renders edges between source nodes and target
+   * nodes. This prototype is intended to be used with a Line mark in
+   * conjunction with the node prototype.
+   *
+   * @type pv.Mark
+   * @name pv.Layout.Network.prototype.link
+   */
+  this.link = new pv.Mark()
+      .extend(this.node)
+      .data(function(p) { return [p.sourceNode, p.targetNode]; })
+      .fillStyle(null)
+      .lineWidth(function(d, p) { return p.linkValue * 1.5; })
+      .strokeStyle("rgba(0,0,0,.2)");
+
+  this.link.add = function(type) {
+    return that.add(pv.Panel)
+        .data(function() { return that.links(); })
+      .add(type)
+        .extend(this);
+  };
+
+  /**
+   * The node label prototype, which renders the node name adjacent to the node.
+   * This prototype is provided as an alternative to using the anchor on the
+   * node mark; it is primarily intended to be used with radial node-link
+   * layouts, since it provides a convenient mechanism to set the text angle.
+   *
+   * @type pv.Mark
+   * @name pv.Layout.Network.prototype.label
+   */
+  (this.label = new pv.Mark()
+      .extend(this.node)
+      .textMargin(7)
+      .textBaseline("middle")
+      .text(function(n) { return n.nodeName || n.nodeValue; })
+      .textAngle(function(n) {
+          var a = n.midAngle;
+          return pv.Wedge.upright(a) ? a : (a + Math.PI);
+        })
+      .textAlign(function(n) {
+          return pv.Wedge.upright(n.midAngle) ? "left" : "right";
+        })).parent = this;
+};
+
+/**
+ * @class Represents a node in a network layout. There is no explicit
+ * constructor; this class merely serves to document the attributes that are
+ * used on nodes in network layouts. (Note that hierarchical nodes place
+ * additional requirements on node representation, vis {@link pv.Dom.Node}.)
+ *
+ * @see pv.Layout.Network
+ * @name pv.Layout.Network.Node
+ */
+
+/**
+ * The node index, zero-based. This attribute is populated automatically based
+ * on the index in the array returned by the <tt>nodes</tt> property.
+ *
+ * @type number
+ * @name pv.Layout.Network.Node.prototype.index
+ */
+
+/**
+ * The link degree; the sum of link values for all incoming and outgoing links.
+ * This attribute is populated automatically.
+ *
+ * @type number
+ * @name pv.Layout.Network.Node.prototype.linkDegree
+ */
+
+/**
+ * The node name; optional. If present, this attribute will be used to provide
+ * the text for node labels. If not present, the label text will fallback to the
+ * <tt>nodeValue</tt> attribute.
+ *
+ * @type string
+ * @name pv.Layout.Network.Node.prototype.nodeName
+ */
+
+/**
+ * The node value; optional. If present, and no <tt>nodeName</tt> attribute is
+ * present, the node value will be used as the label text. This attribute is
+ * also automatically populated if the nodes are specified as an array of
+ * primitives, such as strings or numbers.
+ *
+ * @type object
+ * @name pv.Layout.Network.Node.prototype.nodeValue
+ */
+
+/**
+ * @class Represents a link in a network layout. There is no explicit
+ * constructor; this class merely serves to document the attributes that are
+ * used on links in network layouts. For hierarchical layouts, this class is
+ * used to represent the parent-child links.
+ *
+ * @see pv.Layout.Network
+ * @name pv.Layout.Network.Link
+ */
+
+/**
+ * The link value, or weight; optional. If not specified (or not a number), the
+ * default value of 1 is used.
+ *
+ * @type number
+ * @name pv.Layout.Network.Link.prototype.linkValue
+ */
+
+/**
+ * The link's source node. If not set, this value will be derived from the
+ * <tt>source</tt> attribute index.
+ *
+ * @type pv.Layout.Network.Node
+ * @name pv.Layout.Network.Link.prototype.sourceNode
+ */
+
+/**
+ * The link's target node. If not set, this value will be derived from the
+ * <tt>target</tt> attribute index.
+ *
+ * @type pv.Layout.Network.Node
+ * @name pv.Layout.Network.Link.prototype.targetNode
+ */
+
+/**
+ * Alias for <tt>sourceNode</tt>, as expressed by the index of the source node.
+ * This attribute is not populated automatically, but may be used as a more
+ * convenient identification of the link's source, for example in a static JSON
+ * representation.
+ *
+ * @type number
+ * @name pv.Layout.Network.Link.prototype.source
+ */
+
+/**
+ * Alias for <tt>targetNode</tt>, as expressed by the index of the target node.
+ * This attribute is not populated automatically, but may be used as a more
+ * convenient identification of the link's target, for example in a static JSON
+ * representation.
+ *
+ * @type number
+ * @name pv.Layout.Network.Link.prototype.target
+ */
+
+/**
+ * Alias for <tt>linkValue</tt>. This attribute is not populated automatically,
+ * but may be used instead of the <tt>linkValue</tt> attribute when specifying
+ * links.
+ *
+ * @type number
+ * @name pv.Layout.Network.Link.prototype.value
+ */
+
+/** @private Transform nodes and links on cast. */
+pv.Layout.Network.prototype = pv.extend(pv.Layout)
+    .property("nodes", function(v) {
+        return v.map(function(d, i) {
+            if (typeof d != "object") d = {nodeValue: d};
+            d.index = i;
+            return d;
+          });
+      })
+    .property("links", function(v) {
+        return v.map(function(d) {
+            if (isNaN(d.linkValue)) d.linkValue = isNaN(d.value) ? 1 : d.value;
+            return d;
+          });
+      });
+
+/**
+ * Resets the cache, such that changes to layout property definitions will be
+ * visible on subsequent render. Unlike normal marks (and normal layouts),
+ * properties associated with network layouts are not automatically re-evaluated
+ * on render; the properties are cached, and any expensive layout algorithms are
+ * only run after the layout is explicitly reset.
+ *
+ * @returns {pv.Layout.Network} this.
+ */
+pv.Layout.Network.prototype.reset = function() {
+  this.$id = pv.id();
+  return this;
+};
+
+/** @private Skip evaluating properties if cached. */
+pv.Layout.Network.prototype.buildProperties = function(s, properties) {
+  if ((s.$id || 0) < this.$id) {
+    pv.Layout.prototype.buildProperties.call(this, s, properties);
+  }
+};
+
+/** @private Compute link degrees; map source and target indexes to nodes. */
+pv.Layout.Network.prototype.buildImplied = function(s) {
+  pv.Layout.prototype.buildImplied.call(this, s);
+  if (s.$id >= this.$id) return true;
+  s.$id = this.$id;
+  s.nodes.forEach(function(d) {
+      d.linkDegree = 0;
+    });
+  s.links.forEach(function(d) {
+      var v = d.linkValue;
+      (d.sourceNode || (d.sourceNode = s.nodes[d.source])).linkDegree += v;
+      (d.targetNode || (d.targetNode = s.nodes[d.target])).linkDegree += v;
+    });
+};