Layer

Wiki ▸ API Reference ▸ Specification ▸ Layer

A layer describes the type of plot you will produce. One or more layers can be added to the chart to produce multi-layered graphic (for example, a scatter plot with a trend line).

A layer is represented in the graph specification as a JSON object with a number of attributes. These attributes fall into the following categories.

Layer Type spec.layer.type

The type of the layer describes the geometrical objects that will represent your data. Supported types include:

• point - circles or scatter plots
• line - line charts
• bar - bar charts
• area - area charts
• path - paths
• box - box and whisker plots
• text - text plots
• tile - tile plots

Aesthetic Mappings spec.layer.*

Aesthetics describe retinal properties or properties of an object on the screen that we can see. Color, size, shape, x- and y-position are all examples of aesthetics. In Polychart, not only can one set an aesthetic to be a constant, but also one can map a data column to an aesthetic. For example, to set the aesthetic color to red we write: spec.layer.color = {'const': 'red'}. To map the aesthetic size to a data column called population we write spec.layer.size = {'var': 'population'} or more succinctly spec.layer.size = 'population'.

List of aesthetics

More generally, here is a list of all the aesthetics available. Not all layers will support all of the aesthetics.

• x - The x-position. Supported by all layer types.
• y - The y-position. Supported by all layer types.
• color - The color of each geometrical object. Supported by all layer types.
• opacity - The opacity of the colouring. Supported by all layer types.
• size - The size of each geometrical object. Support by layer type point, line, path and text.
• text - Text text to be displayed. Unique to text layer type.
• tooltip - The tooltip text to display. Tooltips are supported for point, bar and tile layer types.
• id - Not really an aesthetic but is treated as one. Described below.

The "id" aesthetic

The "id" aesthetic gives an identity to each geometrical object on the screen. For example, each bar, each set of box-and-whiskers, and each point will have a unique identifier associated with it. This identifier is used for animation purposes when the underlying dataset changes: it allows Polychart.js to understand which elements are added, removed, and modified. Two elements with the same identifier will be considered identical, and so Polychart.js will consider there to be a modification to the data.

Setting aesthetics to a constant

To set any aesthetics to a constant value for all geometrical objects in a chart, set

spec.layer[aes] = {const: value}

Note that a constant value should not be set for the x- and y-positions unless you really know what you're doing. The x- and y- positions are pixel values!

Aesthetics with Numeric Constant Values

The aesthetics x, y, opacity and size are numeric.

Aesthetics with String Constant Values

The aesthetic color should be a string with a valid hexadecimal code, or the name of a colour.

The aesthetics text and tooltip should be strings.

The aesthetic id is used as an attribute name, and is therefore converted to a string.

Mapping aesthetics

A data column can be mapped to an aesthetics. To do this, one set

spec.layer[aes] = mappingSpec

Where mappingSpec is an object with the following attributes

• mappingSpec.var - The name of data column (or a valid transform or statistics derived from a data column, as described in the next section)
• mappingSpec.sort - The name of a different data column (or a valid transform or statistics derived from a data column, as described in the next section) to sort the unique values of var by.
• mappingSpec.asc - Whether the sort should be ascending or descending.

Data Transforms and Statistics

Instead of associating a data column to an aesthetic, one can associate some transform or statistics on a particular column to that aesthetic. For example, instead of plotting revenue per month for each of many different regions and having multiple points per month, one can plot sum(revenue) instead.

Transforms and statistics differ in that transforms always takes one data point and returns one data point, whereas statistics performs aggregation over data points in some grouping. Transforms can be thought of as mathematical operations, where as statistics are aggregate measures.

Transforms

These are functions that takes one data value and returns one data value. Supported transforms include

• bin(var, binwidth) - Where var is a numeric or date data column type and binwidth is an appropriate number or date range. This transform bins continuous data into discrete intervals, and assigns a particular value to the minimum point of the interval it falls into. The variable binwidth describes the width of each interval. For example bin(date, month), bin('date', 'month'), bin(value, 10), and bin('value', 10) all works.
• lag(var, period) - Where var is a data column name and period is an integer. This transform produces a lagged version of a particular data column. For example lag(value, 2) and lag('value', 2) both produces a column that is lagged by 1.

Statistics

Statistics takes an entire column of data and aggregates it into one value per group (grouping is described in the next section). Supported statistics include

• sum(var) - The sum of a numeric variable over some grouping.
• count(var) - The total number of defined, non-null values over some grouping.
• unique(var) - The total number of unique defined, non-null values over some grouping.
• mean(var) - The mean of a numeric variabel over some grouping.
• median(var) - The median of a numeric variabel over some grouping.
• box(var) - Calculate the quantiles and outliers required for box plot.

Statistics Grouping

Restrictions on Aesthetics

Position Offsets spec.layer.position

The bar layer type offers two ways of changing

Filteringspec.layer.filter

Blah blah blah.