Selections: Building Blocks of Interactions¶
One of the unique features of Altair, inherited from Vega-Lite, is a declarative grammar of not just visualization, but interaction. The core concept of this grammar is the selection object.
Selections in Altair come in a few flavors, and they can be bound to particular charts or sub-charts in your visualization, then referenced in other parts of the visualization.
Selection Types: Interval, Single, Multi¶
With this interesting example under our belt, let’s take a more systematic
look at some of the types of selections available in Altair.
For simplicity, we’ll use a common chart in all the following examples; a
simple heat-map based on the
For convenience, let’s write a quick Python function that will take a selection
object and create a chart with the color of the chart elements linked to this
def make_example(selector): cars = data.cars.url return alt.Chart(cars).mark_rect().encode( x="Cylinders:O", y="Origin:N", color=alt.condition(selector, 'count()', alt.value('lightgray')) ).properties( width=300, height=180 ).add_selection( selector )
Next we’ll use this function to demonstrate the properties of various selections.
An interval selection allows you to select chart elements by clicking and dragging.
You can create such a selection using the
interval = alt.selection_interval() make_example(interval)
As you click and drag on the plot, you’ll find that your mouse creates a box that can be subsequently moved to change the selection.
selection_interval() function takes a few additional arguments; for
example we can bind the interval to only the x-axis, and set it such that the
empty selection contains none of the points:
interval_x = alt.selection_interval(encodings=['x'], empty='none') make_example(interval_x)
A special case of an interval selection is when the interval is bound to the chart scales; this is how Altair plots can be made interactive:
scales = alt.selection_interval(bind='scales') alt.Chart(cars).mark_point().encode( x='Horsepower:Q', y='Miles_per_Gallon:Q', color='Origin:N' ).add_selection( scales )
Because this is such a common pattern, Altair provides the
method which creates such a selection more concisely.
A single selection allows you to select a single chart element at a time using mouse actions. By default, points are selected on click:
single = alt.selection_single() make_example(single)
By changing some arguments, we can select points on mouseover rather than on
click. We can also set the
nearest flag to
True so that the nearest
point is highlighted:
single_nearest = alt.selection_single(on='mouseover', nearest=True) make_example(single_nearest)
A multi selection is similar to a single selection, but it allows for multiple chart objects to be selected at once. By default, chart elements can be added to and removed from the selection by clicking on them while holding the shift key:
multi = alt.selection_multi() make_example(multi)
In addition to the options seen in
selection_single(), the multi selection
toggle parameter, which controls whether points can be removed
from the selection once they are added.
For example, here is a plot where you can “paint” the chart objects by hovering over them with your mouse:
multi_mouseover = alt.selection_multi(on='mouseover', toggle=False, empty='none') make_example(multi_mouseover)
Selection Targets: Fields and Encodings¶
For any but the simplest selections, the user needs to think about exactly
what is targeted by the selection, and this can be controlled with either the
encodings arguments. These control what data properties are
used to determine which points are part of the selection.
For example, here we create a small chart that acts as an interactive legend,
by targeting the Origin field using
fields=['Origin']. Clicking on points
in the upper-left plot (the legend) will propagate a selection for all points
with a matching
selection = alt.selection_multi(fields=['Origin']) color = alt.condition(selection, alt.Color('Origin:N', legend=None), alt.value('lightgray')) scatter = alt.Chart(cars).mark_point().encode( x='Horsepower:Q', y='Miles_per_Gallon:Q', color=color, tooltip='Name:N' ) legend = alt.Chart(cars).mark_point().encode( y=alt.Y('Origin:N', axis=alt.Axis(orient='right')), color=color ).add_selection( selection ) scatter | legend
The above could be equivalently replace
encodings=['color'], because in this case the chart maps
Similarly, we can specify multiple fields and/or encodings that must be matched in order for a datum to be included in a selection. For example, we could modify the above chart to create a two-dimensional clickable legend that will select points by both Origin and number of cylinders:
selection = alt.selection_multi(fields=['Origin', 'Cylinders']) color = alt.condition(selection, alt.Color('Origin:N', legend=None), alt.value('lightgray')) scatter = alt.Chart(cars).mark_point().encode( x='Horsepower:Q', y='Miles_per_Gallon:Q', color=color, tooltip='Name:N' ) legend = alt.Chart(cars).mark_rect().encode( y=alt.Y('Origin:N', axis=alt.Axis(orient='right')), x='Cylinders:O', color=color ).add_selection( selection ) scatter | legend
By fine-tuning the behavior of selections in this way, they can be used to create a wide variety of linked interactive chart types.
Now that you understand the basics of Altair selections, you might wish to look through the Interactive Charts section of the example gallery for ideas about how they can be applied to more interesting charts.
For more information on how to fine-tune selections, including specifying other mouse and keystroke options, see the Vega-Lite Selection documentation.