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:
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