Skip to content

Building collections

There are two ways to build a collection:

  • Column by column, from its dimension rows: zk.Collection.of(...), then with_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:

class Business(zk.Dims):
    class_of_business = zk.Dim(str)
    underwriting_year = zk.Dim(int)

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.