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, 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' ).properties( 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)
Now that you understand the basics of Altair selections, you might wish to look through the Interactive 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.