Interactors

Allows users to create interactive plots.

• Designs plots with interactive behaviour, such as selecting or highlighting values, and panning or zooming the display.
• Determines which fields an interactor should select, looks at the corresponding encoding channels for the most recently added mark.
• The interactors accept options which explicity indicates the data fields should be accepted.

🔗 Explore Interactors: Use Cases

Function Parameters

1. Highlight

• Highlights individual data points based on selection.

Function Signature

app.mosaic(
	vg.interactors.highlight(
		by, fill, fillOpacity, opacity,
		stroke, strokeOpacity
	)
)

Parameter	Description
by (Parameter)	The input selection used to highlight the marks. Unselected marks are deemphasized.
opacity (Union[int, float])	The overall opacity of deemphasized marks. By default, this value is set to 0.2.
fillOpacity (Union[int, float])	The fill opacity of deemphasized marks. By default, the fill opacity is unchanged.
strokeOpacity (Union[int, float])	The stroke opacity of deemphasized marks. By default, the stroke opacity is unchanged.
fill (str)	The fill color of deemphasized marks. By default, the fill color is unchanged.
stroke (str)	The stroke color of deemphasized marks. By default, the stroke color is unchanged.

2. Interval 1D

• Select all values within an interval range in 1D.

Function Signature

app.mosaic(
	vg.interactors.intervalX(
		as_, brush, field,
		peers, pixelSize
	)
)

app.mosaic(
	vg.interactors.intervalY(
		as_, brush, field,
		peers, pixelSize
	)
)

Parameter	Description
as_ (Parameter)	The output selection. A clause of the form field BETWEEN lo AND hi is added for the currently selected interval [lo, hi].
field (str)	The name of the field (database column) over which the interval selection should be defined. Defaults to the first valid prior mark definition.
pixelSize (int)	The size of an interactive pixel (default 1). Larger pixel sizes reduce brush resolution, reducing the size of data cube indexes.
peers (bool)	A flag indicating whether peer (sibling) marks are affected during cross-filtering (default true). If false, peer marks are not filtered in cross-filtering.
brush (BrushStyles)	CSS styles for the brush (SVG rect) element.

• Interval X

  Accepts all parameters from Interval1D options.

  Returns an IntervalX selection over the x scale domain.

• Interval Y

  Accepts all parameters from Interval1D options.

  Returns an IntervalY selection over the y scale domain.

3. Interval 2D

• Select all values within an interval range in 2D.

Function Signature

app.mosaic(
	vg.interactors.intervalXY(
		as_, brush, peers,
		pixelSize, xfield, yfield
	)
)

Parameter	Description
as_ (Parameter)	The output selection. A clause of the form (xfield BETWEEN x1 AND x2) AND (yfield BETWEEN y1 AND y2) is added for the currently selected intervals.
xfield (str)	The name of the field (database column) over which the x-component of the interval selection should be defined. Defaults to the x channel field of the first valid prior mark definition.
yfield (str)	The name of the field (database column) over which the y-component of the interval selection should be defined. Defaults to the y channel field of the first valid prior mark definition.
pixelSize (int)	The size of an interactive pixel (default 1). Larger pixel sizes reduce the brush resolution, which can reduce the size of data cube indexes.
peers (bool)	A flag indicating if peer (sibling) marks are affected when cross-filtering (default true). If set to false, peer marks will not be filtered by this interactor's selection in cross-filtering setups.
brush (BrushStyles)	CSS styles for the brush (SVG rect) element.

• Interval XY

  Accepts all parameters from Interval2D options.

  Returns an IntervalXY selection over the x and y scale domains.

4. Nearest

• Select the nearest value to the current cursor position.

Function Signature

app.mosaic(
	vg.interactors.nearestX(
		as_, channels,
		fields, maxRadius
	)
)

app.mosaic(
	vg.interactors.nearestY(
		as_, channels,
		fields, maxRadius
	)
)

Parameter	Description
as_ (Parameter)	The output selection. A clause of the form field = value is added for the currently nearest value.
channels (List[str])	The encoding channels whose domain values should be selected. For example, ['color'] selects the data value backing the color channel, ['x', 'z'] selects both x and z channel domain values.
fields (List[str])	The fields (database column names) to use in generated selection clause predicates. If unspecified, the fields backing the selected channels in the first valid prior mark definition are used.
maxRadius (Union[int, float])	The maximum radius of a nearest selection (default 40). Marks with (x, y) coordinates outside this radius will not be selected as nearest points.

• Nearest X

  Accepts all parameters from Nearest options.

  Returns a NearestX selection over the x scale domain.

• Nearest Y

  Accepts all parameters from Nearest options.

  Returns a NearestY selection over the y scale domain.

5. Pan and Zoom

• Pan or zoom a plot. To pan, click and drag within a plot. To zoom, scroll within in a plot.

• Panning and zooming is implemented by changing the x and/or y scale domains and re-rendering the plot in response.

Function Signature

app.mosaic(
	vg.interactors.pan(
		x, xfield, y, yfield
	)
)

app.mosaic(
	vg.interactors.panX(
		x, xfield, y, yfield
	)
)

app.mosaic(
	vg.interactors.panY(
		x, xfield, y, yfield
	)
)

app.mosaic(
	vg.interactors.panZoom(
		x, xfield, y, yfield
	)
)

app.mosaic(
	vg.interactors.panZoomX(
		x, xfield, y, yfield
	)
)

app.mosaic(
	vg.interactors.panZoomY(
		x, xfield, y, yfield
	)
)

Parameter	Description
x (Parameter)	The output selection for the x domain. A clause of the form field BETWEEN x1 AND x2 is added for the current pan/zoom interval [x1, x2].
y (Parameter)	The output selection for the y domain. A clause of the form field BETWEEN y1 AND y2 is added for the current pan/zoom interval [y1, y2].
xfield (str)	The name of the field (database column) over which the x-component of the pan/zoom interval should be defined. If unspecified, the x channel field of the first valid prior mark definition is used.
yfield (str)	The name of the field (database column) over which the y-component of the pan/zoom interval should be defined. If unspecified, the y channel field of the first valid prior mark definition is used.

• Pan - Accepts all parameters from PanZoomOptions. Returns a Pan selection for panning a plot along both x and y scales.
• PanX - Accepts all parameters from PanZoomOptions. Returns a PanX selection for panning a plot along the x scale only.
• PanY - Accepts all parameters from PanZoomOptions. Returns a PanY selection for panning a plot along the y scale only.
• PanZoom - Accepts all parameters from PanZoomOptions. Returns a PanZoom selection for panning and zooming a plot along both x and y scales.
• PanZoomX - Accepts all parameters from PanZoomOptions. Returns a PanZoomX selection for panning and zooming a plot along the x scale only.
• PanZoomY - Accepts all parameters from PanZoomOptions. Returns a PanZoomY selection for panning and zooming a plot along the y scale only.

6. Toggle

• Select individual data values by clicking / shift-clicking points.

Function Signature

app.mosaic(
	vg.interactors.toggleX(
		as_, channels, peers
	)
)

app.mosaic(
	vg.interactors.toggleY(
		as_, channels, peers
	)
)

app.mosaic(
	vg.interactors.toggleColor(
		as_, channels, peers
	)
)

Parameter	Description
as_ (Parameter)	The output selection. A clause of the form (field = value1) OR (field = value2) ... is added for the currently selected values.
peers (bool)	A flag indicating if peer (sibling) marks are affected during cross-filtering (default true). If set, peer marks will not be filtered in cross-filtering setups.
channels (Sequence[str])	The encoding channels over which to select values. Selection clauses will cover the backing data fields for each channel.

• ToggleX - Accepts all parameters from ToggleOptions. Returns a ToggleX selection to toggle individual values in the x scale domain.
• ToggleY - Accepts all parameters from ToggleOptions. Returns a ToggleY selection to toggle individual values in the y scale domain.
• ToggleColor - Accepts all parameters from ToggleOptions. Returns a ToggleColor selection to toggle individual values in the color scale domain.