Skip to content

Legend

Legend value class for legend configuration.

Ferrum — a statistical visualization library with a Rust core.

Legend dataclass

Per-channel legend configuration.

Parameters:

Name Type Description Default
title str

Legend title text. Pass title=None to suppress the legend title (the field name will not be shown). Omitting title entirely keeps the field-name default.

 _UNSET
orient str

Legend position ("right", "left", "top", "bottom", "none"). Omitting orient (or passing orient=None, treated identically — the same "unset" spelling every other optional field here accepts) keeps the renderer's own default ("right" for a side legend); passing any other value explicitly — even as "right" — always reaches the wire, so an explicit value beats a conflicting chart-level configure_legend(orient=...) (per-channel wins, D7).

 _UNSET
direction str

Layout direction ("vertical", "horizontal"). Omitting direction (or passing direction=None) keeps the renderer's per-orient default; passing any other value explicitly — even the value that default would have picked — always reaches the wire.

 _UNSET
type str

Legend type ("symbol", "gradient").

 None
tick_count int

Number of ticks for gradient legends.

 None
tick_min_step float

Minimum tick step.

 None
values list

Explicit legend values.

 None
format str

Label format string.

 None
format_type str

Format type.

 None
label_font_size float

Label font size.

 None
label_color str

Label color.

 None
label_limit float

Maximum label width.

 None
symbol_size float

Symbol size.

 None
symbol_stroke_width float

Symbol stroke width.

 None
symbol_type str

Symbol shape type.

 None
gradient_length float

Gradient legend length.

 None
gradient_thickness float

Gradient legend thickness.

 None
columns int

Number of columns for multi-column layout.

 None
column_padding float

Padding between columns.

 None
row_padding float

Padding between rows.

 None
clip_height float

Clip height for legend.

 None
title_font_size float

Title font size.

 None
title_padding float

Title padding.

 None
offset float

Offset from plot.

 None
padding float

Internal padding.

 None
zindex int

Z-index.

 None

Examples:

>>> import ferrum as fm
>>> leg = fm.Legend(title="Species", orient="top")
>>> leg.title
'Species'
>>> leg.to_dict()
{'title': 'Species', 'orient': 'top'}

to_dict 

to_dict() -> dict[str, Any]

Serialize to dict for the renderer, omitting only unset/None values.

orient and direction follow the two-way omit-vs-explicit contract :func:ferrum._title_sentinel.is_unspecified implements (distinct from title's three-way contract below): "not specified" is either omitting the kwarg (_UNSET, the field default) or passing orient=None/direction=None explicitly, and either spelling drops the key so the renderer's own orient/direction defaulting applies. Any OTHER explicitly passed value — including one that happens to equal what the renderer would have picked anyway — always reaches the wire (NF-B3/F-L04-04). Skipping an explicit-equals-default value here previously made it indistinguishable from "not specified", which silently lost the per-channel-wins cascade (D7) for that field. The same gate runs in __post_init__ (token validation) and here (serialization), so a value can never be validated-but-dropped or accepted-but-unvalidated.

format preset names are resolved to their d3-format/strftime strings via :func:ferrum.format_presets.resolve_format_field before serialization (NF-B1); an unrecognized name passes through as an honest raw spec. The resolved format_type fills the format_type field only when the caller did not set it explicitly.