Channels

Altair provides a number of encoding channels that can be useful in different circumstances. The following sections summarize them:

Position

Channel	Altair Class	Description	Example
x	X	The x-axis value	Simple Scatter Plot with Tooltips
y	Y	The y-axis value	Simple Scatter Plot with Tooltips
x2	X2	Second x value for ranges	Gantt Chart
y2	Y2	Second y value for ranges	Candlestick Chart
longitude	Longitude	Longitude for geo charts	Point map
latitude	Latitude	Latitude for geo charts	Point map
longitude2	Longitude2	Second longitude value for ranges	Connections Among U.S. Airports Interactive
latitude2	Latitude2	Second latitude value for ranges	Connections Among U.S. Airports Interactive
xError	XError	The x-axis error value	N/A
yError	YError	The y-axis error value	N/A
xError2	XError2	The second x-axis error value	N/A
yError2	YError2	The second y-axis error value	N/A
xOffset	XOffset	Offset to the x position	Grouped Bar Chart with xOffset
yOffset	YOffset	Offset to the y position	Strip Plot with Jitter
theta	Theta	The start arc angle	Radial Chart
theta2	Theta2	The end arc angle (radian)	Pacman Chart

Mark Property

Channel	Altair Class	Description	Example
angle	Angle	The angle of the mark	Wind Vector Map
color	Color	The color of the mark	Simple Heatmap
fill	Fill	The fill for the mark	Ridgeline plot
fillOpacity	FillOpacity	The opacity of the mark’s fill	N/A
opacity	Opacity	The opacity of the mark	Horizon Graph
radius	Radius	The radius or the mark	Radial Chart
shape	Shape	The shape of the mark	US Income by State: Wrapped Facet
size	Size	The size of the mark	Table Bubble Plot (Github Punch Card)
stroke	Stroke	The stroke of the mark	N/A
strokeDash	StrokeDash	The stroke dash style	Multiple Series Line Chart
strokeOpacity	StrokeOpacity	The opacity of the line	N/A
strokeWidth	StrokeWidth	The width of the line	N/A

Text and Tooltip

Channel	Altair Class	Description	Example
text	Text	Text to use for the mark	Simple Scatter Plot with Labels
tooltip	Tooltip	The tooltip value	Simple Scatter Plot with Tooltips

Hyperlink

Channel	Altair Class	Description	Example
href	Href	Hyperlink for points	Scatter Plot with Href

Detail

Grouping data is an important operation in data visualization. For line and area marks, mapping an unaggregated data field to any non-position channel will group the lines and stacked areas by that field. For aggregated plots, all unaggregated fields encoded are used as grouping fields in the aggregation (similar to fields in GROUP BY in SQL).

The detail channel specifies an additional grouping field (or fields) for grouping data without mapping the field(s) to any visual properties.

Channel	Altair Class	Description	Example
detail	Detail	Additional property to group by	Ranged Dot Plot

For example here is a line chart showing stock prices of 5 tech companies over time. We map the symbol variable to detail to use them to group lines.

import altair as alt
from vega_datasets import data

source = data.stocks()
alt.Chart(source).mark_line().encode(
    x="date:T",
    y="price:Q",
    detail="symbol:N"
)

Order

The order option and Order channel can sort how marks are drawn on the chart.

For stacked marks, this controls the order of components of the stack. Here, the elements of each bar are sorted alphabetically by the name of the nominal data in the color channel.

import altair as alt
from vega_datasets import data

barley = data.barley()

alt.Chart(barley).mark_bar().encode(
    x='variety:N',
    y='sum(yield):Q',
    color='site:N',
    order=alt.Order("site").sort("ascending")
)

The order can be reversed by changing the sort option to descending.

import altair as alt
from vega_datasets import data

barley = data.barley()

alt.Chart(barley).mark_bar().encode(
    x='variety:N',
    y='sum(yield):Q',
    color='site:N',
    order=alt.Order("site").sort("descending")
)

The same approach works for other mark types, like stacked areas charts.

import altair as alt
from vega_datasets import data

barley = data.barley()

alt.Chart(barley).mark_area().encode(
    x='variety:N',
    y='sum(yield):Q',
    color='site:N',
    order=alt.Order("site").sort("ascending")
)

Note that unlike the sort parameter to positional encoding channels, the Order channel cannot take a list of values to sort by and is not automatically sorted when an ordered pandas categorical column is passed. If we want to sort stacked segments in a custom order, we can follow the approach in this issue comment, although there might be edge cases where this is not fully supported. This workaround also makes the order of the segments align with the order that the colors shows up in a legend that uses custom sorting for the color domain.

For line marks, the Order channel encodes the order in which data points are connected. This can be useful for creating a scatter plot that draws lines between the dots using a different field than the x and y axes.

import altair as alt
from vega_datasets import data

driving = data.driving()

alt.Chart(driving).mark_line(point=True).encode(
    alt.X('miles').scale(zero=False),
    alt.Y('gas').scale(zero=False),
    order='year'
)

Facet

For more information, see Faceted Charts.

Channel	Altair Class	Description	Example
column	Column	The column of a faceted plot	Faceted Scatter Plot
row	Row	The row of a faceted plot	Becker’s Barley Faceted Plot
facet	Facet	The row and/or column of a general faceted plot	US Population: Wrapped Facet