Skip to content

Parameters

Reactive parameters — param, Parameter, VariableParameter.

Ferrum — a statistical visualization library with a Rust core.

Parameter

Base class for all ferrum reactive parameters.

Both VariableParameter and Selection are subtypes. isinstance(x, Parameter) is the canonical discriminator used at reference sites (e.g. scale domain, transform filter, conditional encoding) to detect that a value is a parameter reference rather than a literal.

Subclasses must implement to_param_spec_dict(). The base raises NotImplementedError only as an unreachable guard — every concrete type (VariableParameter, Selection) provides its own override.

Attributes:

Name Type Description
name str

Stable identifier used across the chart spec to link parameters to their reference sites.

Examples:

>>> import ferrum as fm
>>> p = fm.param("threshold", value=50)
>>> isinstance(p, fm.Parameter)
True
>>> p.ref()
{'param': 'threshold'}

ref 

ref() -> dict

Return the reference marker dict used at parameter reference sites.

Returns:

Type Description
dict

{"param": self.name} — consumed by scale.domain, filter predicates, and conditional value sites.

Examples:

>>> import ferrum as fm
>>> fm.param("brush").ref()
{'param': 'brush'}

to_param_spec_dict 

to_param_spec_dict() -> dict

Serialize to the wire dict emitted into the params spec array.

Subclasses must override this. This base implementation is an unreachable guard — concrete types (VariableParameter, Selection) each supply their own implementation.

Returns:

Type Description
dict

Entry in the top-level params spec array. Shape varies by subtype; see VariableParameter.to_param_spec_dict and Selection.to_param_spec_dict for the concrete shapes.

Raises:

Type Description
NotImplementedError

Always (guard for subclasses that forget to override).

VariableParameter dataclass

Bases: Parameter

A named scalar or array parameter with an optional initial value.

Created via fm.param(). Do not construct directly.

Attributes:

Name Type Description
name str

Stable parameter identifier.
value Any, default None

Static initial value (serialized into the spec as the starting state for the WASM runtime and the static renderer). None is a valid initial value — the key is always emitted.
bind str, dict, or None, default None

Optional bind target. "legend" connects the parameter to a legend widget. A dict specifies a full Vega-Lite-style input binding (e.g. {"input": "range", "min": 0, "max": 100}). When None the "bind" key is omitted from the wire dict.

Examples:

>>> import ferrum as fm
>>> p = fm.param("threshold", value=50)
>>> p.to_param_spec_dict()
{'name': 'threshold', 'kind': 'variable', 'value': 50}

>>> fm.param("t", value=0, bind="legend").to_param_spec_dict()
{'name': 't', 'kind': 'variable', 'value': 0, 'bind': 'legend'}

ref 

ref() -> dict

Return the reference marker dict used at parameter reference sites.

Returns:

Type Description
dict

{"param": self.name} — consumed by scale.domain, filter predicates, and conditional value sites.

Examples:

>>> import ferrum as fm
>>> fm.param("brush").ref()
{'param': 'brush'}

to_param_spec_dict 

to_param_spec_dict() -> dict

Serialize to the params-array wire dict.

"bind" is omitted when None to avoid emitting null clutter in the spec JSON. "value" is always emitted (it is the static initial value and may legitimately be None).

Returns:

Type Description
dict

Wire shape::

{"name": str, "kind": "variable", "value": Any}
{"name": str, "kind": "variable", "value": Any, "bind": str | dict}

Examples:

>>> import ferrum as fm
>>> fm.param("x", value=10).to_param_spec_dict()
{'name': 'x', 'kind': 'variable', 'value': 10}

param 

param(name: str, value: Any = None, bind: Any = None) -> VariableParameter

Construct a named variable parameter.

A VariableParameter declares a named, mutable scalar or array parameter that can be referenced at scale domains, filter predicates, and conditional encoding values. At static render time the initial value is used; in interactive WASM exports the parameter is driven by its bind widget or by a linked selection.

Parameters:

Name Type Description Default
name str

Stable identifier for the parameter. Must be unique within the chart. Used in ref() markers at reference sites and in the emitted params spec array.

 required
value Any

Static initial value. Serialized as the starting state for both the static renderer and the WASM runtime. None is a valid choice; the key is always emitted.

 None
bind str, dict, or None

Optional bind target controlling how the parameter is driven at runtime.

  • None (default) — no binding; parameter is static unless updated programmatically.
  • "legend" — binds the parameter to legend-entry click interactions.
  • dict — full input-binding spec (e.g. {"input": "range", "min": 0, "max": 100, "step": 1}).
 None

Returns:

Type Description
VariableParameter

Frozen, immutable parameter descriptor. Pass to Chart.add_param() (coming in a later sub-task) and reference via p.ref() at scale domain or conditional sites.

Examples:

Static threshold parameter:

>>> import ferrum as fm
>>> thresh = fm.param("threshold", value=50)
>>> thresh.to_param_spec_dict()
{'name': 'threshold', 'kind': 'variable', 'value': 50}

Range-slider binding:

>>> slider = fm.param(
...     "k",
...     value=3,
...     bind={"input": "range", "min": 1, "max": 20, "step": 1},
... )

Legend bind:

>>> legend_param = fm.param("series", bind="legend")