Skip to content

Render Config

RenderConfig for auto-raster, scale, and output tuning.

Ferrum — a statistical visualization library with a Rust core.

RenderConfig dataclass

Per-chart rendering configuration.

Controls the auto-raster policy that transparently substitutes mark_raster for per-element marks when the mark count exceeds raster_threshold. This prevents multi-million-row charts from producing impractically large SVG output.

For one-off overrides, prefer the raster= keyword on output methods (chart.show(raster=False), chart.save(..., raster=False), chart.to_svg(raster=False)). Use RenderConfig when you want to bake the policy into the chart object itself.

Parameters:

Name Type Description Default
raster_threshold int or None

Mark count above which auto-raster fires. None disables auto-raster entirely.

 500_000
raster_behavior ('warn', 'silent', 'error')

"warn" emits a UserWarning when auto-raster substitutes. "silent" substitutes without warning. "error" raises ValueError instead of substituting.

 "warn"
raster_aggregate ('count', 'density', 'mean', 'sum', 'any')

Aggregation function for the substituted mark_raster. "mean" and "sum" require raster_field to also be set, since they aggregate a value column rather than counting rows. Any other value (e.g. "max"/"min"/"median", which are not valid raster aggregates) raises ValueError at construction.

 "count"
raster_scheme str or None

Colormap (color scheme) for the substituted mark_raster. None defers to the built-in "viridis" default.

 None
raster_cmap str or None

Back-compat alias for raster_scheme. Pass at most one of the two; after construction it reads back as the resolved raster_scheme.

 None
raster_field str or None

Column name to aggregate when raster_aggregate is "mean" or "sum". Not required for "count", "density", and "any" -- and genuinely ignored for them: it is dropped before the substitution, so it is never resolved as a column name and an unrelated or nonexistent value here has no effect and never raises. The column must be Float64-typed; an integer or other non-Float64 column raises stat_raster: column '...' must be Float64 at render time (a pre-existing constraint of the underlying Raster transform, not new to this field).

 None