Building collections¶
There are two ways to build a collection:
- Column by column, from its dimension rows:
zk.Collection.of(...), thenwith_columns(...). This suits data held in a DataFrame or in dictionaries, and simulation from per-row parameters. - Row by row, with
add(...), which suits per-row logic in a loop.
Both start from a dimensions class:
Column by column¶
zk.Collection.of(dims, dim_rows) makes a collection with no value columns yet. The dimension rows
are a Polars DataFrame with a column per dimension (other columns are ignored), or a list of tuples
in dimension order.
with_columns then adds columns. zk.float calls a function once per row and makes a float column
of what it returns. Its arguments are passed to the function, with zk.dim(...) replaced by the
row's value of that dimension.
Simulating from parameters¶
Float dimensions can hold the parameters each row is simulated from:
class Parameters(zk.Dims):
class_of_business = zk.Dim(str)
underwriting_year = zk.Dim(int)
mu = zk.Dim(float)
sigma = zk.Dim(float)
parameters = pl.DataFrame(
{
"class_of_business": ["motor", "motor", "property", "property"],
"underwriting_year": [2025, 2026, 2025, 2026],
"mu": [10.0, 10.1, 9.5, 9.6],
"sigma": [0.4, 0.4, 0.8, 0.8],
}
)
rng = np.random.default_rng(2026)
gross = (
zk.Collection.of(Parameters, parameters)
.with_columns(gross=zk.float(rng.lognormal, zk.dim("mu"), zk.dim("sigma"), SIMULATIONS))
.drop_dims("mu", "sigma") # the parameters have done their job
)
The function is called once per row, in row order, so a random generator's draws are the same as
one vectorised call over the rows would give. Once the values are simulated, drop_dims removes
the parameter dimensions.
From data you already have¶
Data you already hold is read the same way, by a function keyed by the dimensions. What the function returns sets the column's shape:
| The function returns | Column |
|---|---|
| A scalar | A constant: zk.FloatC |
| A 1-D array | An array: zk.FloatA |
A (counts, values) pair of 1-D arrays |
A jagged value: zk.FloatJ. counts says how many values each entry holds, and values holds them all in turn. |
premium = {"motor": 120_000.0, "property": 80_000.0}
def large_losses(class_of_business: str) -> tuple[np.ndarray, np.ndarray]:
"""Per simulation, a Poisson count of large losses, then a Pareto severity for each."""
frequency = 0.3 if class_of_business == "motor" else 0.8
counts = rng.poisson(frequency, SIMULATIONS)
severities = 250_000.0 * (1.0 + rng.pareto(2.5, counts.sum()))
return counts, severities
dim_rows = [("motor", 2025), ("motor", 2026), ("property", 2025), ("property", 2026)]
inputs = zk.Collection.of(Business, dim_rows).with_columns(
premium=zk.float(premium.__getitem__, zk.dim("class_of_business")), # a scalar: a constant column
large=zk.float(large_losses, zk.dim("class_of_business")), # a (counts, values) pair: a jagged column
claim_count=zk.int(rng.poisson, 4.0, SIMULATIONS), # an int array column
)
zk.int works as zk.float does, for int columns.
Checking and typing: validate¶
with_columns can add any columns, so a type checker can't know what the result holds. validate
checks the collection has the dimensions and column types you name, and types it by them:
typed = inputs.validate(
Business,
zk.FloatC[Lit["premium"]],
zk.FloatJ[Lit["large"]],
zk.IntA[Lit["claim_count"]],
)
# typed: zk.Collection[Business, FloatC["premium"], FloatJ["large"], IntA["claim_count"]]
Row by row¶
zk.Collection(dims, *columns) makes an empty collection with the columns you name, and add
adds a row: its dimension values in order, then a value per column.
gross = zk.Collection(Business, zk.FloatA[Lit["gross"]])
rng = np.random.default_rng(1)
for class_of_business, underwriting_year in [("motor", 2025), ("motor", 2026), ("property", 2025)]:
gross.add(class_of_business, underwriting_year, rng.lognormal(10.0, 0.5, SIMULATIONS))
A constant column takes a scalar, an array column a 1-D NumPy array, and a jagged column a
(counts, values) pair. Values can be passed by position, or by dimension and column name:
Premium = zk.FloatC[Lit["premium"]]
Gross = zk.FloatA[Lit["gross"]]
book = zk.Collection(Business, Premium, Gross)
book.add("motor", 2025, 120_000.0, rng.lognormal(10.0, 0.5, SIMULATIONS))
book.add(
class_of_business="property", underwriting_year=2025, premium=80_000.0, gross=rng.lognormal(9.5, 0.8, SIMULATIONS)
)
Adding a dimension row the collection already has raises a ValueError.
Several columns at once¶
A zk.ValueColumns subclass declares several columns together, each named after its attribute:
class Reserves(zk.ValueColumns):
gross_ibnr = zk.ValueColumn(zk.FloatA)
net_to_gross = zk.ValueColumn(zk.FloatC)
reserves = zk.Collection(Business, Reserves)
reserves.add("motor", 2025, rng.lognormal(10.0, 0.5, SIMULATIONS), 0.8)
A ValueColumns class isn't a single column
Arithmetic needs exactly one value column on each side (see
Arithmetic). A ValueColumns class
declaring two columns still fills a single type slot, so a type checker can't tell it apart
from one column. To type a function that takes one column, bound it by the column types it may
be, such as zk.FloatC[Any] | zk.FloatA[Any], or by zk.Value.
Lineage starts at the inputs¶
Every array or jagged value you add, or that zk.float returns, becomes an input: a leaf of the
model that everything else is built from. Copulas reorder inputs, and zeki tracks which inputs each
value depends on. See Dependency and copulas.