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_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.
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 ¶
The values held between lower and upper, value by value:
zk.value("loss_ratio").clamp(0, 1.5). A NaN stays NaN.
pad_end ¶
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.
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).
Conditionals¶
when ¶
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.
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().
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.
to_list ¶
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.