Error Band#

An error band summarizes an error range of quantitative values using a set of summary statistics, representing by area. Error band in Altair can either be used to aggregate raw data or directly visualize aggregated data.

To create an error band, use mark_errorband.

Error Band Mark Properties#

An errorband mark definition can contain the following properties:

Click to show table

Property	Type	Description
extent	`ErrorBarExtent`	The extent of the band. Available options include: `"ci"`: Extend the band to the confidence interval of the mean. `"stderr"`: The size of band are set to the value of standard error, extending from the mean. `"stdev"`: The size of band are set to the value of standard deviation, extending from the mean. `"iqr"`: Extend the band to the q1 and q3. Default value: `"stderr"`.
orient	`Orientation`	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	anyOf(`Color`, `Gradient`, `ExprRef`)	Default color. Default value: ■ `"#4682b4"` Note: This property cannot be used in a style config. The `fill` and `stroke` properties have higher precedence than `color` and will override `color`.
opacity	`number`	The opacity (value between [0,1]) of the mark.
interpolate	`Interpolate`	The line interpolation method for the error band. One of the following: `"linear"`: piecewise linear segments, as in a polyline. `"linear-closed"`: close the linear segments to form a polygon. `"step"`: a piecewise constant function (a step function) consisting of alternating horizontal and vertical lines. The y-value changes at the midpoint of each pair of adjacent x-values. `"step-before"`: a piecewise constant function (a step function) consisting of alternating horizontal and vertical lines. The y-value changes before the x-value. `"step-after"`: a piecewise constant function (a step function) consisting of alternating horizontal and vertical lines. The y-value changes after the x-value. `"basis"`: a B-spline, with control point duplication on the ends. `"basis-open"`: an open B-spline; may not intersect the start or end. `"basis-closed"`: a closed B-spline, as in a loop. `"cardinal"`: a Cardinal spline, with control point duplication on the ends. `"cardinal-open"`: an open Cardinal spline; may not intersect the start or end, but will intersect other control points. `"cardinal-closed"`: a closed Cardinal spline, as in a loop. `"bundle"`: equivalent to basis, except the tension parameter is used to straighten the spline. `"monotone"`: cubic interpolation that preserves monotonicity in y.
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

import altair as alt
from vega_datasets import data

source = data.cars.url

alt.Chart(source).mark_errorband(extent="ci", borders=True).encode(
    x="year(Year)",
    y=alt.Y(
        "Miles_per_Gallon:Q",
        scale=alt.Scale(zero=False),
        title="Miles per Gallon (95% CIs)",
    ),
)

Error Bar

import altair as alt
from vega_datasets import data

source = data.cars.url

alt.Chart(source).mark_errorbar(extent="ci", ticks=True).encode(
    x="year(Year)",
    y=alt.Y(
        "Miles_per_Gallon:Q",
        scale=alt.Scale(zero=False),
        title="Miles per Gallon (95% CIs)",
    ),
)

Using Error Band to Aggregate Raw Data#

If the data is not aggregated yet, Altair 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#

1. 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.

import altair as alt
import pandas as pd

source = pd.DataFrame(
    {
        "ci1": [23.5007, 25.8214, 26.4472, 27.7074],
        "ci0": [19.6912, 20.8554, 21.9749, 22.6203],
        "center": [21.5735, 23.3750, 24.0611, 25.0931],
        "Year": [189302400000, 220924800000, 252460800000, 283996800000],
    }
)

band = alt.Chart(source).mark_errorband().encode(
    alt.Y(
        "ci1:Q",
        scale=alt.Scale(zero=False),
        title="Mean of Miles per Gallon (95% CIs)"
    ),
    alt.Y2("ci0:Q"),
    alt.X("year(Year)"),
)

line = alt.Chart(source).mark_line().encode(
    alt.Y("center:Q"),
    alt.X("year(Year)")
)

band + line

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 band, you can use x/y, x/yError, and x/yError2 as defined in Error Bar.

Dimension#

Altair supports both 1D and 2D error bands:

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.

import altair as alt
from vega_datasets import data

source = data.cars.url

band = alt.Chart(source).mark_errorband(extent="stdev").encode(
    alt.Y("Miles_per_Gallon:Q").title("Miles per Gallon")
)

points = alt.Chart(source).mark_point().encode(
    x="Horsepower:Q",
    y="Miles_per_Gallon:Q",
)

band + points

A 2D error band shows the error range of a continuous field for each dimension value such as year.

import altair as alt
from vega_datasets import data

source = data.cars()

line = alt.Chart(source).mark_line().encode(
    x="Year",
    y="mean(Miles_per_Gallon)"
)

band = alt.Chart(source).mark_errorband(extent="ci").encode(
    x="Year",
    y=alt.Y("Miles_per_Gallon").title("Miles/Gallon"),
)

band + line

Color and Opacity Encoding Channels#

You can customize the color and opacity of the bands by using the color and opacity encoding channels.

Here is an example of a errorband with the color encoding channel set to alt.value('black').

import altair as alt
from vega_datasets import data

source = data.cars.url

alt.Chart(source).mark_errorband(extent="ci", borders=True).encode(
    x="year(Year)",
    y=alt.Y("Miles_per_Gallon:Q")
        .scale(zero=False)
        .title("Miles per Gallon (95% CIs)"),
    color=alt.value("black")
)