An encoding channel maps a data column to a visual property in a chart. In Altair, encodings say where or how values appear: position on an axis, color, size, shape, text, or a tooltip. An encoding combines a chosen column, a channel, and a data type so the chart can interpret the values correctly. section 2.1.3 section 3.2.1
Common channel roles include:
- Use x and y for horizontal and vertical position; longitude and latitude provide geographic position. section 3.2.1
- Use color, fill, size, shape, opacity, and stroke properties to distinguish or emphasize marks. section 3.2.1
- Use text and tooltip to attach visible labels or hover details to marks. section 3.2.1 section 8.4.1
Specify the field type with every encoded column. Altair supports nominal values for unordered categories, ordinal values for ordered categories, quantitative values for continuous numbers, temporal values for dates or times, and GeoJSON values for geographic data. Type can be declared with a channel property or with shorthand such as `Age:Q` and `Name:N`. section 2.1.3 section 3.2.1
Build a first mapping
A bar chart can place `Age:Q` on x and `Name:N` on y. Here, age becomes horizontal position and name becomes vertical position. The same pattern scales to a time series: map `Date:T` to x, `Tourist Arrivals:Q` to y, and `Country:N` to color, producing one colored line per country. section 2.1.3 section 2.3.1
Table 3.1 The main encodings in Altair
|
Type
|
Channel
|
Description
|
|---|---|---|
|
Position
|
x, y
|
Horizontal and vertical positions
|
longitude, latitude
|
Geographical coordinates
|
|
xError, xError
|
Error values for
x and
y
|
|
x2,y2, longitude2, latitude2
|
Second positions for ranges
|
|
theta, theta2
|
Start and end arc angles
|
|
|
Mark property
|
angle, radius
|
The angle and the radius of the mark
|
color, fill
|
The color and the fill of the mark
|
|
opacity, fillOpacity
|
The opacity and the fill opacity of the mark
|
|
shape, size
|
The shape and the size of the mark
|
|
stroke, strokeDash, strokeOpacity, strokeWidth
|
Stroke properties of the mark
|
|
|
Text and tooltip
|
text
|
The text of the mark
|
tooltip
|
The tooltip of the mark
|
Browse the channel reference to choose position, mark-property, text, and tooltip mappings before writing an encoding. section 3.2.1
Channels shape what a chart makes easy to see, but they do not fix an unfocused dataset by themselves. A raw country trend chart can become cluttered when color represents too many countries; filtering, aggregation, and a focused comparison can make the encoded view more readable. Likewise, sorting a bar chart through its channels can answer which regions have the highest values, while normalization may be needed before interpreting those values as meaningful rates. section 2.3.1 section 3.3 section 5.1.1
For generated Altair code, state each mapping explicitly after the mark: name the dataset column and its intended channel. Channel-specific conditions can refine the mapping—for example, assigning bar colors according to country values—while tooltip channels can reveal supporting values on hover. section 4.4.3 section 4.4.4 section 8.4.1
