Selection Parameters

// A Single View Specification{  ...,  "params": [  // An array of named parameters.    {      "name": ...,      "select": { // Selection        "type": ...,        ...      }    }  ],  "mark": ...,  "encoding": ...,  ...}

Selection parameters definedata queries that are driven by direct manipulation user input (e.g., mouse clicks or drags). A parameter becomes a selection when theselect property is specified. This page discusses different properties of a selection.

Documentation Overview

• Common Selection Properties
  • type
  • Selection Projection withencodings andfields
    • Current Limitations
  • on
  • clear
  • resolve
• Point Selection Properties
  • toggle
  • Nearest
    • Current Limitations
• Interval Selection Properties
  • mark
  • translate
  • zoom

Common Selection Properties

For both selection types, theselect object can take the following properties:

type

Aselection’s type determines which data values fall within it by default:

• Forpoint selections, only values that have been directly interacted with (e.g., those that have been clicked on) are considered to be “selected.”
• Forinterval selections, values that fall withinboth the horizontal (x) and vertical (y) extents are considered to be “selected.”

Selection Projection withencodings andfields

In the scatterplot example below, highlightmultiplea single:Cylinder(s)Origin(s).

With interval selections, we can use the projection to restrict the region to just thehorizontal (x) and/orvertical (y) dimensions.

Current Limitations

• Selections projected over aggregatedfields/encodings can only be used within the same view they are defined in.
• Interval selections can only be projected usingencodings.
• Interval selections projected over binned ortimeUnit fields remain continuous selections. Thus, if the visual encoding discretizes them, conditional encodings will no longer work. Instead, use a layered view as shown in the example below. The bar mark discretizes the binnedAcceleration field. As a result, to highlight selected bars, we use a second layered view rather than a conditional color encoding within the same view.

on

Theon property modifies the event that triggers the selection.

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

clear

Theclear property identifies which events must fire to empty a selection of all selected values (theempty property can be used to further determine the behavior of empty selections).

The following visualization demonstrates the default clearing behavior: select a square on click and clear out the selection on double click.

The following example clears the brush when the mouse button is released.

Note, in the above example, clearing out the selection doesnot reset it to its initial value. Instead, when the mouse button is released, the selection is emptied of all values. This behavior is subtly different to when the selection isbound to scales – clearing the selection out now resets the view to use the initial scale domains. Try it out below: pan and zoom the plot, and then double click.

resolve

When a selection is defined within a data-driven view (i.e., a view that is part of afacet orrepeat), the desired behaviour can be ambiguous. Consider the scatterplot matrix (SPLOM) example below, which has an interval selection namedbrush. Should there be only one brush across all cells, or should each cell have its own brush? In the latter case, how should points be highlighted in all the other cells?

The aptly namedresolve property addresses this ambiguity, and can be set to one of the following values (click to apply it to the SPLOM example, and drag out an interval in different cells):

• global (default) – only one brush exists for the entire SPLOM. When the user begins to drag, any previous brushes are cleared, and a new one is constructed.

• union – each cell contains its own brush, and points are highlighted if they lie withinany of these individual brushes.

• intersect – each cell contains its own brush, and points are highlighted only if they fall withinall of these individual brushes.

Point Selection Properties

In addition to allcommon selection properties, point selections support the following properties:

toggle

Thetoggle property customizes how user interaction can insert or remove data values from a point selection if they are or are not already members of the selection, respectively.

For example, you can highlight points in the scatterplot below by toggling them into thepaintbrush selection when clicking with:
event.shiftKeyevent.altKey.

Nearest

Thenearest propery accelerates user selection with an invisible voronoi diagram.

For example, in the scatterplot below, pointsnearestdirectly underneath the mouse cursor are highlighted as it moves.

Thenearest transform also respects anyposition encoding projections applied to the selection. For instance, in the example below, moving the mouse cursor back-and-forth snaps the vertical rule and label to the nearestdate value.

Current Limitations

• Thenearest property is not supported for multi-element mark types (i.e.,line andarea). For these mark types, consider layering a discrete mark type (e.g.,point) with a 0-valueopacity as in the last example above.

Interval Selection Properties

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

mark

Every interval selection also adds a rectangle mark to the visualization, to depict the extents of the selected region.

The selection’smark property can include the folloiwing properties to customize the appearance of this rectangle mark.

For example, the spec below imagines two users, Alex and Morgan, who can each drag out an interval selection. To prevent collision between the two selections, Morgan must press the shift key while dragging out their interval (while Alex must not). Morgan’s interval is depicted with the default grey rectangle, and Morgan’s with a customized red rectangle.

translate

Thetranslate property allows a user to interactively move an interval selection back-and-forth.

For example, try to pan thebrushscatterplot ondragshift-drag.

zoom

Thezoom property allows a user to interactively resize an interval selection.

For example, you can zoom thebrushscatterplot onwheelshift-wheel.