Skip to content

Combining collections

Alignment is strict

An operation between two collections lines their rows up by the dimensions they share. Every dimension row on one side must have a match on the other: if one side has a row the other lacks, zeki raises a ValueError. Nothing is dropped, and nothing is filled in, without you asking.

extend_default adds the missing rows explicitly. It takes another collection, its dim_rows, or a list of dimension rows:

home = zk.Collection(Business, Gross)
home.add("motor", 2025, rng.lognormal(10.0, 0.5, 1_000))
home.add("home", 2025, rng.lognormal(9.0, 0.5, 1_000))

with pytest.raises(ValueError):
    gross + home  # each side has dim rows the other lacks

total = gross.extend_default(home) + home.extend_default(gross)  # missing rows read as 0

Each new cell holds its kind's default, as a constant, an array, or a jagged value of empty entries: 0 for floats and ints, False for bools, datetime.date.min for dates and "" for strings. Override them with float_default, int_default, bool_default, date_default or string_default:

labels = labels.extend_default(gross, string_default="unknown")

Filter

filter keeps the rows whose dimensions meet every condition. zk.dim(name) refers to a dimension, and conditions combine with &, | and ~, as Polars expressions do. Several conditions passed to filter must all hold:

recent = reserves.filter(zk.dim("underwriting_year") >= 2025)
motor_and_home = reserves.filter(
    zk.dim("class_of_business").is_in(["motor", "home"]),
    zk.dim("underwriting_year").is_between(2024, 2025),
)

A dimension expression can be compared (==, <, .is_between, .is_in), combined (&, |, ~), computed on (+, -, *, and // for int dimensions), and mapped with .replace({...}). .replace_strict({...}, default=...) can change its kind, such as mapping classes to segments.

Group-by

group_by takes expressions over the dimensions, each of which becomes a dimension of the result. agg then defines the value columns, by keyword, from value expressions reduced across each group's rows. Every other dimension is reduced away.

year = zk.dim("underwriting_year")
by_class = reserves.group_by(
    zk.dim("class_of_business"),
    zk.when(year < 2025).then(year).otherwise(2025).alias("year_group"),  # 2025 onwards as one group
).agg(
    total_reserves=zk.value("gross_reserves").sum(),
    loss_ratio=zk.value("gross_reserves").sum() / zk.value("premium").sum(),
    rows=zk.value("premium").count(),
)

A grouping dimension is named after the dimension it refers to, or by .alias(...). Value expressions reduce with .sum(), .mean(), .min(), .max() or .count(). To reduce every column the same way, use group_by(...).sum(), .mean(), .min() or .max() directly.

A dimension expression can map dimensions on the way:

segment = zk.dim("class_of_business").replace_strict(
    {"home": "personal", "motor": "personal", "property": "commercial"}
)
by_segment = gross.group_by(segment.alias("segment")).sum()

Reducing every row

sum(), mean(), min() and max() on a collection reduce across all its rows, the same as grouping by nothing. The result has no dimensions (its type is zk.Collection[zk.NoDims, ...]) and a single row. It combines with any collection, as a scalar would:

total = gross.sum()  # one row, no dims: zk.Collection[zk.NoDims, ...]
share = gross / total  # each row's share of the total, keeping gross's dims

Reducing an empty collection raises a ValueError, rather than guessing what an empty total should be.

Note

collection.min() and collection.max() reduce across rows. For the elementwise minimum or maximum of two collections, use zk.min(a, b) and zk.max(a, b). See Maths functions.

Concatenate

zk.concat combines several collections into one, keeping the first one's dimensions and column order. Horizontally (the default, unlike Polars) it puts their value columns side by side, over the same dimension rows. Vertically it stacks their rows, over the same dimensions and value columns.

Premium = zk.FloatC[Lit["premium"]]
Gross = zk.FloatA[Lit["gross"]]

premium_2025 = zk.Collection(Business, Premium)
premium_2025.add("motor", 2025, 120_000.0)
premium_2026 = zk.Collection(Business, Premium)
premium_2026.add("motor", 2026, 125_000.0)
gross = zk.Collection(Business, Gross)
gross.add("motor", 2025, rng.lognormal(10.0, 0.5, 1_000))
gross.add("motor", 2026, rng.lognormal(10.0, 0.5, 1_000))

premium = zk.concat([premium_2025, premium_2026], how="vertical")  # rows stacked
both = zk.concat([premium, gross])  # premium's columns, then gross's, over the same rows