Error Bar

Edit this page
// Single View Specification
{
  "data": ... ,
  "mark": "errorbar",
  "encoding": ... ,
  ...
}

An error bar summarizes an error range of quantitative values using a set of summary statistics, representing by rules (and optional end ticks). Error bars in Vega-Lite can either be used to aggregate raw data or directly visualize aggregated data.

To create an error bar, set mark to "errorbar".

Documentation Overview

Error Bar Mark Properties

An error bar’s mark definition contain the following properties:

Property Type Description
type String

Required. The mark type. This could a primitive mark type (one of "bar", "circle", "square", "tick", "line", "area", "point", "geoshape", "rule", and "text") or a composite mark type ("boxplot", "errorband", "errorbar").

extent String

The extent of the rule. Available options include:

  • "ci": Extend the rule to the confidence interval of the mean.
  • "stderr": The size of rule are set to the value of standard error, extending from the mean.
  • "stdev": The size of rule are set to the value of standard deviation, extending from the mean.
  • "iqr": Extend the rule to the q1 and q3.

Default value: "stderr".

orient String

Orientation of the error bar. This is normally automatically determined, but can be specified when the orientation is ambiguous and cannot be automatically determined.

color String

Default color. Note that fill and stroke have higher precedence than color and will override color.

Default value: "#4682b4"

Note: This property cannot be used in a style config.

opacity Number

The opacity (value between [0,1]) of the mark.

Besides the properties listed above, rule and ticks can be used to specify the underlying mark properties for different parts of the error bar as well.

Using Error Bars to Aggregate Raw Data

If the data is not aggregated yet, Vega-Lite will aggregate the data based on the extent properties in the mark definition.

1) Error bars showing standard error is the default error bar in Vega-Lite. It can also be explicitly specified by setting extent to "stderr". The length of lower and upper rules represent standard error. By default, the rule marks expand from the mean.

2) Error bar showing standard deviation can be specified by setting extent to "stdev". For this type of error bar, the length of lower and upper rules represent standard deviation. Like an error bar that shows Standard Error, the rule marks expand from the mean by default.

3) Error bars showing confidence interval can be specified by setting extent to "ci". For this type of error bar, the rule marks expand from the "ci0" value to "ci1" value, as defined in aggregate.

4) Error bars showing interquartile range can be specified by setting extent to "iqr". For this type of error bar, the rule marks expand from the first quartile to the third quartile.

Using Error Bars to Visualize Aggregated Data

1) Data is aggregated with low and high values of the error bars

If the data is already pre-aggregated with low and high values of the error bars, you can directly specify x and x2 (or y and y2) to use error bar as a ranged mark.

2) Data is aggregated with center and error value(s)

If the data is already pre-aggregated with center and error values of the error bars, you can directly specity x as center, xError and xError2 as error values extended from center (or y, yError, and yError2). If x/yError2 is omitted, error bars have symmetric error values.

Error bar with symmetric error values:

Error bar with asymmetric error values:

Note in this case, extent is not necessary and will be ignored.

Dimension & Orientation

Vega-Lite supports both 1D and 2D error bars:

A 1D error bar shows the error range of a continuous field.

The orientation of an error bar is automatically determined by the continuous field axis. For example, you can create a vertical 1D error bar by encoding a continuous field on the y axis.

A 2D error bar shows the error range of a continuous field, broken down by categories.

For 2D error bars with one continuous field and one discrete field, the error bars will be horizontal if the continuous field is on the x axis.

Alternatively, if the continuous field is on the y axis, the error bar will be vertical.

The Parts of Error Bars

Under the hood, the errorbar mark is a composite mark that expands into a layered plot. For example, a basic 1D error bar shown above is expanded to:

We can customize different parts of the error bar mark definition or config.

For example, we can add the error bar’s end ticks and customize it by setting ticks to true or adding a mark property to ticks, such as setting color to "blue":

Color, and Opacity Encoding Channels

You can customize the color, size, and opacity of the bar in the errorbar by using the color, and opacity encoding channels, which applied to the whole errorbar.

Here is an example of a errorbar with the color encoding channel set to {"value": "#4682b4"}.

Mark Config

{
  "errorbar": {
    "extent": ...,
    "rule": ...,
    "ticks": ...
  }
}

The errorbar config object sets the default properties for errorbar marks.

The error bar config can contain all error bar mark properties but currently does not support color, opacity, and orient. Please see issue #3934 for details.