Selection¶

Create an interval (brush) selection activated by dragging.

An interval selection lets the user drag a rectangular brush over the chart. All marks inside the brush are considered selected. The brush supports panning (translate=True) and scroll-to-zoom (zoom=True) after it is drawn.

Parameters:

Returns:

Examples:

Brush that greys out unselected points:

>>> import ferrum as fm
>>> brush = fm.selection_interval()
>>> fm.Chart(df).mark_point().encode(
...     x=fm.X("x"), y=fm.Y("y"),
...     color=brush.when(fm.Color("category")).otherwise(fm.value("#cccccc")),
... ).add_selection(brush)

Horizontal-only brush:

>>> brush = fm.selection_interval(encodings=["x"])

Custom brush style:

>>> brush = fm.selection_interval(
...     mark=fm.SelectionMark(fill="#4287f5", fill_opacity=0.2, stroke_dash=[4, 2])
... )

Create a point selection activated by clicking on marks.

A point selection highlights individual marks. Shift-click adds to the selection by default (toggle="event.shiftKey"). Use selection_single to disable toggle, or selection_multi to keep the shift-click default explicitly.

Parameters:

Returns:

Examples:

Highlight selected marks by colour:

>>> import ferrum as fm
>>> sel = fm.selection_point()
>>> fm.Chart(df).mark_point().encode(
...     x=fm.X("x"), y=fm.Y("y"),
...     color=sel.when(fm.Color("category")).otherwise(fm.value("#cccccc")),
... ).add_selection(sel)

Nearest-mark selection on mouse-over:

>>> sel = fm.selection_point(nearest=True, on="mouseover", clear="mouseout")

Legend-toggle selection:

>>> sel = fm.selection_point(bind="legend")

Wrap a literal value for use in conditional encodings.

Returns an opaque literal wrapper that can be passed as the if_selected or if_not argument of sel.when(...).otherwise(...) when a constant (rather than a field mapping) is needed.

Parameters:

Returns:

Examples:

Grey-out unselected marks:

>>> import ferrum as fm
>>> sel = fm.selection_point()
>>> fm.Chart(df).mark_point().encode(
...     x=fm.X("x"), y=fm.Y("y"),
...     color=sel.when(fm.Color("category")).otherwise(fm.value("#cccccc")),
... ).add_selection(sel)

Fade unselected marks with low opacity (numeric branches resolve to opacity values, not colours, so assign to the opacity channel):

>>> opacity = fm.when(sel).then(1.0).otherwise(0.1)
>>> # or, equivalently, with explicit value(...) wrappers:
>>> opacity = sel.when(fm.value(1.0)).otherwise(fm.value(0.1))

Start a module-level conditional encoding builder.

A more explicit alternative to sel.when(enc).otherwise(enc) for cases where the conditional test is on a selection parameter and the branches are literal values (opacity, colour) rather than encoding channels.

Usage::

fm.when(sel).then(v_if).otherwise(v_else)

The parameter argument must be a Selection instance — the conditional test is "datum ∈ selection". Variable parameters (fm.param) drive value/domain/bind references, not the conditional predicate; passing one raises TypeError.

v_if and v_else may be plain numbers or fm.value(...) wrappers; they are wrapped via value() when not already a _LiteralValue. Hex colour strings are interpreted as colours at serialization time (in _resolve_encoding_value), not at this layer.

Parameters:

Returns:

Raises:

Examples:

Fade unselected marks — assign the conditional to the opacity channel so the numeric branches resolve to opacity values (encode stamps the channel from its key and auto-registers sel):

>>> import ferrum as fm
>>> sel = fm.selection_point()
>>> chart = fm.Chart(df).mark_point().encode(
...     x=fm.X("x"), y=fm.Y("y"),
...     opacity=fm.when(sel).then(1.0).otherwise(0.2),
... )

Colour toggle on legend selection:

>>> sel = fm.selection_point(bind="legend")
>>> cond = fm.when(sel).then(fm.value("#1f77b4")).otherwise(fm.value("#cccccc"))