0
# Parameters & Interactions
1
2
Interactive parameters and selections that enable dynamic, interactive visualizations with user input controls and cross-filtering. Parameters provide the foundation for creating responsive visualizations that update based on user interaction.
3
4
## Capabilities
5
6
### Parameter Creation
7
8
Core functions for creating interactive parameters that can be bound to UI controls or driven by selections.
9
10
```python { .api }
11
def param(
12
name=None,
13
value=None,
14
bind=None,
15
empty=None,
16
expr=None,
17
**kwargs
18
):
19
"""
20
Create an interactive parameter.
21
22
Parameters:
23
- name: Parameter name (auto-generated if not provided)
24
- value: Initial parameter value
25
- bind: UI binding specification
26
- empty: Behavior when selection is empty
27
- expr: Expression for parameter value
28
29
Returns:
30
Parameter: Parameter object with operator methods
31
"""
32
33
class Parameter:
34
def __init__(self, **kwargs):
35
"""
36
Interactive parameter with logical operators.
37
38
Supports logical operations: &, |, ~, ==, !=, <, <=, >, >=
39
"""
40
41
def __and__(self, other):
42
"""Logical AND operation (param1 & param2)."""
43
44
def __or__(self, other):
45
"""Logical OR operation (param1 | param2)."""
46
47
def __invert__(self):
48
"""Logical NOT operation (~param)."""
49
50
def __eq__(self, other):
51
"""Equality comparison (param == value)."""
52
53
def __ne__(self, other):
54
"""Inequality comparison (param != value)."""
55
56
def __lt__(self, other):
57
"""Less than comparison (param < value)."""
58
59
def __le__(self, other):
60
"""Less than or equal (param <= value)."""
61
62
def __gt__(self, other):
63
"""Greater than comparison (param > value)."""
64
65
def __ge__(self, other):
66
"""Greater than or equal (param >= value)."""
67
68
def to_dict(self):
69
"""Convert parameter to dictionary specification."""
70
```
71
72
### Selection Functions
73
74
Functions for creating different types of selections that capture user interactions.
75
76
```python { .api }
77
def selection_point(
78
name=None,
79
fields=None,
80
on=None,
81
clear=None,
82
empty=None,
83
init=None,
84
nearest=None,
85
resolve=None,
86
toggle=None,
87
**kwargs
88
):
89
"""
90
Create a point selection parameter.
91
92
Parameters:
93
- name: Selection name
94
- fields: Data fields to project selection over
95
- on: Event specification for triggering selection
96
- clear: Event specification for clearing selection
97
- empty: Behavior when selection is empty ('all' or 'none')
98
- init: Initial selection values
99
- nearest: Whether to select nearest data point
100
- resolve: Selection resolution ('global', 'union', 'intersect')
101
- toggle: Toggle mode for selection ('true', 'false', or expression)
102
103
Returns:
104
SelectionParameter: Point selection parameter
105
"""
106
107
def selection_interval(
108
name=None,
109
encodings=None,
110
on=None,
111
clear=None,
112
empty=None,
113
init=None,
114
mark=None,
115
resolve=None,
116
translate=None,
117
zoom=None,
118
**kwargs
119
):
120
"""
121
Create an interval selection parameter.
122
123
Parameters:
124
- name: Selection name
125
- encodings: Encoding channels to project over ('x', 'y', etc.)
126
- on: Event specification for triggering selection
127
- clear: Event specification for clearing selection
128
- empty: Behavior when selection is empty
129
- init: Initial selection extent
130
- mark: Mark properties for selection brush
131
- resolve: Selection resolution
132
- translate: Translation interaction specification
133
- zoom: Zoom interaction specification
134
135
Returns:
136
SelectionParameter: Interval selection parameter
137
"""
138
139
# Legacy selection functions (deprecated but still available)
140
def selection_single(**kwargs):
141
"""Create single-point selection (deprecated, use selection_point)."""
142
143
def selection_multi(**kwargs):
144
"""Create multi-point selection (deprecated, use selection_point)."""
145
```
146
147
### Parameter Binding
148
149
Functions for binding parameters to UI controls for interactive input.
150
151
```python { .api }
152
def binding(input_type, **kwargs):
153
"""
154
Create a general parameter binding specification.
155
156
Parameters:
157
- input_type: Type of input control
158
- **kwargs: Input-specific options
159
160
Returns:
161
dict: Binding specification
162
"""
163
164
def binding_checkbox(name=None, **kwargs):
165
"""
166
Create checkbox binding for boolean parameters.
167
168
Parameters:
169
- name: Input name/label
170
171
Returns:
172
dict: Checkbox binding specification
173
"""
174
175
def binding_radio(options, name=None, **kwargs):
176
"""
177
Create radio button binding for categorical parameters.
178
179
Parameters:
180
- options: List of option values
181
- name: Input name/label
182
183
Returns:
184
dict: Radio button binding specification
185
"""
186
187
def binding_range(
188
min=None,
189
max=None,
190
step=None,
191
name=None,
192
**kwargs
193
):
194
"""
195
Create range slider binding for numeric parameters.
196
197
Parameters:
198
- min: Minimum value
199
- max: Maximum value
200
- step: Step size
201
- name: Input name/label
202
203
Returns:
204
dict: Range slider binding specification
205
"""
206
207
def binding_select(options, name=None, **kwargs):
208
"""
209
Create select dropdown binding for categorical parameters.
210
211
Parameters:
212
- options: List of option values
213
- name: Input name/label
214
215
Returns:
216
dict: Select dropdown binding specification
217
"""
218
```
219
220
### Conditional Logic
221
222
Functions for creating conditional encodings and expressions based on parameters and selections.
223
224
```python { .api }
225
def condition(
226
predicate,
227
if_true,
228
if_false=None,
229
**kwargs
230
):
231
"""
232
Create conditional encoding based on parameter or selection.
233
234
Parameters:
235
- predicate: Parameter, selection, or test expression
236
- if_true: Value when condition is true
237
- if_false: Value when condition is false (optional)
238
239
Returns:
240
dict: Conditional encoding specification
241
"""
242
243
def when(predicate):
244
"""
245
Start a conditional chain with when().then().otherwise().
246
247
Parameters:
248
- predicate: Parameter, selection, or test expression
249
250
Returns:
251
ChainedWhen: Object for method chaining
252
"""
253
254
class ChainedWhen:
255
def then(self, value):
256
"""
257
Specify value when condition is true.
258
259
Returns:
260
Then: Object for continuing chain
261
"""
262
263
class Then:
264
def when(self, predicate):
265
"""Add additional condition to chain."""
266
267
def otherwise(self, value):
268
"""Specify final fallback value."""
269
```
270
271
### Value Functions
272
273
Functions for creating value expressions and references.
274
275
```python { .api }
276
def value(val):
277
"""
278
Create a value expression for fixed values in encodings.
279
280
Parameters:
281
- val: Fixed value (number, string, color, etc.)
282
283
Returns:
284
dict: Value specification
285
"""
286
```
287
288
## Usage Examples
289
290
### Basic Parameter with Binding
291
292
```python
293
import altair as alt
294
295
# Numeric parameter with slider
296
size_param = alt.param(
297
value=100,
298
bind=alt.binding_range(min=10, max=500, step=10, name='Point Size')
299
)
300
301
chart = alt.Chart(data).add_params(
302
size_param
303
).mark_circle(size=size_param).encode(
304
x='x:Q',
305
y='y:Q'
306
)
307
```
308
309
### Point Selection
310
311
```python
312
# Click selection with conditional color
313
click = alt.selection_point()
314
315
chart = alt.Chart(data).add_params(
316
click
317
).mark_circle().encode(
318
x='x:Q',
319
y='y:Q',
320
color=alt.condition(click, 'category:N', alt.value('lightgray'))
321
)
322
```
323
324
### Interval Selection with Filtering
325
326
```python
327
# Brush selection for filtering
328
brush = alt.selection_interval()
329
330
base = alt.Chart(data).add_params(brush)
331
332
points = base.mark_circle().encode(
333
x='x:Q',
334
y='y:Q',
335
color=alt.condition(brush, 'category:N', alt.value('lightgray'))
336
)
337
338
bars = base.mark_bar().encode(
339
x='category:N',
340
y='count():Q'
341
).transform_filter(brush)
342
343
chart = points & bars
344
```
345
346
### Parameter-Driven Filtering
347
348
```python
349
# Dropdown parameter for category filtering
350
category_param = alt.param(
351
value='All',
352
bind=alt.binding_select(
353
options=['All', 'A', 'B', 'C'],
354
name='Category'
355
)
356
)
357
358
chart = alt.Chart(data).add_params(
359
category_param
360
).mark_point().encode(
361
x='x:Q',
362
y='y:Q',
363
color='category:N'
364
).transform_filter(
365
(category_param == 'All') | (alt.datum.category == category_param)
366
)
367
```
368
369
### Complex Conditional Logic
370
371
```python
372
# Multi-condition parameter
373
threshold_param = alt.param(value=50, bind=alt.binding_range(min=0, max=100))
374
375
chart = alt.Chart(data).add_params(
376
threshold_param
377
).mark_circle().encode(
378
x='x:Q',
379
y='y:Q',
380
color=alt.when(
381
alt.datum.value > threshold_param
382
).then(
383
alt.value('red')
384
).when(
385
alt.datum.value > threshold_param / 2
386
).then(
387
alt.value('orange')
388
).otherwise(
389
alt.value('blue')
390
)
391
)
392
```
393
394
### Cross-Chart Interaction
395
396
```python
397
# Shared selection across multiple charts
398
brush = alt.selection_interval()
399
400
chart1 = alt.Chart(data).add_params(
401
brush
402
).mark_circle().encode(
403
x='x:Q',
404
y='y:Q',
405
color=alt.condition(brush, 'category:N', alt.value('lightgray'))
406
)
407
408
chart2 = alt.Chart(data).mark_bar().encode(
409
x='category:N',
410
y='mean(value):Q',
411
opacity=alt.condition(brush, alt.value(1.0), alt.value(0.3))
412
).transform_filter(brush)
413
414
combined = chart1 | chart2
415
```
416
417
### Parameter Expressions
418
419
```python
420
# Parameter with calculated expression
421
base_param = alt.param(value=10)
422
multiplier_param = alt.param(value=2)
423
424
# Use parameters in calculated field
425
chart = alt.Chart(data).add_params(
426
base_param,
427
multiplier_param
428
).mark_circle().encode(
429
x='x:Q',
430
y='y:Q',
431
size=alt.expr(f'{base_param} * {multiplier_param} * datum.value')
432
)
433
```
434
435
## Types
436
437
```python { .api }
438
from typing import Union, Dict, Any, Optional, List
439
440
# Parameter types
441
ParameterValue = Union[str, int, float, bool, List[Any]]
442
ParameterBinding = Dict[str, Any]
443
444
# Selection types
445
SelectionType = Union['point', 'interval']
446
SelectionResolution = Union['global', 'union', 'intersect']
447
SelectionEmpty = Union['all', 'none']
448
449
# Event specifications
450
EventType = Union[str, Dict[str, Any]]
451
EventStream = Union[str, Dict[str, Any]]
452
453
# Binding input types
454
InputType = Union['checkbox', 'radio', 'range', 'select', 'text', 'number', 'date', 'time', 'month', 'week', 'datetime-local', 'tel', 'url']
455
456
# Conditional predicate types
457
ConditionalPredicate = Union[Parameter, Dict[str, Any], str]
458
459
# Selection configuration
460
class SelectionConfig:
461
point: Optional[Dict[str, Any]] = None
462
interval: Optional[Dict[str, Any]] = None
463
464
# Parameter specification
465
class ParameterSpec:
466
name: str
467
value: Optional[ParameterValue] = None
468
bind: Optional[ParameterBinding] = None
469
expr: Optional[str] = None
470
471
# Selection parameter specification
472
class SelectionParameterSpec(ParameterSpec):
473
select: SelectionType
474
init: Optional[Dict[str, Any]] = None
475
on: Optional[EventStream] = None
476
clear: Optional[EventStream] = None
477
empty: Optional[SelectionEmpty] = None
478
resolve: Optional[SelectionResolution] = None
479
```