Interactive Plots with Selections

// A Single View Specification
{
  ...,
  "selection": {  // Key-value mappings between selection names and definitions.
    ...: {"type": "single/multi/interval",  ...},
    ...
  },
  "mark": ...,
  "encoding": ...,
  ...
}

Selections are the basic building block in Vega-Lite’s grammar of interaction. They map user input (e.g., mouse moves and clicks, touch presses, etc.) into data queries, which can subsequently be used to drive conditional encoding rules, filter data points, or determine scale domains.

Documentation Overview

• Documentation Overview
• Selection Types
• Selection Properties
  • Common Selection Properties
  • Single Selection Properties
  • Multi Selection Properties
  • Interval Selection Properties
• Using Selections
  • Conditional Encodings
  • Filtering Data
  • Scale Domains
  • Composing Multiple Selections
• Selection Configuration

Selection Types

Selections are defined within single views, and their simplest definition consists of a name and a type. The selection type determines the default events that trigger a selection and the resultant data query.

For example, try the different types against the example selection (named pts) below:

single multi interval .

Selection Properties

While selection types provide useful defaults, it can often be useful to override these properties to customize the interaction design.

Common Selection Properties

All selection types support the following properties:

For instance, with the on property, a single rectangle in the heatmap below can now be selected on mouse hover instead.

Single Selection Properties

In addition to all common selection properties, single selections support the following properties:

Multi Selection Properties

In addition to all common selection properties, multi selections support the following properties:

Interval Selection Properties

In addition to all common selection properties, interval selections support the following properties:

Using Selections

Conditional Encodings

Selections can be used to conditionally specify visual encodings – encode data values one way if they fall within the selection, and another if they do not. For instance, in the first two examples on this page, rectangles are colored based on whether or not their data values fall within the pts selection. If they do, they are colored by the number of records; and, if they do not, they are left grey.

In this example, a selection (named paintbrush) is used to resize the points in the scatterplot on hover. This example is also useful for understanding the difference when empty selections are set to contain allnone of the data values.

See the condition documentation for more information.

Filtering Data

Selections in one view can also be used to filter input data to another view. In the example below, two scatterplots are concatenated vertically. An interval selection (named brush) is defined in the first plot and is used to filter the points in the second. Thus, the Acceleration x Displacement scatterplot only visualizes points that fall within the brushed region.

Scale Domains

With multiview displays, selections can also be used to determine the domains of scales in other views. For example, in the specification below, the bottom plot contains an interval selection named brush. We use this brush selection to parameterize the domain of the top plot’s x-scale to make it show only the selected interval. This technique is called an overview+detail display.

An alternate way to construct this technique would be to filter out the input data to the top (detail) view like so:

{
  "vconcat": [{
    "transform": [{"filter": {"selection": "brush"}}],
    ...
  }]
}

However, setting the scale domains (rather than filtering data out) yields superior interactive performance. Rather than testing whether each data value falls within the selection or not, the scale domains are changed directly to the brush extents.

If the selection is projected over multiple fields or encodings, one must be given as part of the scale domain definition. Vega-Lite automatically infers this property if the selection is only projected over a single field or encoding. Thus, with the above example, the scale domain can be specified more explicitly as:

• "scale": {"domain": {"selection": "brush", "encoding": "x"}} or
• "scale": {"domain": {"selection": "brush", "field": "date"}}

Note: For a selection to manipulate the scales of its own view, use the bind operator instead.

Composing Multiple Selections

So far, we have only considered how to use one selection at a time. Vega-Lite also supports combining multiple selections using the not, or, and and logical composition operators.

For example, we had previously seen how we could setup two interval selections for our users Alex and Morgan. Now, we color the rectangles when they fall within Alex’s andor Morgan’s selections.

With these operators, selections can be combined in arbitrary ways:

• "selection": {"not": {"and": ["alex", "morgan"]}}
• "selection": {"or": ["alex", {"not": "morgan"}]}

When using selections with filter operators, logical composition can be used to mix selections with other filter operators. For example, as shown below, the Displacement x Acceleration scatterplot now visualizes points that lie within the brushed region and have a Weight_in_lbs > 3000.

Note: Logical composition is not supported when selections are used to drive scale domains.

Selection Configuration

// Top-level View Specification
{
  ...,
  "config": {          // Configuration Object
    "selection": { ... },   // - Selection Configuration
    ...
  }
}

The selection property of the config object determines the default properties and transformations applied to different types of selections. The selection config can contain the following properties: