Skip to content

Layer

Jump to bottom Edit New page
zach edited this page Feb 20, 2013 · 27 revisions

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

Data spec.layer.data

This is the Polychart.js data object that is used to created the charts. See the data section of the API reference for more details. Note that different layers can have different data objects attached to it.

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

Statistic calculation produces one aggregated vale per group. Groups are imputed automatically based on the aesthetic mappings applied. Specifically, data points are grouped based on the values of its non-aggregated mappings. For example, both of the following sets of mappings

x: 'bin(date, week)',
y: 'sum(num_events)',
color: 'event_type'

and

x: 'bin(date, week)',
y: 'event_type',
color: 'sum(num_events)'

will have the summation statistics calculated for each unique values of bin(date, week) and event_type. As another example, in the below mappings

x: 'event_type',
y: 'sum(num_events)',
color: 'mean(num_events)',
size: 'sum(event_duration)'

will have all three aggregations sum(num_events), mean(num_events) and sum(event_duration) performed for each unique value of event_type.

Restrictions on Aesthetics

Not all sets of aesthetic mappings will make sense for every layer type. Some mappings cannot be rendered by Polychart.js at all, and we describe these restrictions in this section.

Box plot requires statistics

The box plot assumes that the box statistics is calculated for the y-mapping. Thus, the y-mapping for a box layer should be in the form box(*). The box statistics calculates the quantiles and outliers for each grouping. If you would like to specify the quantiles and outliers directly, you can use the following format

FILL IN HERE

Binning for bar, box and tile plots

Bar charts and box plots require discrete y-mappings, and tile plots require discrete x- and y-mappings. Thus, if a continuous variable (date or number) is mapped to the y-position of a bar or box plot or the x- or y-position of a tile plot, it should be binned. That is, the mappings should be of the form x: bin(*, *).

If you have pre-binned values or discrete numeric values (e.g. integers), you should either bin the values as if it is continuous, or provide the appropriate binwidth when setting the guides. (See the binwidth section of the guides page

Position spec.layer.position

The position setting is used to determine how to offset two geometrical elements that appear in the same location. It specifically applies to bar charts, and will apply to scatter plots in the future.

Bar chart position setting

The bar layer type offers two ways of displaying two bars with the same x-position. The default method is to stack the bars together, producing a stacked bar chart. An alternate method is to have the bars dodge one another, so that each bar is a fraction of its original width and appear side by side.

Filteringspec.layer.filter

A filtering object can be defined if not all rows in the data set are to be plotted. The filtering syntax is defined SOMEHWERE ELSE.

Add a custom footer
Add a custom sidebar
Clone this wiki locally