-
Notifications
You must be signed in to change notification settings - Fork 42
Guides
Wiki ▸ API Reference ▸ Chart ▸ Guides
Guides contain information about how a data column is mapped to an aesthetic, and how that mapping is displayed. There are two types of guides: axes and legends. Axes show how the data are mapped to the x- and y-position by providing labeled ticks. Legends show how other aesthetics mappings by providing example data values along with the value of the visual feature it is mapped to.
Each guide specification object o pertains to a single aesthetic, so we have exactly one set of specifications for the x-position, y-position, color, etc. This means that Polychart.js can create exactly one x-axis, one y-axis, one color legend, etc.. This is true even if multiple layers are present. (E.g. the color aesthetic of all layers share the same guide)
Technical Note: Like other systems that are motivated by the Grammar of Graphics, Polychart.js uses the concept of scales and guides. A scale is a function that takes values from some data space to some visible value of the resulting geometrical object on the screen. For example, if an x-position aesthetic of a chart is mapped to some numeric data column with values between 5 and 10, there will be a scale internal to Polychart.js that takes values from that data column ([5, 10]) and outputs the correct pixel position represented by those values. Depending on the type of scale used (e.g. linear, logarithmic), each pixel position on the screen will denote a different value in the data domain. A guide is a visual display that shows how the mapping occurred, and helps differentiate between the type of scale used. For simplicity, guide specification listed here is used to specify both scales and guides.
The guide specification object o have a number of attributes falling into these categories:
- guide title
o.title - domain
o.* - scale
o.scale - ticks
o.* - axis position
o.position - axis visibility
*.render* - paddings
o.padding
| Type | String |
| Required | No (Optional) |
| Default | The name of the data column or series mapped to the aesthetic in question. (If multiple exists, the one in the first layer is taken.) |
This is the title of the axis or legend.
Recall that a scale is a function that takes values occuring in a data column or series and outputs values that specify visible characteristics. The domain that we refer to in this section is the domain of this scale function.
As an example, if a data series "dice_roll" contains values in the range [1,6], and we wish map the values of this series onto the x-axis. If there are 100 pixels alloted to rendering the chart, our scale function would presumably map the domain [1,6] to the range [0, 99]. This way, a linear scale would take the value 1 to pixel 0, and the value 6 to pixel 99, and so on. However, we could also force the domain to be [2,4], so that the value 2 is mapped to pixel 0, and 4 to pixel 99, and values outside of the range no longer appears in the chart. Likewise, we could define the domain to be [0,10], so that 0 is mapped to pixel 0 and 10 is mapped to pixel 99.
One can re-define domains of date and categorical values in a similar manner.
| Type | Numeric or Date |
| Required | No (Optional) |
| Default | Minimum of the data series mapped to the aesthetic |
This is used to determine the minimum value of the domain. It is used for numeric or datetime data series.
| Type | Numeric or Date |
| Required | No (Optional) |
| Default | Maximum of the data series mapped to the aesthetic |
This is used to determine the maximum value of the domain. It is used for numeric or datetime data series.
| Type | Numeric or Date |
| Required | No (Optional) |
| Default | Derived from the data |
This parameter is used to defined the binning value for pre-binned data columns/series, for aesthetics that require a discrete value. Typically these aesthetics will require a bin() transformation to be preformed, but setting this parameters circumvents that requirement. For example, if you have intergral values mapped to the x-axis of a bar chart (which requires the x-mapping to be discrete), we can set the bw here to 1. This becomes the width of each bin. (See Aesthetics for more details.)
| Type | Array of values (categorical) |
| Required | No (Optional) |
| Default | Derived from the data |
For categorical values, this parameter is an array of values allowed on the axis or legend. Any value that is not in this parameter is not displayed. This parameter is only useful for aesthetics mapped to categorical values.
| Type | Bool |
| Required | No (Optional) |
| Default | False |
When set to true, Polychart.js will not resort the values defined in o.levels and keep the original ordering. This parameter is only useful for aesthetics mapped to categorical values.
| Type | Scale Object OR function |
| Required | No (Optional) |
| Default | Depends on Aesthetics |
Scales define how data is mapped to a particular aesthetics (position, color, etc). A default scale type is automatically imputed, but can be overwritten using this parameter. The value of the scale parameter should be an object describing one of the following available scale types. Each scale type works with one or more data types and aesthetics.
This is a scale for the x or y aesthetic, and can be used for data columns of any type (numeric, datetime or categorical). For continuous types, this scale maps linearly to pixel positions. For categorical values, it spaces each category evenly across the allotted space. To use this scale, set
guides = {
x: { scale: {type: 'linear'}},
y: { scale: {type: 'linear'}}
}
This is a scale for the x or y aesthetic, and can take data columns of numeric type, where all values are strictly greater than 0. It produces a logarithmic scale. To use this scale, set
guides = {
y: { scale: {type: 'log'}}
}
This is a scale for the size aesthetic, and can take data columns of FILLTHISIN types. Because size is usually represented as a radius or diameter in Polychart, the area scale applies a squareroot transform on numeric data values. This way, a 2x increase in the data produces a 2x increase in area (as opposed to 2x increase in diameter, implying a 4x increase in area). To use this scale, set
guides = {
size: {scale: {type: 'area'}}
}
This is a scale for the color aesthetic for data column of categorical type. It assigns a unique colour to every unique cateogry value. If less than 10 categories are present, then a color brewer palette is used. Otherwise, colors are generated from the HSL space, with hues evenly distributed and saturation and lightness set to 0.5. To use this scale, set
guides = {
color: {scale: {type: 'palette'}}
}
This is a scale for the color aesthetic for data column of numeric or datetime type. It produces a smooth gradient: a straight line between two colors in the RGB space. The colour values can be set using the lower and upper attributes, like this:
guides = {
color: {
scale: {
type: 'gradient',
lower: '#FFF',
upper: 'steelblue'
}
}
}
Note that both HEX colours and colour names are acceptable.
This is a scale for the color aesthetic for data column of numeric or datetime type, and produces a diverging gradient scale, or a gradient along three points in the color space. For example, this can be used to differentiate positive and negative values, with a colour representing the neutral value zero. Colour values can be set using the lower, middle and upper attributes, and the midpoint (of the data) can be set using the midpoint attribute (and defaults to 0), for example:
guides = {
color: {
scale: {
type: 'gradient2',
lower: 'red',
middle: '#FFFFFF',
upper: 'steelblue'
midpoint: 0
}
}
}
This is a scale for the opacity aesthetic for data column of all types. It works exactly the same way a linear scale would, except the output is always a numeric value between 0 and 1. To use this scale set
guides = {
opacity: {scale: {type: 'opacity'}}
}
If a data column already describes a visual feature, we can use it directly using the identity scale. For example, if a data column contains HEX colors, then we can use an identity scale to use those colors. This scale is used by the text aesthetic by default, and can also be used for all other aesthetics except the position aesthetics (x and y). To use this scale set
guides = {
aes: {scale: {type: 'identity'}}
}
For greater control of how data is mapped to visual features, one can define a custom scale function that takes a data point and outputs an appropriate value. This applies to all data types and all non-position aesthetics (x and y). In this case, the scale parameter should be this custom scale function.
guides = {
aes: {
scale: function(datavalue) {
var aestheticvalue;
// calculation
return aestheticvalue;
}
}
}
Ticks describe the small line and labels on axes, and the geometric object and label on legends. Ticks are generated automatically for all aesthetics, but default behaviour can be overwritten.
| Type | Int |
| Required | No (Optional) |
| Default | 5 |
This parameter represents a suggested number of ticks that Polychart.js should render. This is a suggestion only, and in many cases a number of ticks close to this value is chosen so "prettier" tick values can be used (e.g. for numeric values, multiples of 2, 5, 10, etc.).
This should no be used when o.ticks are defined.
| Type | Array of Data Values |
| Required | No (Optional) |
| Default | N/A |
Alternative to providing numticks, one can provide the array of data values at which ticks should appear. This is useful if one wishes to draw ticks at an irregular interval.
This should not be used if o.numticks is defined.
| Type | Associate Array of Data Values to Labels |
| Required | No (Optional) |
| Default | N/A |
If the tick text are not displayed in the desired fashion, one can override the default behaviour. One can provide a o.labels parameters, which should be a key-value pair where the keys are data values, and the values are string labels for the data value.
| Type | Function |
| Required | No (Optional) |
| Default | N/A |
If the tick text are not displayed in the desired fashion, one can override the default behaviour. One can provide a formatter, which should be a function that takes a data value, and returns a string label for that value. Alternatively,
| Type | String |
| Required | No (Optional) |
| Default | 'left' for y-axis; 'bottom' for x-axis |
The position of the axis. For the x aesthetic this can be top, bottom or none. For the y aesthetic this can be left, right or none.
For axes, there are options to control rendering of each axis element, including the ticks, labels, grid, and lines.
| Type | Bool |
| Required | No (Optional) |
| Default | True |
Whether or not to render the axis line.
| Type | Bool |
| Required | No (Optional) |
| Default | True for y-axis; False for x-axis |
Whether or not to render the grid lines that extends into the body of the chart.
| Type | Bool |
| Required | No (Optional) |
| Default | True |
Whether or not to render the tick lines that extends from the axis.
| Type | Bool |
| Required | No (Optional) |
| Default | True |
Whether or not to render the label text that denotes the value represented at a particular point on the axis.
| Type | String (HEX or colour name) |
| Required | No (Optional) |
| Default | gray |
Colour of the grid lines
| Type | Number between 0 and 0.5 |
| Required | No (Optional) |
| Default | 0.05 |
Layers that requires discrete values tend to have a bit of padding beside adjacent elements. For example, bar charts have some space between adjacent bars. The padding parameter determines how big that space is, and should have a value between 0 and 0.5. The value is the proportion of the full horizontal width to devote to padding.