Error Band
Edit this page// Single View Specification
{
"data": ... ,
"mark": "errorband",
"encoding": ... ,
...
}
An error band summarizes an error range of quantitative values using a set of summary statistics, representing by area. Error band in Vega-Lite can either be used to aggregate raw data or directly visualize aggregated data.
To create an error band, set mark
to "errorband"
.
Documentation Overview
- Error Band Mark Properties
- Comparing the usage of Error Band to the usage of Error Bar
- Using Error Band to Aggregate Raw Data
- Using Error Band to Visualize Aggregated Data
- Dimension
- The Parts of Error Band
- Color, and Opacity Encoding Channels
- Tooltip Encoding Channels
- Mark Config
Error Band Mark Properties
An error band’s mark definition can contain the following properties:
Property | Type | Description |
---|---|---|
type | ErrorBand |
Required. The mark type. This could a primitive mark type (one of |
extent | String |
The extent of the band. Available options include:
Default value: |
orient | String |
Orientation of the error band. This is normally automatically determined, but can be specified when the orientation is ambiguous and cannot be automatically determined. |
color | Color | Gradient | ExprRef |
Default color. Default value: ■ Note:
|
opacity | Number |
The opacity (value between [0,1]) of the mark. |
interpolate | String |
The line interpolation method for the error band. One of the following:
|
tension | Number |
The tension parameter for the interpolation type of the error band. |
Besides the properties listed above, band
and borders
can be used to specify the underlying mark properties for different parts of the error band as well.
Comparing the usage of Error Band to the usage of Error Bar
All the properties and usage of error band are identical to error bar’s, except the band
and borders
that replace the error bar’s rule
and ticks
.
Error Band
Error Bar
Using Error Band 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 as done in the error band showing confidence interval above. All other extent
values are defined in Error Bar.
Using Error Band to Visualize Aggregated Data
- Data is aggregated with low and high values of the error band
If the data is already pre-aggregated with low and high values of the error band, you can directly specify x
and x2
(or y
and y2
) to use error band as a ranged mark.
- Data is aggregated with center and error value(s)
If the data is already pre-aggregated with center and error values of the error band, you can use x/y
, x/yError
, and x/yError2
as defined in Error Bar
Dimension
Vega-Lite supports both 1D and 2D error bands:
{:#1d} A 1D error band shows the error range of a continuous field; it can be used to show the global error range of the whole plot.
{:#2d} A 2D error band shows the error range of a continuous field for each dimension value such as year.
The Parts of Error Band
Under the hood, the errorband
mark is a composite mark that expands into a layered plot. For example, the basic 2D error band shown above is equivalent to:
We can customize different parts of the error band mark definition or config.
For example, we can add the error band’s borders and customize it by setting borders
to true
or adding a mark property to borders
, such as strokeDash
and opacity
:
Color, and Opacity Encoding Channels
You can customize the color, size, and opacity of the band in the errorband
by using the color
, and opacity
encoding channels, which applied to the whole errorband
.
Here is an example of a errorband
with the color
encoding channel set to {"value": "black"}
.
Tooltip Encoding Channels
You can add custom tooltips to error bands. The custom tooltip will override the default error band’s tooltips.
Mark Config
{
"errorband": {
"extent": ...,
"band": ...,
"borders": ...
}
}
The errorband
config object sets the default properties for errorband
marks.
The error band config can contain all error band mark properties but currently not supporting color
, opacity
, and orient
. Please see issue #3934.