0
# Encodings & Channels
1
2
Visual encoding channels that map data fields to visual properties like position, color, size, and shape. These form the core of Altair's grammar of graphics implementation, allowing declarative mapping from data dimensions to visual dimensions.
3
4
## Capabilities
5
6
### Position Channels
7
8
Encoding channels for spatial positioning of marks on x and y axes, including primary and secondary positions for ranges and spans.
9
10
```python { .api }
11
class X:
12
def __init__(
13
self,
14
field=None,
15
type=None,
16
aggregate=None,
17
bin=None,
18
timeUnit=None,
19
scale=None,
20
axis=None,
21
sort=None,
22
title=None,
23
**kwargs
24
):
25
"""
26
X-axis position encoding.
27
28
Parameters:
29
- field: Data field name
30
- type: Data type ('quantitative', 'ordinal', 'nominal', 'temporal')
31
- aggregate: Aggregation function ('mean', 'sum', 'count', etc.)
32
- bin: Binning specification (bool or BinParams)
33
- timeUnit: Time unit for temporal data
34
- scale: Scale configuration
35
- axis: Axis configuration
36
- sort: Sort specification
37
- title: Axis title
38
"""
39
40
class Y:
41
def __init__(
42
self,
43
field=None,
44
type=None,
45
aggregate=None,
46
bin=None,
47
timeUnit=None,
48
scale=None,
49
axis=None,
50
sort=None,
51
title=None,
52
**kwargs
53
):
54
"""Y-axis position encoding."""
55
56
class X2:
57
def __init__(self, field=None, type=None, value=None, datum=None, **kwargs):
58
"""Secondary x-position for spans/ranges."""
59
60
class Y2:
61
def __init__(self, field=None, type=None, value=None, datum=None, **kwargs):
62
"""Secondary y-position for spans/ranges."""
63
64
class XOffset:
65
def __init__(self, field=None, type=None, value=None, datum=None, **kwargs):
66
"""X-position offset for fine positioning."""
67
68
class YOffset:
69
def __init__(self, field=None, type=None, value=None, datum=None, **kwargs):
70
"""Y-position offset for fine positioning."""
71
```
72
73
### Mark Property Channels
74
75
Encoding channels for visual properties of marks including color, size, opacity, and stroke properties.
76
77
```python { .api }
78
class Color:
79
def __init__(
80
self,
81
field=None,
82
type=None,
83
scale=None,
84
legend=None,
85
condition=None,
86
value=None,
87
**kwargs
88
):
89
"""
90
Color encoding for mark fill/stroke.
91
92
Parameters:
93
- field: Data field name
94
- type: Data type
95
- scale: Color scale configuration
96
- legend: Legend configuration
97
- condition: Conditional encoding
98
- value: Fixed color value
99
"""
100
101
class Fill:
102
def __init__(
103
self,
104
field=None,
105
type=None,
106
scale=None,
107
legend=None,
108
condition=None,
109
value=None,
110
**kwargs
111
):
112
"""Fill color encoding."""
113
114
class Stroke:
115
def __init__(
116
self,
117
field=None,
118
type=None,
119
scale=None,
120
legend=None,
121
condition=None,
122
value=None,
123
**kwargs
124
):
125
"""Stroke color encoding."""
126
127
class Opacity:
128
def __init__(
129
self,
130
field=None,
131
type=None,
132
scale=None,
133
legend=None,
134
condition=None,
135
value=None,
136
**kwargs
137
):
138
"""Opacity encoding."""
139
140
class FillOpacity:
141
def __init__(
142
self,
143
field=None,
144
type=None,
145
scale=None,
146
legend=None,
147
condition=None,
148
value=None,
149
**kwargs
150
):
151
"""Fill opacity encoding."""
152
153
class StrokeOpacity:
154
def __init__(
155
self,
156
field=None,
157
type=None,
158
scale=None,
159
legend=None,
160
condition=None,
161
value=None,
162
**kwargs
163
):
164
"""Stroke opacity encoding."""
165
166
class Size:
167
def __init__(
168
self,
169
field=None,
170
type=None,
171
scale=None,
172
legend=None,
173
condition=None,
174
value=None,
175
**kwargs
176
):
177
"""Size encoding for marks."""
178
179
class StrokeWidth:
180
def __init__(
181
self,
182
field=None,
183
type=None,
184
scale=None,
185
legend=None,
186
condition=None,
187
value=None,
188
**kwargs
189
):
190
"""Stroke width encoding."""
191
192
class StrokeDash:
193
def __init__(
194
self,
195
field=None,
196
type=None,
197
scale=None,
198
legend=None,
199
condition=None,
200
value=None,
201
**kwargs
202
):
203
"""Stroke dash pattern encoding."""
204
205
class Shape:
206
def __init__(
207
self,
208
field=None,
209
type=None,
210
scale=None,
211
legend=None,
212
condition=None,
213
value=None,
214
**kwargs
215
):
216
"""Shape encoding for point marks."""
217
```
218
219
### Polar Coordinate Channels
220
221
Encoding channels for polar coordinate systems used in pie charts, arc plots, and radial visualizations.
222
223
```python { .api }
224
class Angle:
225
def __init__(
226
self,
227
field=None,
228
type=None,
229
scale=None,
230
value=None,
231
**kwargs
232
):
233
"""Angle encoding for arc marks."""
234
235
class Theta:
236
def __init__(
237
self,
238
field=None,
239
type=None,
240
scale=None,
241
value=None,
242
**kwargs
243
):
244
"""Angular position in polar coordinates."""
245
246
class Theta2:
247
def __init__(self, field=None, type=None, value=None, datum=None, **kwargs):
248
"""Secondary angular position."""
249
250
class Radius:
251
def __init__(
252
self,
253
field=None,
254
type=None,
255
scale=None,
256
value=None,
257
**kwargs
258
):
259
"""Radial position in polar coordinates."""
260
261
class Radius2:
262
def __init__(self, field=None, type=None, value=None, datum=None, **kwargs):
263
"""Secondary radial position."""
264
```
265
266
### Facet and Detail Channels
267
268
Encoding channels for creating small multiples, grouping data, and controlling visual details without mapping to visual properties.
269
270
```python { .api }
271
class Column:
272
def __init__(
273
self,
274
field=None,
275
type=None,
276
sort=None,
277
spacing=None,
278
header=None,
279
**kwargs
280
):
281
"""Column faceting encoding."""
282
283
class Row:
284
def __init__(
285
self,
286
field=None,
287
type=None,
288
sort=None,
289
spacing=None,
290
header=None,
291
**kwargs
292
):
293
"""Row faceting encoding."""
294
295
class Facet:
296
def __init__(
297
self,
298
field=None,
299
type=None,
300
columns=None,
301
sort=None,
302
header=None,
303
**kwargs
304
):
305
"""General faceting encoding."""
306
307
class Detail:
308
def __init__(self, field=None, type=None, **kwargs):
309
"""Additional grouping without visual encoding."""
310
311
class Key:
312
def __init__(self, field=None, type=None, **kwargs):
313
"""Key field for object constancy in animations."""
314
315
class Order:
316
def __init__(self, field=None, type=None, sort=None, **kwargs):
317
"""Order encoding for line/area connection order."""
318
```
319
320
### Metadata Channels
321
322
Encoding channels for metadata and supplementary information like tooltips, hyperlinks, and accessibility descriptions.
323
324
```python { .api }
325
class Tooltip:
326
def __init__(
327
self,
328
field=None,
329
type=None,
330
format=None,
331
formatType=None,
332
value=None,
333
**kwargs
334
):
335
"""Tooltip encoding for hover information."""
336
337
class Href:
338
def __init__(self, field=None, type=None, value=None, **kwargs):
339
"""Hyperlink encoding."""
340
341
class Description:
342
def __init__(self, field=None, type=None, value=None, **kwargs):
343
"""Accessibility description encoding."""
344
345
class Text:
346
def __init__(
347
self,
348
field=None,
349
type=None,
350
format=None,
351
formatType=None,
352
value=None,
353
**kwargs
354
):
355
"""Text encoding for text marks."""
356
```
357
358
### Geographic Channels
359
360
Encoding channels specifically for geographic and cartographic data visualization.
361
362
```python { .api }
363
class Latitude:
364
def __init__(self, field=None, type=None, scale=None, **kwargs):
365
"""Latitude encoding for geographic data."""
366
367
class Longitude:
368
def __init__(self, field=None, type=None, scale=None, **kwargs):
369
"""Longitude encoding for geographic data."""
370
371
class Latitude2:
372
def __init__(self, field=None, type=None, value=None, datum=None, **kwargs):
373
"""Secondary latitude coordinate."""
374
375
class Longitude2:
376
def __init__(self, field=None, type=None, value=None, datum=None, **kwargs):
377
"""Secondary longitude coordinate."""
378
```
379
380
### Error Bar Channels
381
382
Encoding channels for representing uncertainty and error ranges in visualizations.
383
384
```python { .api }
385
class XError:
386
def __init__(self, field=None, type=None, value=None, **kwargs):
387
"""X-direction error encoding."""
388
389
class YError:
390
def __init__(self, field=None, type=None, value=None, **kwargs):
391
"""Y-direction error encoding."""
392
393
class XError2:
394
def __init__(self, field=None, type=None, value=None, **kwargs):
395
"""Secondary X-direction error encoding."""
396
397
class YError2:
398
def __init__(self, field=None, type=None, value=None, **kwargs):
399
"""Secondary Y-direction error encoding."""
400
```
401
402
## Usage Examples
403
404
### Basic Position Encoding
405
406
```python
407
import altair as alt
408
409
# Simple x, y encoding
410
chart = alt.Chart(data).mark_point().encode(
411
x='xfield:Q', # Quantitative x
412
y='yfield:Q' # Quantitative y
413
)
414
415
# With explicit encoding objects
416
chart = alt.Chart(data).mark_point().encode(
417
x=alt.X('xfield:Q', title='X Axis Title'),
418
y=alt.Y('yfield:Q', scale=alt.Scale(zero=False))
419
)
420
```
421
422
### Color and Size Encoding
423
424
```python
425
# Color by category, size by value
426
chart = alt.Chart(data).mark_circle().encode(
427
x='x:Q',
428
y='y:Q',
429
color=alt.Color('category:N', scale=alt.Scale(scheme='category10')),
430
size=alt.Size('value:Q', scale=alt.Scale(range=[50, 400]))
431
)
432
```
433
434
### Conditional Encoding
435
436
```python
437
# Conditional color based on selection
438
selection = alt.selection_point()
439
440
chart = alt.Chart(data).mark_circle().add_selection(
441
selection
442
).encode(
443
x='x:Q',
444
y='y:Q',
445
color=alt.condition(selection, 'category:N', alt.value('lightgray'))
446
)
447
```
448
449
### Faceted Visualization
450
451
```python
452
# Facet by category
453
chart = alt.Chart(data).mark_point().encode(
454
x='x:Q',
455
y='y:Q',
456
column=alt.Column('category:N', header=alt.Header(title='Category'))
457
)
458
```
459
460
### Tooltip with Multiple Fields
461
462
```python
463
# Multi-field tooltip
464
chart = alt.Chart(data).mark_circle().encode(
465
x='x:Q',
466
y='y:Q',
467
tooltip=['x:Q', 'y:Q', 'category:N', 'value:Q']
468
)
469
470
# Custom tooltip formatting
471
chart = alt.Chart(data).mark_circle().encode(
472
x='x:Q',
473
y='y:Q',
474
tooltip=[
475
alt.Tooltip('x:Q', title='X Value'),
476
alt.Tooltip('y:Q', title='Y Value', format='.2f')
477
]
478
)
479
```
480
481
## Types
482
483
```python { .api }
484
from typing import Union, Dict, Any, Optional, List
485
486
# Data types
487
DataType = Union['quantitative', 'ordinal', 'nominal', 'temporal', 'geojson']
488
DataTypeShort = Union['Q', 'O', 'N', 'T', 'G']
489
490
# Field specification
491
FieldName = str
492
ShorthandString = str # e.g., 'field:Q', 'mean(field):Q'
493
494
# Aggregate operations
495
AggregateOp = Union[
496
'argmax', 'argmin', 'average', 'count', 'distinct', 'max', 'mean',
497
'median', 'min', 'missing', 'q1', 'q3', 'ci0', 'ci1', 'stderr',
498
'stdev', 'stdevp', 'sum', 'valid', 'values', 'variance', 'variancep'
499
]
500
501
# Time units
502
TimeUnit = Union[
503
'year', 'quarter', 'month', 'day', 'date', 'hours', 'minutes',
504
'seconds', 'milliseconds', 'yearquarter', 'yearquartermonth',
505
'yearmonth', 'yearmonthdate', 'yearmonthdatehours',
506
'yearmonthdatehoursminutes', 'yearmonthdatehoursminutesseconds'
507
]
508
509
# Scale types
510
ScaleType = Union[
511
'linear', 'log', 'pow', 'sqrt', 'symlog', 'identity', 'sequential',
512
'time', 'utc', 'ordinal', 'band', 'point', 'bin-ordinal', 'quantile',
513
'quantize', 'threshold'
514
]
515
516
# Sort specification
517
SortOrder = Union['ascending', 'descending']
518
SortField = Dict[str, Any]
519
Sort = Union[SortOrder, SortField, List[str], None]
520
521
# Conditional encoding
522
ConditionalEncoding = Dict[str, Any]
523
524
# Value types for encodings
525
EncodingValue = Union[str, int, float, bool, None]
526
```