Skip to content

Encoding

Typed encoding channels — X, Y, Color, Size, Tooltip, and more.

Ferrum — a statistical visualization library with a Rust core.

Angle

Bases: ChannelBase

Angle channel — maps a field to mark rotation in degrees.

Rotates each mark around its center point. A value of 0 is upright; values increase clockwise.

Parameters:

Name Type Description Default
field str

Column name to map to rotation angle.

 None
type_ ('Q', 'N', 'O', 'T')

Data type. Inferred from the column dtype when omitted.

 "Q"

Examples:

>>> import ferrum as fm
>>> fm.Chart(df).encode(x="x", y="y", angle=fm.Angle("direction"))

to_encoding_spec_dict 

to_encoding_spec_dict() -> dict

Return kwargs for the Rust EncodingSpec constructor / serde JSON.

Iterates this channel's own _honored_kwargs (the single source of truth) rather than a separate hard-coded key list, so a kwarg is serialized iff the channel honors it. Each honored key routes through :data:_SPEC_DICT_HANDLERS to its serializer; keys with no handler (bin/aggregate) are honored for the warn guard but consumed via :meth:to_implicit_transforms, so they contribute nothing here.

Keys are emitted in :data:_SPEC_DICT_ORDER so the dict layout is stable regardless of frozenset iteration order.

to_implicit_transforms 

to_implicit_transforms() -> list

Return a list of transform objects derived from kwargs (bin, aggregate).

Both bin and aggregate transforms are returned as pending sentinels rather than concrete Rust objects. chart.to_spec() resolves them:

  • _PendingBin: single-chart path converts to an unnamed Bin (byte-stable); layered path converts to a named Bin fan-out so it does not corrupt the shared unnamed chain.
  • _PendingAggregate: defers groupby assignment until all sibling encoding channels are known (Altair-style auto-groupby).

option 

option(name: str, default: Any = None) -> Any

Return the value of encoding option name, or default if unset.

Parameters:

Name Type Description Default
name str

The option key to look up (e.g. "sort", "axis").

 required
default Any

Value returned when name is not present. Defaults to None.

 None

Returns:

Type Description
Any

The option value, or default when the key is absent.

Color

Bases: ChannelBase

Color encoding channel — maps a field to mark color (fill and stroke).

Parameters:

Name Type Description Default
field str

Column name to map to color.

 None
type_ ('Q', 'N', 'O', 'T')

Data type: quantitative, nominal, ordinal, temporal. Inferred from the column dtype when omitted.

 "Q"
scheme str

Named categorical color scheme (e.g. "tableau10", "set1").

 required
scale Scale

Explicit scale override (e.g. ColorScale.Continuous("viridis")).

 required
title str

Legend title override. When omitted the field name is used.

 required
Notes

legend is honored: passing legend={"disabled": True}, legend=None, or legend=False suppresses the color legend in the rendered SVG. sort is honored: pass a list of strings to set the explicit domain order for the color scale. condition is accepted but reserved for future use.

Examples:

>>> import ferrum as fm
>>> fm.Chart(df).encode(x="hp", y="mpg", color=fm.Color("cyl"))
>>> fm.Chart(df).encode(x="hp", y="mpg", color=fm.Color("origin", scheme="set1"))

to_encoding_spec_dict 

to_encoding_spec_dict() -> dict

Return kwargs for the Rust EncodingSpec constructor / serde JSON.

Iterates this channel's own _honored_kwargs (the single source of truth) rather than a separate hard-coded key list, so a kwarg is serialized iff the channel honors it. Each honored key routes through :data:_SPEC_DICT_HANDLERS to its serializer; keys with no handler (bin/aggregate) are honored for the warn guard but consumed via :meth:to_implicit_transforms, so they contribute nothing here.

Keys are emitted in :data:_SPEC_DICT_ORDER so the dict layout is stable regardless of frozenset iteration order.

to_implicit_transforms 

to_implicit_transforms() -> list

Return a list of transform objects derived from kwargs (bin, aggregate).

Both bin and aggregate transforms are returned as pending sentinels rather than concrete Rust objects. chart.to_spec() resolves them:

  • _PendingBin: single-chart path converts to an unnamed Bin (byte-stable); layered path converts to a named Bin fan-out so it does not corrupt the shared unnamed chain.
  • _PendingAggregate: defers groupby assignment until all sibling encoding channels are known (Altair-style auto-groupby).

option 

option(name: str, default: Any = None) -> Any

Return the value of encoding option name, or default if unset.

Parameters:

Name Type Description Default
name str

The option key to look up (e.g. "sort", "axis").

 required
default Any

Value returned when name is not present. Defaults to None.

 None

Returns:

Type Description
Any

The option value, or default when the key is absent.

Description

Bases: ChannelBase

Accessibility description channel — maps a field to per-mark alt text.

The description text is used by screen readers and other accessibility tools to describe each individual mark.

Parameters:

Name Type Description Default
field str

Column name whose values are used as the accessibility description.

 None
type_ ('Q', 'N', 'O', 'T')

Data type. Inferred from the column dtype when omitted.

 "Q"

Examples:

>>> import ferrum as fm
>>> fm.Chart(df).encode(x="x", y="y", description=fm.Description("alt_text"))

to_encoding_spec_dict 

to_encoding_spec_dict() -> dict

Return kwargs for the Rust EncodingSpec constructor / serde JSON.

Iterates this channel's own _honored_kwargs (the single source of truth) rather than a separate hard-coded key list, so a kwarg is serialized iff the channel honors it. Each honored key routes through :data:_SPEC_DICT_HANDLERS to its serializer; keys with no handler (bin/aggregate) are honored for the warn guard but consumed via :meth:to_implicit_transforms, so they contribute nothing here.

Keys are emitted in :data:_SPEC_DICT_ORDER so the dict layout is stable regardless of frozenset iteration order.

to_implicit_transforms 

to_implicit_transforms() -> list

Return a list of transform objects derived from kwargs (bin, aggregate).

Both bin and aggregate transforms are returned as pending sentinels rather than concrete Rust objects. chart.to_spec() resolves them:

  • _PendingBin: single-chart path converts to an unnamed Bin (byte-stable); layered path converts to a named Bin fan-out so it does not corrupt the shared unnamed chain.
  • _PendingAggregate: defers groupby assignment until all sibling encoding channels are known (Altair-style auto-groupby).

option 

option(name: str, default: Any = None) -> Any

Return the value of encoding option name, or default if unset.

Parameters:

Name Type Description Default
name str

The option key to look up (e.g. "sort", "axis").

 required
default Any

Value returned when name is not present. Defaults to None.

 None

Returns:

Type Description
Any

The option value, or default when the key is absent.

Detail

Bases: ChannelBase

Detail channel — adds a field to the encoding without a visual variable.

Groups marks by the levels of the field without mapping those levels to any visual property (color, size, shape, etc.). Useful for drawing one line per group in a line chart.

Parameters:

Name Type Description Default
field str

Column name to group by.

 None
type_ ('Q', 'N', 'O', 'T')

Data type. Inferred from the column dtype when omitted.

 "Q"

Examples:

>>> import ferrum as fm
>>> fm.Chart(df).encode(x="year", y="value", detail=fm.Detail("series"))

to_encoding_spec_dict 

to_encoding_spec_dict() -> dict

Return kwargs for the Rust EncodingSpec constructor / serde JSON.

Iterates this channel's own _honored_kwargs (the single source of truth) rather than a separate hard-coded key list, so a kwarg is serialized iff the channel honors it. Each honored key routes through :data:_SPEC_DICT_HANDLERS to its serializer; keys with no handler (bin/aggregate) are honored for the warn guard but consumed via :meth:to_implicit_transforms, so they contribute nothing here.

Keys are emitted in :data:_SPEC_DICT_ORDER so the dict layout is stable regardless of frozenset iteration order.

to_implicit_transforms 

to_implicit_transforms() -> list

Return a list of transform objects derived from kwargs (bin, aggregate).

Both bin and aggregate transforms are returned as pending sentinels rather than concrete Rust objects. chart.to_spec() resolves them:

  • _PendingBin: single-chart path converts to an unnamed Bin (byte-stable); layered path converts to a named Bin fan-out so it does not corrupt the shared unnamed chain.
  • _PendingAggregate: defers groupby assignment until all sibling encoding channels are known (Altair-style auto-groupby).

option 

option(name: str, default: Any = None) -> Any

Return the value of encoding option name, or default if unset.

Parameters:

Name Type Description Default
name str

The option key to look up (e.g. "sort", "axis").

 required
default Any

Value returned when name is not present. Defaults to None.

 None

Returns:

Type Description
Any

The option value, or default when the key is absent.

Facet

Bases: ChannelBase

Facet channel — splits a chart into a grid by levels of a field.

Wraps the chart into a faceted layout where each panel shows data for one level of the facet field. Pass this channel object to Chart.encode(facet=...).

Parameters:

Name Type Description Default
field str

Column name to facet by.

 None
type_ ('Q', 'N', 'O', 'T')

Data type. Inferred from the column dtype when omitted; "N" or "O" are the most common choices.

 "Q"
title str

Facet panel title override. When omitted the field name is used.

 required
Notes

columns (number of facets per row) is accepted as a kwarg but is reserved for future use (no-op today) — it triggers a one-time deprecation warning. If you need column-wrap control today, use Chart.facet(ncols=N) directly.

Examples:

>>> import ferrum as fm
>>> fm.Chart(df).encode(x="hp", y="mpg", facet=fm.Facet("species")).mark_point()
>>> fm.Chart(df).encode(x="hp", y="mpg").mark_point().facet("species", ncols=3)

to_encoding_spec_dict 

to_encoding_spec_dict() -> dict

Return kwargs for the Rust EncodingSpec constructor / serde JSON.

Iterates this channel's own _honored_kwargs (the single source of truth) rather than a separate hard-coded key list, so a kwarg is serialized iff the channel honors it. Each honored key routes through :data:_SPEC_DICT_HANDLERS to its serializer; keys with no handler (bin/aggregate) are honored for the warn guard but consumed via :meth:to_implicit_transforms, so they contribute nothing here.

Keys are emitted in :data:_SPEC_DICT_ORDER so the dict layout is stable regardless of frozenset iteration order.

to_implicit_transforms 

to_implicit_transforms() -> list

Return a list of transform objects derived from kwargs (bin, aggregate).

Both bin and aggregate transforms are returned as pending sentinels rather than concrete Rust objects. chart.to_spec() resolves them:

  • _PendingBin: single-chart path converts to an unnamed Bin (byte-stable); layered path converts to a named Bin fan-out so it does not corrupt the shared unnamed chain.
  • _PendingAggregate: defers groupby assignment until all sibling encoding channels are known (Altair-style auto-groupby).

option 

option(name: str, default: Any = None) -> Any

Return the value of encoding option name, or default if unset.

Parameters:

Name Type Description Default
name str

The option key to look up (e.g. "sort", "axis").

 required
default Any

Value returned when name is not present. Defaults to None.

 None

Returns:

Type Description
Any

The option value, or default when the key is absent.

FacetCol

Bases: ChannelBase

Facet-column channel — splits a chart into columns by levels of a field.

Pass this channel object to Chart.encode(facet_col=...) to create a column-faceted layout where each column shows data for one level of the field.

Parameters:

Name Type Description Default
field str

Column name to facet columns by.

 None
type_ ('Q', 'N', 'O', 'T')

Data type. Inferred from the column dtype when omitted; "N" or "O" are the most common choices.

 "Q"
title str

Column-facet title override. When omitted the field name is used.

 required

Examples:

>>> import ferrum as fm
>>> fm.Chart(df).encode(x="hp", y="mpg", facet_col=fm.FacetCol("species")).mark_point()

to_encoding_spec_dict 

to_encoding_spec_dict() -> dict

Return kwargs for the Rust EncodingSpec constructor / serde JSON.

Iterates this channel's own _honored_kwargs (the single source of truth) rather than a separate hard-coded key list, so a kwarg is serialized iff the channel honors it. Each honored key routes through :data:_SPEC_DICT_HANDLERS to its serializer; keys with no handler (bin/aggregate) are honored for the warn guard but consumed via :meth:to_implicit_transforms, so they contribute nothing here.

Keys are emitted in :data:_SPEC_DICT_ORDER so the dict layout is stable regardless of frozenset iteration order.

to_implicit_transforms 

to_implicit_transforms() -> list

Return a list of transform objects derived from kwargs (bin, aggregate).

Both bin and aggregate transforms are returned as pending sentinels rather than concrete Rust objects. chart.to_spec() resolves them:

  • _PendingBin: single-chart path converts to an unnamed Bin (byte-stable); layered path converts to a named Bin fan-out so it does not corrupt the shared unnamed chain.
  • _PendingAggregate: defers groupby assignment until all sibling encoding channels are known (Altair-style auto-groupby).

option 

option(name: str, default: Any = None) -> Any

Return the value of encoding option name, or default if unset.

Parameters:

Name Type Description Default
name str

The option key to look up (e.g. "sort", "axis").

 required
default Any

Value returned when name is not present. Defaults to None.

 None

Returns:

Type Description
Any

The option value, or default when the key is absent.

FacetRow

Bases: ChannelBase

Facet-row channel — splits a chart into rows by levels of a field.

Pass this channel object to Chart.encode(facet_row=...) to create a row-faceted layout where each row shows data for one level of the field.

Parameters:

Name Type Description Default
field str

Column name to facet rows by.

 None
type_ ('Q', 'N', 'O', 'T')

Data type. Inferred from the column dtype when omitted; "N" or "O" are the most common choices.

 "Q"
title str

Row-facet title override. When omitted the field name is used.

 required

Examples:

>>> import ferrum as fm
>>> fm.Chart(df).encode(x="hp", y="mpg", facet_row=fm.FacetRow("year")).mark_point()

to_encoding_spec_dict 

to_encoding_spec_dict() -> dict

Return kwargs for the Rust EncodingSpec constructor / serde JSON.

Iterates this channel's own _honored_kwargs (the single source of truth) rather than a separate hard-coded key list, so a kwarg is serialized iff the channel honors it. Each honored key routes through :data:_SPEC_DICT_HANDLERS to its serializer; keys with no handler (bin/aggregate) are honored for the warn guard but consumed via :meth:to_implicit_transforms, so they contribute nothing here.

Keys are emitted in :data:_SPEC_DICT_ORDER so the dict layout is stable regardless of frozenset iteration order.

to_implicit_transforms 

to_implicit_transforms() -> list

Return a list of transform objects derived from kwargs (bin, aggregate).

Both bin and aggregate transforms are returned as pending sentinels rather than concrete Rust objects. chart.to_spec() resolves them:

  • _PendingBin: single-chart path converts to an unnamed Bin (byte-stable); layered path converts to a named Bin fan-out so it does not corrupt the shared unnamed chain.
  • _PendingAggregate: defers groupby assignment until all sibling encoding channels are known (Altair-style auto-groupby).

option 

option(name: str, default: Any = None) -> Any

Return the value of encoding option name, or default if unset.

Parameters:

Name Type Description Default
name str

The option key to look up (e.g. "sort", "axis").

 required
default Any

Value returned when name is not present. Defaults to None.

 None

Returns:

Type Description
Any

The option value, or default when the key is absent.

Fill

Bases: ChannelBase

Fill color channel — maps a field to filled-mark fill color.

Distinct from stroke, which controls only the outline color. When both Fill and Color are encoded, Fill takes precedence for the interior of the mark.

Parameters:

Name Type Description Default
field str

Column name to map to fill color.

 None
type_ ('Q', 'N', 'O', 'T')

Data type. Inferred from the column dtype when omitted.

 "Q"

Examples:

>>> import ferrum as fm
>>> fm.Chart(df).encode(x="hp", y="mpg", fill=fm.Fill("origin"))

to_encoding_spec_dict 

to_encoding_spec_dict() -> dict

Return kwargs for the Rust EncodingSpec constructor / serde JSON.

Iterates this channel's own _honored_kwargs (the single source of truth) rather than a separate hard-coded key list, so a kwarg is serialized iff the channel honors it. Each honored key routes through :data:_SPEC_DICT_HANDLERS to its serializer; keys with no handler (bin/aggregate) are honored for the warn guard but consumed via :meth:to_implicit_transforms, so they contribute nothing here.

Keys are emitted in :data:_SPEC_DICT_ORDER so the dict layout is stable regardless of frozenset iteration order.

to_implicit_transforms 

to_implicit_transforms() -> list

Return a list of transform objects derived from kwargs (bin, aggregate).

Both bin and aggregate transforms are returned as pending sentinels rather than concrete Rust objects. chart.to_spec() resolves them:

  • _PendingBin: single-chart path converts to an unnamed Bin (byte-stable); layered path converts to a named Bin fan-out so it does not corrupt the shared unnamed chain.
  • _PendingAggregate: defers groupby assignment until all sibling encoding channels are known (Altair-style auto-groupby).

option 

option(name: str, default: Any = None) -> Any

Return the value of encoding option name, or default if unset.

Parameters:

Name Type Description Default
name str

The option key to look up (e.g. "sort", "axis").

 required
default Any

Value returned when name is not present. Defaults to None.

 None

Returns:

Type Description
Any

The option value, or default when the key is absent.

FillOpacity

Bases: ChannelBase

Fill-opacity channel — maps a field to fill opacity.

Independent of stroke opacity; controls only how transparent the interior of a mark is. Values are mapped to the range [0, 1].

Parameters:

Name Type Description Default
field str

Column name to map to fill opacity.

 None
type_ ('Q', 'N', 'O', 'T')

Data type. Inferred from the column dtype when omitted.

 "Q"

Examples:

>>> import ferrum as fm
>>> fm.Chart(df).encode(x="hp", y="mpg", fill_opacity=fm.FillOpacity("density"))

to_encoding_spec_dict 

to_encoding_spec_dict() -> dict

Return kwargs for the Rust EncodingSpec constructor / serde JSON.

Iterates this channel's own _honored_kwargs (the single source of truth) rather than a separate hard-coded key list, so a kwarg is serialized iff the channel honors it. Each honored key routes through :data:_SPEC_DICT_HANDLERS to its serializer; keys with no handler (bin/aggregate) are honored for the warn guard but consumed via :meth:to_implicit_transforms, so they contribute nothing here.

Keys are emitted in :data:_SPEC_DICT_ORDER so the dict layout is stable regardless of frozenset iteration order.

to_implicit_transforms 

to_implicit_transforms() -> list

Return a list of transform objects derived from kwargs (bin, aggregate).

Both bin and aggregate transforms are returned as pending sentinels rather than concrete Rust objects. chart.to_spec() resolves them:

  • _PendingBin: single-chart path converts to an unnamed Bin (byte-stable); layered path converts to a named Bin fan-out so it does not corrupt the shared unnamed chain.
  • _PendingAggregate: defers groupby assignment until all sibling encoding channels are known (Altair-style auto-groupby).

option 

option(name: str, default: Any = None) -> Any

Return the value of encoding option name, or default if unset.

Parameters:

Name Type Description Default
name str

The option key to look up (e.g. "sort", "axis").

 required
default Any

Value returned when name is not present. Defaults to None.

 None

Returns:

Type Description
Any

The option value, or default when the key is absent.

Href

Bases: ChannelBase

URL-link channel — maps a field to a clickable URL.

When the chart is rendered in an interactive renderer, marks become clickable hyperlinks pointing to the URL stored in field.

Parameters:

Name Type Description Default
field str

Column name containing the URL string for each mark.

 None
type_ ('Q', 'N', 'O', 'T')

Data type. Inferred from the column dtype when omitted.

 "Q"
Notes

Interactive renderers only; SVG export does not embed hyperlinks.

Examples:

>>> import ferrum as fm
>>> fm.Chart(df).encode(x="x", y="y", href=fm.Href("url"))

to_encoding_spec_dict 

to_encoding_spec_dict() -> dict

Return kwargs for the Rust EncodingSpec constructor / serde JSON.

Iterates this channel's own _honored_kwargs (the single source of truth) rather than a separate hard-coded key list, so a kwarg is serialized iff the channel honors it. Each honored key routes through :data:_SPEC_DICT_HANDLERS to its serializer; keys with no handler (bin/aggregate) are honored for the warn guard but consumed via :meth:to_implicit_transforms, so they contribute nothing here.

Keys are emitted in :data:_SPEC_DICT_ORDER so the dict layout is stable regardless of frozenset iteration order.

to_implicit_transforms 

to_implicit_transforms() -> list

Return a list of transform objects derived from kwargs (bin, aggregate).

Both bin and aggregate transforms are returned as pending sentinels rather than concrete Rust objects. chart.to_spec() resolves them:

  • _PendingBin: single-chart path converts to an unnamed Bin (byte-stable); layered path converts to a named Bin fan-out so it does not corrupt the shared unnamed chain.
  • _PendingAggregate: defers groupby assignment until all sibling encoding channels are known (Altair-style auto-groupby).

option 

option(name: str, default: Any = None) -> Any

Return the value of encoding option name, or default if unset.

Parameters:

Name Type Description Default
name str

The option key to look up (e.g. "sort", "axis").

 required
default Any

Value returned when name is not present. Defaults to None.

 None

Returns:

Type Description
Any

The option value, or default when the key is absent.

Key

Bases: ChannelBase

Key channel — maps a field to a unique key per mark.

Provides a stable identity for each mark when joining across data updates (e.g. animated transitions or streaming data).

Parameters:

Name Type Description Default
field str

Column name whose values uniquely identify each mark.

 None
type_ ('Q', 'N', 'O', 'T')

Data type. Inferred from the column dtype when omitted.

 "Q"

Examples:

>>> import ferrum as fm
>>> fm.Chart(df).encode(x="x", y="y", key=fm.Key("id"))

to_encoding_spec_dict 

to_encoding_spec_dict() -> dict

Return kwargs for the Rust EncodingSpec constructor / serde JSON.

Iterates this channel's own _honored_kwargs (the single source of truth) rather than a separate hard-coded key list, so a kwarg is serialized iff the channel honors it. Each honored key routes through :data:_SPEC_DICT_HANDLERS to its serializer; keys with no handler (bin/aggregate) are honored for the warn guard but consumed via :meth:to_implicit_transforms, so they contribute nothing here.

Keys are emitted in :data:_SPEC_DICT_ORDER so the dict layout is stable regardless of frozenset iteration order.

to_implicit_transforms 

to_implicit_transforms() -> list

Return a list of transform objects derived from kwargs (bin, aggregate).

Both bin and aggregate transforms are returned as pending sentinels rather than concrete Rust objects. chart.to_spec() resolves them:

  • _PendingBin: single-chart path converts to an unnamed Bin (byte-stable); layered path converts to a named Bin fan-out so it does not corrupt the shared unnamed chain.
  • _PendingAggregate: defers groupby assignment until all sibling encoding channels are known (Altair-style auto-groupby).

option 

option(name: str, default: Any = None) -> Any

Return the value of encoding option name, or default if unset.

Parameters:

Name Type Description Default
name str

The option key to look up (e.g. "sort", "axis").

 required
default Any

Value returned when name is not present. Defaults to None.

 None

Returns:

Type Description
Any

The option value, or default when the key is absent.

Opacity

Bases: ChannelBase

Opacity channel — maps a field to overall mark opacity.

Controls both fill and stroke opacity simultaneously. Values are mapped to the range [0, 1].

Parameters:

Name Type Description Default
field str

Column name to map to opacity.

 None
type_ ('Q', 'N', 'O', 'T')

Data type. Inferred from the column dtype when omitted.

 "Q"
scale Scale

Explicit scale override.

 required
title str

Legend title override.

 required

Examples:

>>> import ferrum as fm
>>> fm.Chart(df).encode(x="hp", y="mpg", opacity=fm.Opacity("year"))

to_encoding_spec_dict 

to_encoding_spec_dict() -> dict

Return kwargs for the Rust EncodingSpec constructor / serde JSON.

Iterates this channel's own _honored_kwargs (the single source of truth) rather than a separate hard-coded key list, so a kwarg is serialized iff the channel honors it. Each honored key routes through :data:_SPEC_DICT_HANDLERS to its serializer; keys with no handler (bin/aggregate) are honored for the warn guard but consumed via :meth:to_implicit_transforms, so they contribute nothing here.

Keys are emitted in :data:_SPEC_DICT_ORDER so the dict layout is stable regardless of frozenset iteration order.

to_implicit_transforms 

to_implicit_transforms() -> list

Return a list of transform objects derived from kwargs (bin, aggregate).

Both bin and aggregate transforms are returned as pending sentinels rather than concrete Rust objects. chart.to_spec() resolves them:

  • _PendingBin: single-chart path converts to an unnamed Bin (byte-stable); layered path converts to a named Bin fan-out so it does not corrupt the shared unnamed chain.
  • _PendingAggregate: defers groupby assignment until all sibling encoding channels are known (Altair-style auto-groupby).

option 

option(name: str, default: Any = None) -> Any

Return the value of encoding option name, or default if unset.

Parameters:

Name Type Description Default
name str

The option key to look up (e.g. "sort", "axis").

 required
default Any

Value returned when name is not present. Defaults to None.

 None

Returns:

Type Description
Any

The option value, or default when the key is absent.

Radius

Bases: ChannelBase

Polar radius channel — maps a field to the radial position in polar coords.

Controls how far each mark is placed from the center of the polar plot.

Parameters:

Name Type Description Default
field str

Column name in the input DataFrame.

 None
type_ ('Q', 'N', 'O', 'T')

Data type. Inferred from the column dtype when omitted.

 "Q"
stack bool or str

Stacking behaviour for radial bars (wind-rose / coxcomb charts). True or "zero" accumulates segments outward from the origin; "normalize" produces percentage rings; "center" produces a symmetric streamgraph-style layout. False or None disables stacking. Requires mark_bar under CoordPolar.

 required
Notes

Requires CoordPolar() on the chart to activate polar rendering; without it the channel is registered but the mark renders in Cartesian space.

When stack is set, the radius channel is remapped to y (the value axis) before reaching Rust's apply_stack; bar.rs build_polar then reads __stack_y_base__ as the inner radius so each segment starts where the previous one ended. Pass position=fm.Stack() on mark_bar() as an alternative.

Examples:

>>> import ferrum as fm
>>> fm.Chart(df).encode(theta=fm.Theta("count"), radius=fm.Radius("distance"))
>>> # Stacked wind-rose / coxcomb:
>>> fm.Chart(df).encode(
...     theta=fm.Theta("direction"),
...     radius=fm.Radius("speed", stack=True),
...     color="category:N",
... ).coord(fm.CoordPolar(theta="x"))

to_encoding_spec_dict 

to_encoding_spec_dict() -> dict

Return kwargs for the Rust EncodingSpec constructor / serde JSON.

Iterates this channel's own _honored_kwargs (the single source of truth) rather than a separate hard-coded key list, so a kwarg is serialized iff the channel honors it. Each honored key routes through :data:_SPEC_DICT_HANDLERS to its serializer; keys with no handler (bin/aggregate) are honored for the warn guard but consumed via :meth:to_implicit_transforms, so they contribute nothing here.

Keys are emitted in :data:_SPEC_DICT_ORDER so the dict layout is stable regardless of frozenset iteration order.

to_implicit_transforms 

to_implicit_transforms() -> list

Return a list of transform objects derived from kwargs (bin, aggregate).

Both bin and aggregate transforms are returned as pending sentinels rather than concrete Rust objects. chart.to_spec() resolves them:

  • _PendingBin: single-chart path converts to an unnamed Bin (byte-stable); layered path converts to a named Bin fan-out so it does not corrupt the shared unnamed chain.
  • _PendingAggregate: defers groupby assignment until all sibling encoding channels are known (Altair-style auto-groupby).

option 

option(name: str, default: Any = None) -> Any

Return the value of encoding option name, or default if unset.

Parameters:

Name Type Description Default
name str

The option key to look up (e.g. "sort", "axis").

 required
default Any

Value returned when name is not present. Defaults to None.

 None

Returns:

Type Description
Any

The option value, or default when the key is absent.

Radius2

Bases: ChannelBase

Polar second-extent radius channel — maps a field to the outer radial boundary.

Used with Radius to define an explicit inner/outer radial span for each arc segment (annular wedge marks). When both radius and radius2 are encoded, the arc spans from the radius column value (inner boundary) to the radius2 column value (outer boundary) per row.

Parameters:

Name Type Description Default
field str

Column name in the input DataFrame.

 None
type_ ('Q', 'N', 'O', 'T')

Data type. Inferred from the column dtype when omitted.

 "Q"
Notes

Requires CoordPolar() on the chart to activate polar rendering. Remapped to y2 (when CoordPolar(theta="x")) or x2 (when CoordPolar(theta="y")) before the spec reaches Rust.

Examples:

>>> import ferrum as fm
>>> fm.Chart(df).encode(
...     theta=fm.Theta("t_start"),
...     theta2=fm.Theta2("t_end"),
...     radius=fm.Radius("r_inner"),
...     radius2=fm.Radius2("r_outer"),
... )

to_encoding_spec_dict 

to_encoding_spec_dict() -> dict

Return kwargs for the Rust EncodingSpec constructor / serde JSON.

Iterates this channel's own _honored_kwargs (the single source of truth) rather than a separate hard-coded key list, so a kwarg is serialized iff the channel honors it. Each honored key routes through :data:_SPEC_DICT_HANDLERS to its serializer; keys with no handler (bin/aggregate) are honored for the warn guard but consumed via :meth:to_implicit_transforms, so they contribute nothing here.

Keys are emitted in :data:_SPEC_DICT_ORDER so the dict layout is stable regardless of frozenset iteration order.

to_implicit_transforms 

to_implicit_transforms() -> list

Return a list of transform objects derived from kwargs (bin, aggregate).

Both bin and aggregate transforms are returned as pending sentinels rather than concrete Rust objects. chart.to_spec() resolves them:

  • _PendingBin: single-chart path converts to an unnamed Bin (byte-stable); layered path converts to a named Bin fan-out so it does not corrupt the shared unnamed chain.
  • _PendingAggregate: defers groupby assignment until all sibling encoding channels are known (Altair-style auto-groupby).

option 

option(name: str, default: Any = None) -> Any

Return the value of encoding option name, or default if unset.

Parameters:

Name Type Description Default
name str

The option key to look up (e.g. "sort", "axis").

 required
default Any

Value returned when name is not present. Defaults to None.

 None

Returns:

Type Description
Any

The option value, or default when the key is absent.

Shape

Bases: ChannelBase

Shape channel — maps a categorical field to point shape.

Supported shapes include "circle", "square", "triangle", "cross", "diamond", and "star".

Parameters:

Name Type Description Default
field str

Column name (should be nominal or ordinal) to map to shape.

 None
type_ ('Q', 'N', 'O', 'T')

Data type. Inferred from the column dtype when omitted; "N" is the most common choice.

 "Q"
scale Scale

Explicit scale override.

 required
title str

Legend title override.

 required
Notes

legend is honored: passing legend=None or legend=False suppresses the shape legend in the rendered SVG. legend=Legend(title=..., format=...) customizes the legend title. When legend is omitted, a categorical shape legend is rendered automatically showing one glyph per distinct category value. sort is honored: pass "ascending", "descending", a list of strings for an explicit domain order, or a channel shorthand such as "-y" to sort by the per-category aggregate of another channel. condition is accepted but reserved for future use.

Examples:

>>> import ferrum as fm
>>> fm.Chart(df).encode(x="hp", y="mpg", shape=fm.Shape("origin", type_="N"))
>>> fm.Chart(df).encode(x="hp", y="mpg", shape=fm.Shape("origin", sort="descending"))
>>> fm.Chart(df).encode(x="hp", y="mpg", shape=fm.Shape("origin", legend=None))

to_encoding_spec_dict 

to_encoding_spec_dict() -> dict

Return kwargs for the Rust EncodingSpec constructor / serde JSON.

Iterates this channel's own _honored_kwargs (the single source of truth) rather than a separate hard-coded key list, so a kwarg is serialized iff the channel honors it. Each honored key routes through :data:_SPEC_DICT_HANDLERS to its serializer; keys with no handler (bin/aggregate) are honored for the warn guard but consumed via :meth:to_implicit_transforms, so they contribute nothing here.

Keys are emitted in :data:_SPEC_DICT_ORDER so the dict layout is stable regardless of frozenset iteration order.

to_implicit_transforms 

to_implicit_transforms() -> list

Return a list of transform objects derived from kwargs (bin, aggregate).

Both bin and aggregate transforms are returned as pending sentinels rather than concrete Rust objects. chart.to_spec() resolves them:

  • _PendingBin: single-chart path converts to an unnamed Bin (byte-stable); layered path converts to a named Bin fan-out so it does not corrupt the shared unnamed chain.
  • _PendingAggregate: defers groupby assignment until all sibling encoding channels are known (Altair-style auto-groupby).

option 

option(name: str, default: Any = None) -> Any

Return the value of encoding option name, or default if unset.

Parameters:

Name Type Description Default
name str

The option key to look up (e.g. "sort", "axis").

 required
default Any

Value returned when name is not present. Defaults to None.

 None

Returns:

Type Description
Any

The option value, or default when the key is absent.

Size

Bases: ChannelBase

Size channel — maps a field to mark size (point area in square pixels).

For point marks the size value corresponds to the area of the mark in square pixels.

Parameters:

Name Type Description Default
field str

Column name to map to size.

 None
type_ ('Q', 'N', 'O', 'T')

Data type. Inferred from the column dtype when omitted.

 "Q"
scale Scale

Explicit scale override.

 required
title str

Legend title override.

 required
Notes

legend is honored: passing legend=None or legend=False suppresses the size legend in the rendered SVG. legend=Legend(title=..., format=...) customizes the legend title and numeric format string. When legend is omitted, a graduated size legend is rendered automatically showing ~5 round representative values from the field's domain. condition is accepted but reserved for future use.

When size and color are both mapped to the same field, ferrum merges them into a single combined legend block.

Examples:

>>> import ferrum as fm
>>> fm.Chart(df).encode(x="hp", y="mpg", size=fm.Size("weight"))
>>> fm.Chart(df).encode(x="hp", y="mpg", size=fm.Size("pop", legend=None))

to_encoding_spec_dict 

to_encoding_spec_dict() -> dict

Return kwargs for the Rust EncodingSpec constructor / serde JSON.

Iterates this channel's own _honored_kwargs (the single source of truth) rather than a separate hard-coded key list, so a kwarg is serialized iff the channel honors it. Each honored key routes through :data:_SPEC_DICT_HANDLERS to its serializer; keys with no handler (bin/aggregate) are honored for the warn guard but consumed via :meth:to_implicit_transforms, so they contribute nothing here.

Keys are emitted in :data:_SPEC_DICT_ORDER so the dict layout is stable regardless of frozenset iteration order.

to_implicit_transforms 

to_implicit_transforms() -> list

Return a list of transform objects derived from kwargs (bin, aggregate).

Both bin and aggregate transforms are returned as pending sentinels rather than concrete Rust objects. chart.to_spec() resolves them:

  • _PendingBin: single-chart path converts to an unnamed Bin (byte-stable); layered path converts to a named Bin fan-out so it does not corrupt the shared unnamed chain.
  • _PendingAggregate: defers groupby assignment until all sibling encoding channels are known (Altair-style auto-groupby).

option 

option(name: str, default: Any = None) -> Any

Return the value of encoding option name, or default if unset.

Parameters:

Name Type Description Default
name str

The option key to look up (e.g. "sort", "axis").

 required
default Any

Value returned when name is not present. Defaults to None.

 None

Returns:

Type Description
Any

The option value, or default when the key is absent.

Stroke

Bases: ChannelBase

Stroke color channel — maps a field to mark stroke (outline) color.

Distinct from fill, which controls only the interior color.

Parameters:

Name Type Description Default
field str

Column name to map to stroke color.

 None
type_ ('Q', 'N', 'O', 'T')

Data type. Inferred from the column dtype when omitted.

 "Q"

Examples:

>>> import ferrum as fm
>>> fm.Chart(df).encode(x="hp", y="mpg", stroke=fm.Stroke("origin"))

to_encoding_spec_dict 

to_encoding_spec_dict() -> dict

Return kwargs for the Rust EncodingSpec constructor / serde JSON.

Iterates this channel's own _honored_kwargs (the single source of truth) rather than a separate hard-coded key list, so a kwarg is serialized iff the channel honors it. Each honored key routes through :data:_SPEC_DICT_HANDLERS to its serializer; keys with no handler (bin/aggregate) are honored for the warn guard but consumed via :meth:to_implicit_transforms, so they contribute nothing here.

Keys are emitted in :data:_SPEC_DICT_ORDER so the dict layout is stable regardless of frozenset iteration order.

to_implicit_transforms 

to_implicit_transforms() -> list

Return a list of transform objects derived from kwargs (bin, aggregate).

Both bin and aggregate transforms are returned as pending sentinels rather than concrete Rust objects. chart.to_spec() resolves them:

  • _PendingBin: single-chart path converts to an unnamed Bin (byte-stable); layered path converts to a named Bin fan-out so it does not corrupt the shared unnamed chain.
  • _PendingAggregate: defers groupby assignment until all sibling encoding channels are known (Altair-style auto-groupby).

option 

option(name: str, default: Any = None) -> Any

Return the value of encoding option name, or default if unset.

Parameters:

Name Type Description Default
name str

The option key to look up (e.g. "sort", "axis").

 required
default Any

Value returned when name is not present. Defaults to None.

 None

Returns:

Type Description
Any

The option value, or default when the key is absent.

StrokeDash

Bases: ChannelBase

Stroke-dash channel — maps a field to a dash pattern.

Each level of the field maps to a distinct dash-gap pattern for the mark stroke (e.g. solid, dashed, dotted).

Parameters:

Name Type Description Default
field str

Column name (typically nominal or ordinal) to map to dash pattern.

 None
type_ ('Q', 'N', 'O', 'T')

Data type. Inferred from the column dtype when omitted.

 "Q"

Examples:

>>> import ferrum as fm
>>> fm.Chart(df).encode(x="x", y="y", stroke_dash=fm.StrokeDash("group", type_="N"))

to_encoding_spec_dict 

to_encoding_spec_dict() -> dict

Return kwargs for the Rust EncodingSpec constructor / serde JSON.

Iterates this channel's own _honored_kwargs (the single source of truth) rather than a separate hard-coded key list, so a kwarg is serialized iff the channel honors it. Each honored key routes through :data:_SPEC_DICT_HANDLERS to its serializer; keys with no handler (bin/aggregate) are honored for the warn guard but consumed via :meth:to_implicit_transforms, so they contribute nothing here.

Keys are emitted in :data:_SPEC_DICT_ORDER so the dict layout is stable regardless of frozenset iteration order.

to_implicit_transforms 

to_implicit_transforms() -> list

Return a list of transform objects derived from kwargs (bin, aggregate).

Both bin and aggregate transforms are returned as pending sentinels rather than concrete Rust objects. chart.to_spec() resolves them:

  • _PendingBin: single-chart path converts to an unnamed Bin (byte-stable); layered path converts to a named Bin fan-out so it does not corrupt the shared unnamed chain.
  • _PendingAggregate: defers groupby assignment until all sibling encoding channels are known (Altair-style auto-groupby).

option 

option(name: str, default: Any = None) -> Any

Return the value of encoding option name, or default if unset.

Parameters:

Name Type Description Default
name str

The option key to look up (e.g. "sort", "axis").

 required
default Any

Value returned when name is not present. Defaults to None.

 None

Returns:

Type Description
Any

The option value, or default when the key is absent.

StrokeOpacity

Bases: ChannelBase

Stroke-opacity channel — maps a field to stroke opacity.

Independent of fill opacity; controls only how transparent the outline of a mark is. Values are mapped to the range [0, 1].

Parameters:

Name Type Description Default
field str

Column name to map to stroke opacity.

 None
type_ ('Q', 'N', 'O', 'T')

Data type. Inferred from the column dtype when omitted.

 "Q"

Examples:

>>> import ferrum as fm
>>> fm.Chart(df).encode(x="hp", y="mpg", stroke_opacity=fm.StrokeOpacity("year"))

to_encoding_spec_dict 

to_encoding_spec_dict() -> dict

Return kwargs for the Rust EncodingSpec constructor / serde JSON.

Iterates this channel's own _honored_kwargs (the single source of truth) rather than a separate hard-coded key list, so a kwarg is serialized iff the channel honors it. Each honored key routes through :data:_SPEC_DICT_HANDLERS to its serializer; keys with no handler (bin/aggregate) are honored for the warn guard but consumed via :meth:to_implicit_transforms, so they contribute nothing here.

Keys are emitted in :data:_SPEC_DICT_ORDER so the dict layout is stable regardless of frozenset iteration order.

to_implicit_transforms 

to_implicit_transforms() -> list

Return a list of transform objects derived from kwargs (bin, aggregate).

Both bin and aggregate transforms are returned as pending sentinels rather than concrete Rust objects. chart.to_spec() resolves them:

  • _PendingBin: single-chart path converts to an unnamed Bin (byte-stable); layered path converts to a named Bin fan-out so it does not corrupt the shared unnamed chain.
  • _PendingAggregate: defers groupby assignment until all sibling encoding channels are known (Altair-style auto-groupby).

option 

option(name: str, default: Any = None) -> Any

Return the value of encoding option name, or default if unset.

Parameters:

Name Type Description Default
name str

The option key to look up (e.g. "sort", "axis").

 required
default Any

Value returned when name is not present. Defaults to None.

 None

Returns:

Type Description
Any

The option value, or default when the key is absent.

StrokeWidth

Bases: ChannelBase

Stroke-width channel — maps a field to stroke width in pixels.

Larger values produce thicker mark outlines.

Parameters:

Name Type Description Default
field str

Column name to map to stroke width.

 None
type_ ('Q', 'N', 'O', 'T')

Data type. Inferred from the column dtype when omitted.

 "Q"

Examples:

>>> import ferrum as fm
>>> fm.Chart(df).encode(x="x", y="y", stroke_width=fm.StrokeWidth("importance"))

to_encoding_spec_dict 

to_encoding_spec_dict() -> dict

Return kwargs for the Rust EncodingSpec constructor / serde JSON.

Iterates this channel's own _honored_kwargs (the single source of truth) rather than a separate hard-coded key list, so a kwarg is serialized iff the channel honors it. Each honored key routes through :data:_SPEC_DICT_HANDLERS to its serializer; keys with no handler (bin/aggregate) are honored for the warn guard but consumed via :meth:to_implicit_transforms, so they contribute nothing here.

Keys are emitted in :data:_SPEC_DICT_ORDER so the dict layout is stable regardless of frozenset iteration order.

to_implicit_transforms 

to_implicit_transforms() -> list

Return a list of transform objects derived from kwargs (bin, aggregate).

Both bin and aggregate transforms are returned as pending sentinels rather than concrete Rust objects. chart.to_spec() resolves them:

  • _PendingBin: single-chart path converts to an unnamed Bin (byte-stable); layered path converts to a named Bin fan-out so it does not corrupt the shared unnamed chain.
  • _PendingAggregate: defers groupby assignment until all sibling encoding channels are known (Altair-style auto-groupby).

option 

option(name: str, default: Any = None) -> Any

Return the value of encoding option name, or default if unset.

Parameters:

Name Type Description Default
name str

The option key to look up (e.g. "sort", "axis").

 required
default Any

Value returned when name is not present. Defaults to None.

 None

Returns:

Type Description
Any

The option value, or default when the key is absent.

Text

Bases: ChannelBase

Text channel — maps a field to text-mark content.

Renders each data point's field value as a text label. Primarily used with the mark_text mark.

Parameters:

Name Type Description Default
field str

Column name whose values are rendered as text.

 None
type_ ('Q', 'N', 'O', 'T')

Data type. Inferred from the column dtype when omitted.

 "Q"
format str

Number or date format string (e.g. ".2f" for two decimal places, "%b %Y" for abbreviated month and year).

 required
format_type str

Format type hint; "number" or "time". Used in combination with format. formatType is accepted as a Vega-compat alias and normalizes to the same wire key.

 required

Examples:

>>> import ferrum as fm
>>> fm.Chart(df).encode(x="x", y="y", text=fm.Text("label"))
>>> fm.Chart(df).encode(x="x", y="y", text=fm.Text("value", format=".1f"))

to_encoding_spec_dict 

to_encoding_spec_dict() -> dict

Return kwargs for the Rust EncodingSpec constructor / serde JSON.

Iterates this channel's own _honored_kwargs (the single source of truth) rather than a separate hard-coded key list, so a kwarg is serialized iff the channel honors it. Each honored key routes through :data:_SPEC_DICT_HANDLERS to its serializer; keys with no handler (bin/aggregate) are honored for the warn guard but consumed via :meth:to_implicit_transforms, so they contribute nothing here.

Keys are emitted in :data:_SPEC_DICT_ORDER so the dict layout is stable regardless of frozenset iteration order.

to_implicit_transforms 

to_implicit_transforms() -> list

Return a list of transform objects derived from kwargs (bin, aggregate).

Both bin and aggregate transforms are returned as pending sentinels rather than concrete Rust objects. chart.to_spec() resolves them:

  • _PendingBin: single-chart path converts to an unnamed Bin (byte-stable); layered path converts to a named Bin fan-out so it does not corrupt the shared unnamed chain.
  • _PendingAggregate: defers groupby assignment until all sibling encoding channels are known (Altair-style auto-groupby).

option 

option(name: str, default: Any = None) -> Any

Return the value of encoding option name, or default if unset.

Parameters:

Name Type Description Default
name str

The option key to look up (e.g. "sort", "axis").

 required
default Any

Value returned when name is not present. Defaults to None.

 None

Returns:

Type Description
Any

The option value, or default when the key is absent.

Theta

Bases: ChannelBase

Polar angle channel — maps a field to the angular position in polar coords.

Typically used with arc or pie marks; the field values determine the sweep angle of each arc segment.

Parameters:

Name Type Description Default
field str

Column name in the input DataFrame.

 None
type_ ('Q', 'N', 'O', 'T')

Data type. Inferred from the column dtype when omitted.

 "Q"
stack bool or str

Stacking behaviour for arc segments. True enables stacking; False disables it; "normalize" produces percentage arcs.

 required
Notes

Requires CoordPolar() on the chart to activate polar rendering; without it the channel is registered but the mark renders in Cartesian space.

Examples:

>>> import ferrum as fm
>>> fm.Chart(df).encode(theta=fm.Theta("count", stack=True))

to_encoding_spec_dict 

to_encoding_spec_dict() -> dict

Return kwargs for the Rust EncodingSpec constructor / serde JSON.

Iterates this channel's own _honored_kwargs (the single source of truth) rather than a separate hard-coded key list, so a kwarg is serialized iff the channel honors it. Each honored key routes through :data:_SPEC_DICT_HANDLERS to its serializer; keys with no handler (bin/aggregate) are honored for the warn guard but consumed via :meth:to_implicit_transforms, so they contribute nothing here.

Keys are emitted in :data:_SPEC_DICT_ORDER so the dict layout is stable regardless of frozenset iteration order.

to_implicit_transforms 

to_implicit_transforms() -> list

Return a list of transform objects derived from kwargs (bin, aggregate).

Both bin and aggregate transforms are returned as pending sentinels rather than concrete Rust objects. chart.to_spec() resolves them:

  • _PendingBin: single-chart path converts to an unnamed Bin (byte-stable); layered path converts to a named Bin fan-out so it does not corrupt the shared unnamed chain.
  • _PendingAggregate: defers groupby assignment until all sibling encoding channels are known (Altair-style auto-groupby).

option 

option(name: str, default: Any = None) -> Any

Return the value of encoding option name, or default if unset.

Parameters:

Name Type Description Default
name str

The option key to look up (e.g. "sort", "axis").

 required
default Any

Value returned when name is not present. Defaults to None.

 None

Returns:

Type Description
Any

The option value, or default when the key is absent.

Theta2

Bases: ChannelBase

Polar second-extent angle channel — maps a field to the angular end position.

Used with Theta to define an explicit angular span for each arc segment (annular wedge marks). When both theta and theta2 are encoded, the arc sweeps from the theta value to the theta2 value directly from data, rather than computing a proportional sweep from column sums.

Parameters:

Name Type Description Default
field str

Column name in the input DataFrame.

 None
type_ ('Q', 'N', 'O', 'T')

Data type. Inferred from the column dtype when omitted.

 "Q"
Notes

Requires CoordPolar() on the chart to activate polar rendering. Remapped to x2 (when CoordPolar(theta="x")) or y2 (when CoordPolar(theta="y")) before the spec reaches Rust.

Examples:

>>> import ferrum as fm
>>> fm.Chart(df).encode(
...     theta=fm.Theta("t_start"),
...     theta2=fm.Theta2("t_end"),
...     radius=fm.Radius("r_inner"),
...     radius2=fm.Radius2("r_outer"),
... )

to_encoding_spec_dict 

to_encoding_spec_dict() -> dict

Return kwargs for the Rust EncodingSpec constructor / serde JSON.

Iterates this channel's own _honored_kwargs (the single source of truth) rather than a separate hard-coded key list, so a kwarg is serialized iff the channel honors it. Each honored key routes through :data:_SPEC_DICT_HANDLERS to its serializer; keys with no handler (bin/aggregate) are honored for the warn guard but consumed via :meth:to_implicit_transforms, so they contribute nothing here.

Keys are emitted in :data:_SPEC_DICT_ORDER so the dict layout is stable regardless of frozenset iteration order.

to_implicit_transforms 

to_implicit_transforms() -> list

Return a list of transform objects derived from kwargs (bin, aggregate).

Both bin and aggregate transforms are returned as pending sentinels rather than concrete Rust objects. chart.to_spec() resolves them:

  • _PendingBin: single-chart path converts to an unnamed Bin (byte-stable); layered path converts to a named Bin fan-out so it does not corrupt the shared unnamed chain.
  • _PendingAggregate: defers groupby assignment until all sibling encoding channels are known (Altair-style auto-groupby).

option 

option(name: str, default: Any = None) -> Any

Return the value of encoding option name, or default if unset.

Parameters:

Name Type Description Default
name str

The option key to look up (e.g. "sort", "axis").

 required
default Any

Value returned when name is not present. Defaults to None.

 None

Returns:

Type Description
Any

The option value, or default when the key is absent.

Tooltip

Bases: ChannelBase

Tooltip channel — specifies which fields appear in the hover tooltip.

Accepts one or more field names (as strings or TooltipField helpers) that are shown when the viewer hovers over a mark in an interactive renderer.

Parameters:

Name Type Description Default
*fields str or TooltipField

One or more column names or TooltipField(...) instances to include in the tooltip. Passing a single string is equivalent to Tooltip(TooltipField(field)).

 ()

Examples:

>>> import ferrum as fm
>>> fm.Chart(df).encode(x="hp", y="mpg",
...     tooltip=fm.Tooltip("hp", "mpg"))
>>> fm.Chart(df).encode(x="hp", y="mpg",
...     tooltip=fm.Tooltip("hp", fm.TooltipField("cyl", title="Cylinders")))

to_encoding_spec_dict 

to_encoding_spec_dict() -> dict

Return kwargs for the Rust EncodingSpec constructor / serde JSON.

Iterates this channel's own _honored_kwargs (the single source of truth) rather than a separate hard-coded key list, so a kwarg is serialized iff the channel honors it. Each honored key routes through :data:_SPEC_DICT_HANDLERS to its serializer; keys with no handler (bin/aggregate) are honored for the warn guard but consumed via :meth:to_implicit_transforms, so they contribute nothing here.

Keys are emitted in :data:_SPEC_DICT_ORDER so the dict layout is stable regardless of frozenset iteration order.

to_implicit_transforms 

to_implicit_transforms() -> list

Return a list of transform objects derived from kwargs (bin, aggregate).

Both bin and aggregate transforms are returned as pending sentinels rather than concrete Rust objects. chart.to_spec() resolves them:

  • _PendingBin: single-chart path converts to an unnamed Bin (byte-stable); layered path converts to a named Bin fan-out so it does not corrupt the shared unnamed chain.
  • _PendingAggregate: defers groupby assignment until all sibling encoding channels are known (Altair-style auto-groupby).

option 

option(name: str, default: Any = None) -> Any

Return the value of encoding option name, or default if unset.

Parameters:

Name Type Description Default
name str

The option key to look up (e.g. "sort", "axis").

 required
default Any

Value returned when name is not present. Defaults to None.

 None

Returns:

Type Description
Any

The option value, or default when the key is absent.

TooltipField

Bases: ChannelBase

Helper for an individual tooltip field with optional title and format.

Used inside Tooltip(*fields) to customise how a single column is displayed in the hover tooltip. Not used as a top-level encoding channel.

Parameters:

Name Type Description Default
field str

Column name.

 None
type_ ('Q', 'N', 'O', 'T')

Data type. Inferred from the column dtype when omitted.

 "Q"
title str

Custom tooltip label for this field.

 required
format str

Number or date format string (e.g. ".1f", "%Y-%m-%d").

 required
format_type str

Format type hint; "number" or "time". formatType is accepted as a Vega-compat alias and normalizes to the same wire key.

 required

Examples:

>>> import ferrum as fm
>>> fm.Chart(df).encode(x="hp", y="mpg",
...     tooltip=fm.Tooltip("hp", fm.TooltipField("mpg", title="MPG", format=".1f")))

to_encoding_spec_dict 

to_encoding_spec_dict() -> dict

Return kwargs for the Rust EncodingSpec constructor / serde JSON.

Iterates this channel's own _honored_kwargs (the single source of truth) rather than a separate hard-coded key list, so a kwarg is serialized iff the channel honors it. Each honored key routes through :data:_SPEC_DICT_HANDLERS to its serializer; keys with no handler (bin/aggregate) are honored for the warn guard but consumed via :meth:to_implicit_transforms, so they contribute nothing here.

Keys are emitted in :data:_SPEC_DICT_ORDER so the dict layout is stable regardless of frozenset iteration order.

to_implicit_transforms 

to_implicit_transforms() -> list

Return a list of transform objects derived from kwargs (bin, aggregate).

Both bin and aggregate transforms are returned as pending sentinels rather than concrete Rust objects. chart.to_spec() resolves them:

  • _PendingBin: single-chart path converts to an unnamed Bin (byte-stable); layered path converts to a named Bin fan-out so it does not corrupt the shared unnamed chain.
  • _PendingAggregate: defers groupby assignment until all sibling encoding channels are known (Altair-style auto-groupby).

option 

option(name: str, default: Any = None) -> Any

Return the value of encoding option name, or default if unset.

Parameters:

Name Type Description Default
name str

The option key to look up (e.g. "sort", "axis").

 required
default Any

Value returned when name is not present. Defaults to None.

 None

Returns:

Type Description
Any

The option value, or default when the key is absent.

Url

Bases: ChannelBase

Image URL channel — maps a field to a base64 data URL for mark_image tiles.

Each row provides a data:image/...;base64,<payload> URL that is placed as an image tile at the position given by the x and y encodings. Used exclusively with :meth:~ferrum.Chart.mark_image.

Parameters:

Name Type Description Default
field str

Column name containing the base64 data URL for each tile.

 None
type_ ('Q', 'N', 'O', 'T')

Data type. Inferred from the column dtype when omitted (typically "N" for string columns).

 "Q"

Examples:

>>> import ferrum as fm
>>> fm.Chart(df).mark_image().encode(x="x:Q", y="y:Q", url=fm.Url("data_url"))

to_encoding_spec_dict 

to_encoding_spec_dict() -> dict

Return kwargs for the Rust EncodingSpec constructor / serde JSON.

Iterates this channel's own _honored_kwargs (the single source of truth) rather than a separate hard-coded key list, so a kwarg is serialized iff the channel honors it. Each honored key routes through :data:_SPEC_DICT_HANDLERS to its serializer; keys with no handler (bin/aggregate) are honored for the warn guard but consumed via :meth:to_implicit_transforms, so they contribute nothing here.

Keys are emitted in :data:_SPEC_DICT_ORDER so the dict layout is stable regardless of frozenset iteration order.

to_implicit_transforms 

to_implicit_transforms() -> list

Return a list of transform objects derived from kwargs (bin, aggregate).

Both bin and aggregate transforms are returned as pending sentinels rather than concrete Rust objects. chart.to_spec() resolves them:

  • _PendingBin: single-chart path converts to an unnamed Bin (byte-stable); layered path converts to a named Bin fan-out so it does not corrupt the shared unnamed chain.
  • _PendingAggregate: defers groupby assignment until all sibling encoding channels are known (Altair-style auto-groupby).

option 

option(name: str, default: Any = None) -> Any

Return the value of encoding option name, or default if unset.

Parameters:

Name Type Description Default
name str

The option key to look up (e.g. "sort", "axis").

 required
default Any

Value returned when name is not present. Defaults to None.

 None

Returns:

Type Description
Any

The option value, or default when the key is absent.

X

Bases: ChannelBase

Positional X channel — maps a field to the horizontal axis.

Parameters:

Name Type Description Default
field str

Column name in the input DataFrame.

 None
type_ ('Q', 'N', 'O', 'T')

Data type: quantitative, nominal, ordinal, temporal. Inferred from the column dtype when omitted.

 "Q"
bin bool or Bin

If truthy, bin the field before mapping. Pass a Bin(...) instance to control bin width or count; True uses automatic binning.

 required
aggregate str

Aggregation operation applied before mapping (e.g. "mean", "sum", "count").

 required
scale Scale

Explicit scale override (e.g. LogScale(), LinearScale()).

 required
title str

Axis title override. When omitted the field name is used.

 required

Examples:

>>> import ferrum as fm
>>> fm.Chart(df).encode(x=fm.X("hp", type_="Q"))
>>> fm.Chart(df).encode(x=fm.X("hp", bin=True))
>>> fm.Chart(df).encode(x=fm.X("hp", aggregate="mean"))

to_encoding_spec_dict 

to_encoding_spec_dict() -> dict

Return kwargs for the Rust EncodingSpec constructor / serde JSON.

Iterates this channel's own _honored_kwargs (the single source of truth) rather than a separate hard-coded key list, so a kwarg is serialized iff the channel honors it. Each honored key routes through :data:_SPEC_DICT_HANDLERS to its serializer; keys with no handler (bin/aggregate) are honored for the warn guard but consumed via :meth:to_implicit_transforms, so they contribute nothing here.

Keys are emitted in :data:_SPEC_DICT_ORDER so the dict layout is stable regardless of frozenset iteration order.

to_implicit_transforms 

to_implicit_transforms() -> list

Return a list of transform objects derived from kwargs (bin, aggregate).

Both bin and aggregate transforms are returned as pending sentinels rather than concrete Rust objects. chart.to_spec() resolves them:

  • _PendingBin: single-chart path converts to an unnamed Bin (byte-stable); layered path converts to a named Bin fan-out so it does not corrupt the shared unnamed chain.
  • _PendingAggregate: defers groupby assignment until all sibling encoding channels are known (Altair-style auto-groupby).

option 

option(name: str, default: Any = None) -> Any

Return the value of encoding option name, or default if unset.

Parameters:

Name Type Description Default
name str

The option key to look up (e.g. "sort", "axis").

 required
default Any

Value returned when name is not present. Defaults to None.

 None

Returns:

Type Description
Any

The option value, or default when the key is absent.

X2

Bases: ChannelBase

Secondary X channel — maps a field to the second x position.

Used for ranged marks (rule, rect, ribbon) where a mark spans from x to x2 along the horizontal axis.

Parameters:

Name Type Description Default
field str

Column name in the input DataFrame.

 None
type_ ('Q', 'N', 'O', 'T')

Data type. Inferred from the column dtype when omitted.

 "Q"

Examples:

>>> import ferrum as fm
>>> fm.Chart(df).encode(x=fm.X("start"), x2=fm.X2("end"))

to_encoding_spec_dict 

to_encoding_spec_dict() -> dict

Return kwargs for the Rust EncodingSpec constructor / serde JSON.

Iterates this channel's own _honored_kwargs (the single source of truth) rather than a separate hard-coded key list, so a kwarg is serialized iff the channel honors it. Each honored key routes through :data:_SPEC_DICT_HANDLERS to its serializer; keys with no handler (bin/aggregate) are honored for the warn guard but consumed via :meth:to_implicit_transforms, so they contribute nothing here.

Keys are emitted in :data:_SPEC_DICT_ORDER so the dict layout is stable regardless of frozenset iteration order.

to_implicit_transforms 

to_implicit_transforms() -> list

Return a list of transform objects derived from kwargs (bin, aggregate).

Both bin and aggregate transforms are returned as pending sentinels rather than concrete Rust objects. chart.to_spec() resolves them:

  • _PendingBin: single-chart path converts to an unnamed Bin (byte-stable); layered path converts to a named Bin fan-out so it does not corrupt the shared unnamed chain.
  • _PendingAggregate: defers groupby assignment until all sibling encoding channels are known (Altair-style auto-groupby).

option 

option(name: str, default: Any = None) -> Any

Return the value of encoding option name, or default if unset.

Parameters:

Name Type Description Default
name str

The option key to look up (e.g. "sort", "axis").

 required
default Any

Value returned when name is not present. Defaults to None.

 None

Returns:

Type Description
Any

The option value, or default when the key is absent.

XError

Bases: ChannelBase

X-axis error channel — maps a field to symmetric error around x.

The error bar extends x ± x_error along the horizontal axis.

Parameters:

Name Type Description Default
field str

Column name whose values are the error magnitude.

 None
type_ ('Q', 'N', 'O', 'T')

Data type. Inferred from the column dtype when omitted.

 "Q"

Examples:

>>> import ferrum as fm
>>> fm.Chart(df).encode(x="mean_hp", x_error=fm.XError("ci_hp"))

to_encoding_spec_dict 

to_encoding_spec_dict() -> dict

Return kwargs for the Rust EncodingSpec constructor / serde JSON.

Iterates this channel's own _honored_kwargs (the single source of truth) rather than a separate hard-coded key list, so a kwarg is serialized iff the channel honors it. Each honored key routes through :data:_SPEC_DICT_HANDLERS to its serializer; keys with no handler (bin/aggregate) are honored for the warn guard but consumed via :meth:to_implicit_transforms, so they contribute nothing here.

Keys are emitted in :data:_SPEC_DICT_ORDER so the dict layout is stable regardless of frozenset iteration order.

to_implicit_transforms 

to_implicit_transforms() -> list

Return a list of transform objects derived from kwargs (bin, aggregate).

Both bin and aggregate transforms are returned as pending sentinels rather than concrete Rust objects. chart.to_spec() resolves them:

  • _PendingBin: single-chart path converts to an unnamed Bin (byte-stable); layered path converts to a named Bin fan-out so it does not corrupt the shared unnamed chain.
  • _PendingAggregate: defers groupby assignment until all sibling encoding channels are known (Altair-style auto-groupby).

option 

option(name: str, default: Any = None) -> Any

Return the value of encoding option name, or default if unset.

Parameters:

Name Type Description Default
name str

The option key to look up (e.g. "sort", "axis").

 required
default Any

Value returned when name is not present. Defaults to None.

 None

Returns:

Type Description
Any

The option value, or default when the key is absent.

XError2

Bases: ChannelBase

Secondary x-axis error channel — for asymmetric error bounds.

When paired with XError, sets the upper bound of the error bar independently of the lower bound, enabling asymmetric error bars.

Parameters:

Name Type Description Default
field str

Column name whose values are the upper-side error magnitude.

 None
type_ ('Q', 'N', 'O', 'T')

Data type. Inferred from the column dtype when omitted.

 "Q"

Examples:

>>> import ferrum as fm
>>> fm.Chart(df).encode(
...     x="mean_hp",
...     x_error=fm.XError("err_low"),
...     x_error2=fm.XError2("err_high"),
... )

to_encoding_spec_dict 

to_encoding_spec_dict() -> dict

Return kwargs for the Rust EncodingSpec constructor / serde JSON.

Iterates this channel's own _honored_kwargs (the single source of truth) rather than a separate hard-coded key list, so a kwarg is serialized iff the channel honors it. Each honored key routes through :data:_SPEC_DICT_HANDLERS to its serializer; keys with no handler (bin/aggregate) are honored for the warn guard but consumed via :meth:to_implicit_transforms, so they contribute nothing here.

Keys are emitted in :data:_SPEC_DICT_ORDER so the dict layout is stable regardless of frozenset iteration order.

to_implicit_transforms 

to_implicit_transforms() -> list

Return a list of transform objects derived from kwargs (bin, aggregate).

Both bin and aggregate transforms are returned as pending sentinels rather than concrete Rust objects. chart.to_spec() resolves them:

  • _PendingBin: single-chart path converts to an unnamed Bin (byte-stable); layered path converts to a named Bin fan-out so it does not corrupt the shared unnamed chain.
  • _PendingAggregate: defers groupby assignment until all sibling encoding channels are known (Altair-style auto-groupby).

option 

option(name: str, default: Any = None) -> Any

Return the value of encoding option name, or default if unset.

Parameters:

Name Type Description Default
name str

The option key to look up (e.g. "sort", "axis").

 required
default Any

Value returned when name is not present. Defaults to None.

 None

Returns:

Type Description
Any

The option value, or default when the key is absent.

Y

Bases: ChannelBase

Positional Y channel — maps a field to the vertical axis.

Parameters:

Name Type Description Default
field str

Column name in the input DataFrame.

 None
type_ ('Q', 'N', 'O', 'T')

Data type: quantitative, nominal, ordinal, temporal. Inferred from the column dtype when omitted.

 "Q"
bin bool or Bin

If truthy, bin the field before mapping. Pass a Bin(...) instance to control bin width or count; True uses automatic binning.

 required
aggregate str

Aggregation operation applied before mapping (e.g. "mean", "sum", "count").

 required
scale Scale

Explicit scale override (e.g. LogScale(), LinearScale()).

 required
title str

Axis title override. When omitted the field name is used.

 required

Examples:

>>> import ferrum as fm
>>> fm.Chart(df).encode(y=fm.Y("mpg", type_="Q"))
>>> fm.Chart(df).encode(y=fm.Y("mpg", aggregate="mean"))

to_encoding_spec_dict 

to_encoding_spec_dict() -> dict

Return kwargs for the Rust EncodingSpec constructor / serde JSON.

Iterates this channel's own _honored_kwargs (the single source of truth) rather than a separate hard-coded key list, so a kwarg is serialized iff the channel honors it. Each honored key routes through :data:_SPEC_DICT_HANDLERS to its serializer; keys with no handler (bin/aggregate) are honored for the warn guard but consumed via :meth:to_implicit_transforms, so they contribute nothing here.

Keys are emitted in :data:_SPEC_DICT_ORDER so the dict layout is stable regardless of frozenset iteration order.

to_implicit_transforms 

to_implicit_transforms() -> list

Return a list of transform objects derived from kwargs (bin, aggregate).

Both bin and aggregate transforms are returned as pending sentinels rather than concrete Rust objects. chart.to_spec() resolves them:

  • _PendingBin: single-chart path converts to an unnamed Bin (byte-stable); layered path converts to a named Bin fan-out so it does not corrupt the shared unnamed chain.
  • _PendingAggregate: defers groupby assignment until all sibling encoding channels are known (Altair-style auto-groupby).

option 

option(name: str, default: Any = None) -> Any

Return the value of encoding option name, or default if unset.

Parameters:

Name Type Description Default
name str

The option key to look up (e.g. "sort", "axis").

 required
default Any

Value returned when name is not present. Defaults to None.

 None

Returns:

Type Description
Any

The option value, or default when the key is absent.

Y2

Bases: ChannelBase

Secondary Y channel — maps a field to the second y position.

Used for ranged marks (rule, rect, ribbon) where a mark spans from y to y2 along the vertical axis.

Parameters:

Name Type Description Default
field str

Column name in the input DataFrame.

 None
type_ ('Q', 'N', 'O', 'T')

Data type. Inferred from the column dtype when omitted.

 "Q"

Examples:

>>> import ferrum as fm
>>> fm.Chart(df).encode(y=fm.Y("low"), y2=fm.Y2("high"))

to_encoding_spec_dict 

to_encoding_spec_dict() -> dict

Return kwargs for the Rust EncodingSpec constructor / serde JSON.

Iterates this channel's own _honored_kwargs (the single source of truth) rather than a separate hard-coded key list, so a kwarg is serialized iff the channel honors it. Each honored key routes through :data:_SPEC_DICT_HANDLERS to its serializer; keys with no handler (bin/aggregate) are honored for the warn guard but consumed via :meth:to_implicit_transforms, so they contribute nothing here.

Keys are emitted in :data:_SPEC_DICT_ORDER so the dict layout is stable regardless of frozenset iteration order.

to_implicit_transforms 

to_implicit_transforms() -> list

Return a list of transform objects derived from kwargs (bin, aggregate).

Both bin and aggregate transforms are returned as pending sentinels rather than concrete Rust objects. chart.to_spec() resolves them:

  • _PendingBin: single-chart path converts to an unnamed Bin (byte-stable); layered path converts to a named Bin fan-out so it does not corrupt the shared unnamed chain.
  • _PendingAggregate: defers groupby assignment until all sibling encoding channels are known (Altair-style auto-groupby).

option 

option(name: str, default: Any = None) -> Any

Return the value of encoding option name, or default if unset.

Parameters:

Name Type Description Default
name str

The option key to look up (e.g. "sort", "axis").

 required
default Any

Value returned when name is not present. Defaults to None.

 None

Returns:

Type Description
Any

The option value, or default when the key is absent.

YError

Bases: ChannelBase

Y-axis error channel — maps a field to symmetric error around y.

The error bar extends y ± y_error along the vertical axis.

Parameters:

Name Type Description Default
field str

Column name whose values are the error magnitude.

 None
type_ ('Q', 'N', 'O', 'T')

Data type. Inferred from the column dtype when omitted.

 "Q"

Examples:

>>> import ferrum as fm
>>> fm.Chart(df).encode(y="mean_mpg", y_error=fm.YError("ci_mpg"))

to_encoding_spec_dict 

to_encoding_spec_dict() -> dict

Return kwargs for the Rust EncodingSpec constructor / serde JSON.

Iterates this channel's own _honored_kwargs (the single source of truth) rather than a separate hard-coded key list, so a kwarg is serialized iff the channel honors it. Each honored key routes through :data:_SPEC_DICT_HANDLERS to its serializer; keys with no handler (bin/aggregate) are honored for the warn guard but consumed via :meth:to_implicit_transforms, so they contribute nothing here.

Keys are emitted in :data:_SPEC_DICT_ORDER so the dict layout is stable regardless of frozenset iteration order.

to_implicit_transforms 

to_implicit_transforms() -> list

Return a list of transform objects derived from kwargs (bin, aggregate).

Both bin and aggregate transforms are returned as pending sentinels rather than concrete Rust objects. chart.to_spec() resolves them:

  • _PendingBin: single-chart path converts to an unnamed Bin (byte-stable); layered path converts to a named Bin fan-out so it does not corrupt the shared unnamed chain.
  • _PendingAggregate: defers groupby assignment until all sibling encoding channels are known (Altair-style auto-groupby).

option 

option(name: str, default: Any = None) -> Any

Return the value of encoding option name, or default if unset.

Parameters:

Name Type Description Default
name str

The option key to look up (e.g. "sort", "axis").

 required
default Any

Value returned when name is not present. Defaults to None.

 None

Returns:

Type Description
Any

The option value, or default when the key is absent.

YError2

Bases: ChannelBase

Secondary y-axis error channel — for asymmetric error bounds.

When paired with YError, sets the upper bound of the error bar independently of the lower bound, enabling asymmetric error bars.

Parameters:

Name Type Description Default
field str

Column name whose values are the upper-side error magnitude.

 None
type_ ('Q', 'N', 'O', 'T')

Data type. Inferred from the column dtype when omitted.

 "Q"

Examples:

>>> import ferrum as fm
>>> fm.Chart(df).encode(
...     y="mean_mpg",
...     y_error=fm.YError("err_low"),
...     y_error2=fm.YError2("err_high"),
... )

to_encoding_spec_dict 

to_encoding_spec_dict() -> dict

Return kwargs for the Rust EncodingSpec constructor / serde JSON.

Iterates this channel's own _honored_kwargs (the single source of truth) rather than a separate hard-coded key list, so a kwarg is serialized iff the channel honors it. Each honored key routes through :data:_SPEC_DICT_HANDLERS to its serializer; keys with no handler (bin/aggregate) are honored for the warn guard but consumed via :meth:to_implicit_transforms, so they contribute nothing here.

Keys are emitted in :data:_SPEC_DICT_ORDER so the dict layout is stable regardless of frozenset iteration order.

to_implicit_transforms 

to_implicit_transforms() -> list

Return a list of transform objects derived from kwargs (bin, aggregate).

Both bin and aggregate transforms are returned as pending sentinels rather than concrete Rust objects. chart.to_spec() resolves them:

  • _PendingBin: single-chart path converts to an unnamed Bin (byte-stable); layered path converts to a named Bin fan-out so it does not corrupt the shared unnamed chain.
  • _PendingAggregate: defers groupby assignment until all sibling encoding channels are known (Altair-style auto-groupby).

option 

option(name: str, default: Any = None) -> Any

Return the value of encoding option name, or default if unset.

Parameters:

Name Type Description Default
name str

The option key to look up (e.g. "sort", "axis").

 required
default Any

Value returned when name is not present. Defaults to None.

 None

Returns:

Type Description
Any

The option value, or default when the key is absent.