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
	pv.Layout.Stack() Constructs a new, empty stack layout.

Field Summary
Field Attributes	Field Name and Description
	defaults Default properties for stack layouts.
	layer The layer prototype.
	layers The layer data in row-major order.
	offset The layer offset; the y-position of the bottom of the lowest layer.
	order The layer order.
	orient 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:

zero - use a zero baseline, i.e., the y-axis.
silohouette - center the stream, i.e., ThemeRiver.
wiggle - minimize weighted change in slope.
expand - expand layers to fill the enclosing layout dimensions.

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:

null - use given layer order.
inside-out - sort by maximum value, with balanced order.
reverse - use reverse of given layer order.

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:

bottom-left == bottom
bottom-right
top-left == top
top-right
left-top
left-bottom == left
right-top
right-bottom == right

. 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.

Classes

Class pv.Layout.Stack