ferrum.encoding¶

Bases: ChannelBase

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

Parameters:

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() -> dict

to_implicit_transforms() -> list

Bases: ChannelBase

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

Parameters:

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() -> dict

to_implicit_transforms() -> list

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:

Examples:

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

to_encoding_spec_dict() -> dict

to_implicit_transforms() -> list

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:

Examples:

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

to_encoding_spec_dict() -> dict

to_implicit_transforms() -> list

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:

Examples:

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

to_encoding_spec_dict() -> dict

to_implicit_transforms() -> list

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:

Examples:

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

to_encoding_spec_dict() -> dict

to_implicit_transforms() -> list

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:

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() -> dict

to_implicit_transforms() -> list

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:

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() -> dict

to_implicit_transforms() -> list

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:

Examples:

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

to_encoding_spec_dict() -> dict

to_implicit_transforms() -> list

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:

Examples:

>>> import ferrum as fm
>>> fm.Chart(df).encode(theta=fm.Theta("count"), radius=fm.Radius("distance"))

to_encoding_spec_dict() -> dict

to_implicit_transforms() -> list

Bases: ChannelBase

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

Parameters:

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() -> dict

to_implicit_transforms() -> list

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:

Examples:

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

to_encoding_spec_dict() -> dict

to_implicit_transforms() -> list

Bases: ChannelBase

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

Distinct from fill, which controls only the interior color.

Parameters:

Examples:

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

to_encoding_spec_dict() -> dict

to_implicit_transforms() -> list

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:

Examples:

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

to_encoding_spec_dict() -> dict

to_implicit_transforms() -> list

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:

Examples:

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

to_encoding_spec_dict() -> dict

to_implicit_transforms() -> list

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:

Examples:

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

to_encoding_spec_dict() -> dict

to_implicit_transforms() -> list

Bases: ChannelBase

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

Larger values produce thicker mark outlines.

Parameters:

Examples:

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

to_encoding_spec_dict() -> dict

to_implicit_transforms() -> list

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:

Examples:

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

to_encoding_spec_dict() -> dict

to_implicit_transforms() -> list

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:

Examples:

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

to_encoding_spec_dict() -> dict

to_implicit_transforms() -> list

Bases: ChannelBase

Shape channel — maps a categorical field to point shape.

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

Parameters:

Examples:

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

to_encoding_spec_dict() -> dict

to_implicit_transforms() -> list

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:

Examples:

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

to_encoding_spec_dict() -> dict

to_implicit_transforms() -> list

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:

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() -> dict

to_implicit_transforms() -> list

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:

Examples:

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

to_encoding_spec_dict() -> dict

to_implicit_transforms() -> list

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:

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() -> dict

to_implicit_transforms() -> list

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:

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() -> dict

to_implicit_transforms() -> list

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:

Examples:

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

to_encoding_spec_dict() -> dict

to_implicit_transforms() -> list

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:

Examples:

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

to_encoding_spec_dict() -> dict

to_implicit_transforms() -> list

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:

Examples:

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

to_encoding_spec_dict() -> dict

to_implicit_transforms() -> list

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:

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() -> dict

to_implicit_transforms() -> list

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:

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() -> dict

to_implicit_transforms() -> list

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:

Examples:

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

to_encoding_spec_dict() -> dict

to_implicit_transforms() -> list

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:

Examples:

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

to_encoding_spec_dict() -> dict

to_implicit_transforms() -> list