Class Index | File Index

Classes


Class pv.Layout.Stack


Extends pv.Layout.
Implements a layout for stacked visualizations, ranging from simple stacked bar charts to more elaborate "streamgraphs" composed of stacked areas. Stack layouts uses length as a visual encoding, as opposed to position, as the layers do not share an aligned axis.

Marks can be stacked vertically or horizontally. For example,

vis.add(pv.Layout.Stack)
    .layers([[1, 1.2, 1.7, 1.5, 1.7],
             [.5, 1, .8, 1.1, 1.3],
             [.2, .5, .8, .9, 1]])
    .x(function() this.index * 35)
    .y(function(d) d * 40)
  .layer.add(pv.Area);
specifies a vertically-stacked area chart, using the default "bottom-left" orientation with "zero" offset. This visualization can be easily changed into a streamgraph using the "wiggle" offset, which attempts to minimize change in slope weighted by layer thickness. See the #offset property for more supported streamgraph algorithms.

In the simplest case, the layer data can be specified as a two-dimensional array of numbers. The x and y psuedo-properties are used to define the thickness of each layer at the given position, respectively; in the above example of the "bottom-left" orientation, the x and y psuedo-properties are equivalent to the left and height properties that you might use if you implemented a stacked area by hand.

The advantage of using the stack layout is that the baseline, i.e., the bottom property is computed automatically using the specified offset algorithm. In addition, the order of layers can be computed using a built-in algorithm via the order property.

With the exception of the "expand" offset, the stack layout does not perform any automatic scaling of data; the values returned from x and y specify pixel sizes. To simplify scaling math, use this layout in conjunction with pv.Scale.linear or similar.

In other cases, the values psuedo-property can be used to define the data more flexibly. As with a typical panel & area, the layers property corresponds to the data in the enclosing panel, while the values psuedo-property corresponds to the data for the area within the panel. For example, given an array of data values:

var crimea = [
 { date: "4/1854", wounds: 0, other: 110, disease: 110 },
 { date: "5/1854", wounds: 0, other: 95, disease: 105 },
 { date: "6/1854", wounds: 0, other: 40, disease: 95 },
 ...
and a corresponding array of series names:
var causes = ["wounds", "other", "disease"];
Separate layers can be defined for each cause like so:
vis.add(pv.Layout.Stack)
    .layers(causes)
    .values(crimea)
    .x(function(d) x(d.date))
    .y(function(d, p) y(d[p]))
  .layer.add(pv.Area)
    ...
As with the panel & area case, the datum that is passed to the psuedo-properties x and y are the values (an element in crimea); the second argument is the layer data (a string in causes). Additional arguments specify the data of enclosing panels, if any.
Defined in: Stack.js.

Class Summary
Constructor Attributes Constructor Name and Description
 
Constructs a new, empty stack layout.
Field Summary
Field Attributes Field Name and Description
 
Default properties for stack layouts.
 
The layer prototype.
 
The layer data in row-major order.
 
The layer offset; the y-position of the bottom of the lowest layer.
 
The layer order.
 
The layer orientation.
Fields borrowed from class pv.Panel:
canvas, children, overflow, transform
Fields borrowed from class pv.Bar:
fillStyle, height, lineWidth, strokeStyle, width
Fields borrowed from class pv.Mark:
bottom, childIndex, cursor, data, events, index, left, parent, proto, reverse, right, root, scale, title, top, type, visible
Method Summary
Method Attributes Method Name and Description
 
values(f)
The values function; determines the values for a given layer.
 
x(f)
The x psuedo-property; determines the position of the value within the layer.
 
y(f)
The y psuedo-property; determines the thickness of the layer at the given value.
Methods borrowed from class pv.Panel:
add, anchor
Methods borrowed from class pv.Mark:
anchorTarget, def, event, extend, margin, mouse, render
Class Detail
pv.Layout.Stack()
Constructs a new, empty stack layout. Layouts are not typically constructed directly; instead, they are added to an existing panel via pv.Mark#add.
Field Detail
{pv.Layout.Stack} defaults
Default properties for stack layouts. The default orientation is "bottom-left", the default offset is "zero", and the default layers is [[]].

{pv.Mark} layer
The layer prototype. This prototype is intended to be used with an area, bar or panel mark (or subclass thereof). Other mark types may be possible, though note that the stack layout is not currently designed to support radial stacked visualizations using wedges.

The layer is not a direct child of the stack layout; a hidden panel is used to replicate layers.


{array[]} layers
The layer data in row-major order. The value of this property is typically a two-dimensional (i.e., nested) array, but any array can be used, provided the values psuedo-property is defined accordingly.

{string} offset
The layer offset; the y-position of the bottom of the lowest layer. The following values are supported:For details on these offset algorithms, refer to "Stacked Graphs -- Geometry & Aesthetics" by L. Byron and M. Wattenberg, IEEE TVCG November/December 2008.

{string} order
The layer order. The following values are supported:For details on the inside-out order algorithm, refer to "Stacked Graphs -- Geometry & Aesthetics" by L. Byron and M. Wattenberg, IEEE TVCG November/December 2008.

{string} orient
The layer orientation. The following values are supported:. The default value is "bottom-left", which means that the layers will be built from the bottom-up, and the values within layers will be laid out from left-to-right.

Note that with non-zero baselines, some orientations may give similar results. For example, offset("silohouette") centers the layers, resulting in a streamgraph. Thus, the orientations "bottom-left" and "top-left" will produce similar results, differing only in the layer order.

Method Detail
{pv.Layout.Stack} values(f)
The values function; determines the values for a given layer. The default value is the identity function, which assumes that the layers property is specified as a two-dimensional (i.e., nested) array.
Parameters:
{function} f
the values function.
Returns:
{pv.Layout.Stack} this.

{pv.Layout.Stack} x(f)
The x psuedo-property; determines the position of the value within the layer. This typically corresponds to the independent variable. For example, with the default "bottom-left" orientation, this function defines the "left" property.
Parameters:
{function} f
the x function.
Returns:
{pv.Layout.Stack} this.

{pv.Layout.Stack} y(f)
The y psuedo-property; determines the thickness of the layer at the given value. This typically corresponds to the dependent variable. For example, with the default "bottom-left" orientation, this function defines the "height" property.
Parameters:
{function} f
the y function.
Returns:
{pv.Layout.Stack} this.

Documentation generated by JsDoc Toolkit 2.3.2 on Sun May 30 2010 18:10:25 GMT-0700 (PDT)