Transforms¶

Aggregation specs, each a dict with keys field, fn, as (e.g. {"field": "price", "fn": "mean", "as": "avg_price"}).

Columns to group by.

Transform specification for the Rust engine.

If groupby is a bare string — iterating a string yields individual characters, not column names.

Column to bin.

Output column name. Defaults to "{field}_bin".

Maximum number of bins.

Explicit bin width (overrides maxbins).

Whether to "nice" the bin boundaries.

Transform specification for the Rust engine.

Name of the output column.

Expression string (e.g. "datum.x * 2 + datum.y"). Supports the same grammar as transform_filter's expression-string form (arithmetic, comparisons, ternary, literals, indexof(...)) — see the data-transforms guide's "Expression syntax" section. An expression whose overall result is an array (rather than a number, string, or boolean) raises ValueError; arrays are only valid as an indexof(...) argument, not as a column value.

Transform specification for the Rust engine.

Column to estimate density for.

KDE bandwidth. If None, estimated automatically.

Kernel function: "gaussian", "epanechnikov" (alias "epan"), "tophat" (alias "uniform"), "cosine", "exponential", or "linear". An unrecognized kernel raises a typed error from the Rust engine at render time (not validated here -- the transform functions in this module defer vocabulary checks to the single Rust-side source of truth rather than duplicating it).

Compute separate densities per group.

Domain extent for the density grid.

Number of grid steps.

If True, compute cumulative density.

Output column names.

Transform specification for the Rust engine.

If groupby is a bare string — iterating a string yields individual characters, not column names.

Vega-style expression string (e.g. "datum.x > 5"), a dict filter specification, or a Parameter (a selection or variable parameter). A Parameter predicate emits a pass-through "true" predicate plus a param marker: the static render keeps all rows while the WASM runtime crossfilters live against the linked parameter.

Expression strings support: field access (datum.field, bracket access datum["field with spaces"]), arithmetic (+ - * / %), comparison and logical operators (&& || !), ternary (cond ? a : b), string/boolean/null literals ('x', true, false, null), scientific notation (1e10), array literals ([1, 2, 3]), and one builtin call, indexof(array, value) (returns the index of the first match, or -1) — the full table lives in the data-transforms guide's "Expression syntax" section. A dict predicate's list/tuple values ({"field": [1, 2, 3]}) compile to exactly this indexof([...], datum.field) >= 0 form.

Transform specification for the Rust engine.

Column names to flatten.

Output names for flattened columns.

Transform specification for the Rust engine.

If fields or as_ is a bare string — iterating a string yields individual characters, not column names.

Column names to fold.

Output column names for the key and value columns.

Transform specification for the Rust engine.

If fields or as_ is a bare string — iterating a string yields individual characters, not column names.

Column to impute.

Imputation method: "value", "mean", "median", "min", "max".

Constant value for method="value".

Impute within groups: the fill value (per method) is computed separately for each group, not once across the whole column. A group with no non-null values of its own to compute a statistic from falls back to the whole column's statistic, rather than degrading to 0.0 or an infinite fill value (unless the column as a whole has no usable values either).

Key column. Within each group (or, with no groupby, the whole batch as one implicit group — Vega's "no groupby means one group" rule), a key value present in the key universe (see keyvals) but missing from that group gets one appended row: the group's own columns, the missing key, and that group's own imputed value; every other column is null.

The key universe. Requires key — passing keyvals without key raises ValueError at render time, since there is no key column for the universe to apply to. Must be a sequence (list, tuple, or other iterable), never a bare string — a bare string iterates into characters, not key values, and raises ValueError at construction time. When omitted, the universe is the distinct key values observed across the whole batch. Each value is typed against the key column's own dtype at render time: a whole-valued float (e.g. 1.0) coerces onto an integer key column, but a genuinely fractional float against an integer key column raises ValueError (that coercion would be lossy); a string against a numeric key column raises the same way.

Transform specification for the Rust engine.

If groupby or keyvals is a bare string — iterating a string yields individual characters, not column/key values.

Aggregation specs, each a dict with keys field, fn, as (e.g. {"field": "price", "fn": "mean", "as": "avg_price"}).

Columns to group by.

Transform specification for the Rust engine.

If groupby is a bare string — iterating a string yields individual characters, not column names.

Independent variable column.

Dependent variable column.

Smoothing bandwidth (fraction of data).

Fit separate curves per group.

Output column names.

Transform specification for the Rust engine.

If groupby is a bare string — iterating a string yields individual characters, not column names.

Column whose unique values become new column headers.

Column whose values fill the pivoted cells.

Columns to group by.

Maximum number of pivot columns to create.

Aggregation operation when multiple values map to the same cell.

Transform specification for the Rust engine.

If groupby is a bare string — iterating a string yields individual characters, not column names.

Independent variable column.

Dependent variable column.

Regression method (e.g. "linear", "poly", "exp", "log", "pow").

Polynomial order (for method="poly").

Fit separate regressions per group.

Output column names.

Transform specification for the Rust engine.

If groupby is a bare string — iterating a string yields individual characters, not column names.

Number of rows to sample.

RNG seed for deterministic sampling.

Transform specification for the Rust engine.

Field to stack.

Columns defining each stack group.

Sort order within each stack.

Output column names for stack start and end.

Offset mode: "zero", "normalize", or "center".

Transform specification for the Rust engine.

If offset is not one of "zero", "normalize", "center", or if groupby or sort is a bare string — iterating a string yields individual characters, not column names.

Datetime column.

Unit to extract: "year", "month", "day", "hour", "minute", "second", "day_of_week", "week", "quarter".

Whether to interpret timestamps as UTC.

Output column name. Defaults to "{unit}_{field}".

Transform specification for the Rust engine.

Number of top groups to keep.

Field to aggregate for ranking.

Aggregation operation: "sum", "mean", "count", "min", "max".

Sort direction: "descending" or "ascending".

Rank groups defined by these columns' distinct value tuples, aggregating op over field within each group — the top-k-per-category use case (e.g. top 3 products by revenue sum). Every row belonging to one of the top-n groups is kept; no rows or columns are synthesized. When omitted, the legacy behavior is preserved byte-identically: field's own distinct values double as the group key, so ranking degenerates to the field's raw value rather than a separate category — a documented historical quirk (F-L05-01), not the intended use case. Pass groupby= for that. An empty sequence (groupby=[]) takes the same legacy ungrouped path as omitting the parameter entirely — it is not treated as "no groups", consistent with the rest of the groupby=-accepting transform family.

Transform specification for the Rust engine.

If groupby is a bare string — iterating a string yields individual characters, not column names.

Window operation specs, each a dict with keys op, as and optionally field and param (e.g. {"op": "row_number", "as": "rank"}).

Sort fields for the window. rank and dense_rank written without a field take their ties from these columns: rows equal on every sort column draw the same rank (1, 1, 3 for rank, 1, 1, 2 for dense_rank).

Partition-by columns.

Window frame bounds: (preceding, following). None means unbounded.

Whether a rolling frame ignores peers — rows tied on every sort column. Left False (the same default setting Vega chose), a frame expands to whole peer groups, so tied rows share one frame and therefore one aggregate value. Note the peer-aware frame semantics themselves deliberately diverge from Vega's: both expand a frame's ends outward to whole peer groups, but ferrum anchors the frame on the peer run's own bounds where Vega anchors on the current row, so ferrum guarantees tied rows share one frame and one value while Vega's need not (see the guide's window-functions section for a worked example). Set True for frames defined by row offsets alone. Only rolling aggregates with an explicit frame over a tied sort key are affected.

Transform specification for the Rust engine.

If sort or groupby is a bare string — iterating a string yields individual characters, not column names.