Skip to content

Expressions

Dimension expressions

dim

dim(name: str) -> DimExpr

The dim called name, as an expression: collection.filter(zk.dim("underwriting_year") == 2026). The counterpart of Dim, which declares a dim and its type - as pl.col is to pl.Column in Polars.

DimExpr

An expression over a collection's dims, from zk.dim(name): it computes a dim cell, or a condition, for every row. Compare it, combine conditions with &, | and ~ (and, or, not and x if condition else y raise TypeError), branch with zk.when(...).then(...).otherwise(...), map it with replace, and name it with alias. A condition filters a collection (Collection.filter); expressions giving str or int dim cells group one (Collection.group_by). Resolved against a collection only when used.

is_in

is_in(values: Iterable[DimCellValue]) -> DimExpr

Whether the dim cell is one of values.

is_between

is_between(
    lower: _DimOperand, upper: _DimOperand
) -> DimExpr

Whether the dim cell lies between lower and upper, both included.

replace

replace(mapping: Mapping[Any, Any]) -> DimExpr

Each dim cell replaced by its value in mapping; dim cells the mapping doesn't cover are kept, so the values must be of the same kind. replace_strict maps to another kind.

replace_strict

replace_strict(
    mapping: Mapping[Any, Any],
    default: DimCellValue | None = None,
) -> DimExpr

Each dim cell replaced by its value in mapping, which may be of another kind; a dim cell the mapping doesn't cover gives default, or raises ValueError without one.

alias

alias(name: str) -> DimExpr

The same expression, named name: the name of the dim it becomes in a group-by.

Value expressions

value

value(name: str | type[ValueColumns]) -> ValueExpr

The value column name - a str, or a column type such as zk.FloatA[Literal["gross"]], whose type the column must have - as an expression, for GroupBy.agg: total=zk.value("gross").sum(). The counterpart of zk.dim for values.

ValueExpr

An expression over a collection's value columns, from zk.value(name): combine it with arithmetic, and reduce it across each group's rows with sum, mean, min, max or count, to compute a column of a group-by's result. Arithmetic joins as Collection's does; reduce both sides of an operation, or neither.

clamp

clamp(
    lower: ValueExpr | Scalar, upper: ValueExpr | Scalar
) -> ValueExpr

The values held between lower and upper, value by value: zk.value("loss_ratio").clamp(0, 1.5). A NaN stays NaN.

pad_end

pad_end(
    length: int, fill: Scalar | None = None
) -> ValueExpr

The arrays padded at the end to length values, with fill (a scalar of their kind) or 0 by default, in with_columns: paid.with_columns(zk.value("paid").pad_end(10)). Arrays combine only at equal lengths, so this is how a shorter one combines with a longer one, explicitly - two cashflows of different terms, say. Raises ValueError when evaluated for a constant or jagged column, an array longer than length, a fill of another kind, or no fill for a kind with no zero.

sum

sum() -> ValueExpr

The sum across each group's rows, value by value.

mean

mean() -> ValueExpr

The mean across each group's rows, value by value.

min

min() -> ValueExpr

The minimum across each group's rows, value by value.

max

max() -> ValueExpr

The maximum across each group's rows, value by value.

count

count() -> ValueExpr

How many rows each group holds, as an int constant.

jagged_sum

jagged_sum() -> ValueExpr

The sum of each entry's values, for a jagged column: an array of the same length, still one per row (reduce it across rows next).

jagged_min

jagged_min() -> ValueExpr

The least of each entry's values, for a jagged column.

jagged_max

jagged_max() -> ValueExpr

The greatest of each entry's values, for a jagged column.

jagged_count

jagged_count() -> ValueExpr

How many values each entry holds, for a jagged column, as ints.

alias

alias(name: str) -> ValueExpr

The same expression, named name: the name of the column it becomes.

Conditionals

when

when(condition: Any, /, *conditions: Any) -> Any

Start an if/else: zk.when(condition).then(value), then any number of .when(condition).then(value), then .otherwise(value). Several conditions must all hold.

With dim expressions it builds a DimExpr for group_by and filter. With value expressions it builds a ValueExpr for with_columns and agg, picking value by value, the values all of one kind: zk.when(zk.value("gross") > 0).then(zk.value("gross")).otherwise(0.0).

DimWhen

A dim expression's if/else waiting for .then(value).

DimThen

A dim expression's if/else with a branch: add another with .when(condition), or finish it with .otherwise(value).

ValueWhen

A value expression's if/else waiting for .then(value).

ValueThen

A value expression's if/else with a branch: add another with .when(condition), or finish it with .otherwise(value).

Group-by

GroupBy

Bases: Generic[G, *Columns]

A collection grouped by expressions over its dims, from Collection.group_by: each expression is a dim of the result, and agg computes its columns, reducing each group's rows. G is the result's dims: NoDims when it groups by nothing, and otherwise Any, as what it groups by is expressions.

dims property

dims: list[Dim]

The dims of the result, one per expression grouped by.

agg

agg(
    *values: ValueExpr, **named_values: ValueExpr
) -> Collection[G, *tuple[Any, ...]]

The collection over the groups, with one column per value expression: named by its keyword, or else by its alias or the column it refers to. Each must reduce across the group's rows, e.g. total=zk.value("gross").sum().

sum

sum() -> Collection[G, *Columns]

Every column summed across each group's rows.

mean

mean() -> Collection[G, *Columns]

Every column's mean across each group's rows.

min

min() -> Collection[G, *Columns]

Every column's minimum across each group's rows.

max

max() -> Collection[G, *Columns]

Every column's maximum across each group's rows.

Dimension rows and jagged shapes

DimRows

Bases: Generic[D]

The dim rows of a collection - its dims and each row's dim cells - without its values: collection.dim_rows. A snapshot: it never changes, whatever is later added to the collection it came from.

dims property

dims: list[Dim]

The dims, in row order.

row_count property

row_count: int

The number of rows.

to_list

to_list() -> list[tuple[Any, ...]]

Each dim row as a tuple of its dim cells, in row order.

zeros

zeros(
    column: type[Value],
    *,
    length: int | None = None,
    jagged_shape: JaggedShape | None = None,
) -> Collection[D, Value]

A collection of zeros over these rows, in one column of type column - a float or int column type such as FloatA[Literal["name"]], which gives the column's name, kind and structure. A constant column holds one 0 per row; an array column length zeros per row (a broadcast 0, so no buffer is allocated); and a jagged column zeros shaped by jagged_shape, a jagged column's jagged_shape, so they combine with that column value by value. length is given for an array column only, and jagged_shape for a jagged column only.

JaggedShape

The shape of a jagged column, row by row: collection.jagged_shape(name). It holds the column's jagged values, not their counts, which a copula may still move until the column is collected.

length property

length: int

The number of entries in each row.

row_count property

row_count: int

The number of rows.