Skip to content

Collections

zeki has two core objects: values and collections. A value holds a constant, an array or a jagged value. A collection groups values into a table, much like a DataFrame, except that a cell can hold a whole array of simulations.

Underwriting Year Class of Business Gross Premium Gross IBNR Gross Large Loss
2025 Casualty 100000 [1029, 3928, ...] [[29438, 23], [], ...]
2026 Casualty 200000 [46292, 19383, ...] [[], [3939], ...]
2025 Property 300000 [27489, 1292, ...] [[], [], ...]
2026 Property 400000 [0, 2833, ...] [[1928], [384, 192], ...]

This collection has two dimension columns, Underwriting Year (int) and Class of Business (string), and three value columns: Gross Premium (a float constant), Gross IBNR (a float array) and Gross Large Loss (a float jagged value).

A zk.Collection holds dimension rows and lazy value cells; collect() gives a zk.Collected holding the values.

Names for the parts

Term Means
Dimensions, dimension columns The columns that identify a row, such as class of business and year.
Values, value columns The columns holding the data: constants, arrays or jagged values.
Row One row of the table, made of a dimension row and a value row.
Cell One (row, column) element: a dimension cell or a value cell.
Row count How many rows a collection has: len(collection).
Length How many simulations (or entries) a value cell holds. See Lengths.

Each dimension row appears once: a collection never has two rows with the same dimension values. Rows are kept sorted by the dimensions, in order.

Schemas

A collection's type names its dimensions and value columns:

from typing import Literal as Lit

import zeki as zk


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


Book = zk.Collection[Business, zk.FloatC[Lit["premium"]], zk.FloatA[Lit["gross_ibnr"]]]

A dimension's values are strings, integers or floats: zk.Dim(str), zk.Dim(int) or zk.Dim(float). One collection can mix value columns of any kind, shape and length. The value types are described in Value types.

zk.dim(...), with a lower-case d, is the counterpart of zk.Dim: it refers to a dimension by name in an expression, as Polars' pl.col refers to a column. zk.value(...) does the same for value columns.

Compared with commercial capital modelling tools

If you've used one of the currently available commercial capital modelling products, collections extend the structure you'll know in three ways:

  1. No tree structure. A collection is a table of values, with no hierarchy or order among its dimensions. Combining two collections lines their rows up by the dimensions they share, so you never need to reorder a collection's dimensions to operate on it alongside another. See Combining collections.
  2. Any mix of types. In commercial products, a variable typically has a single type, so related values of different types, such as a string label and a simulated amount, have to be kept in separate variables, relying on the modeller to know that the same row in each corresponds. A zeki collection holds whatever mix of value columns you need, row by row.
  3. Integer dimensions hold any integers. Where integer dimensions are allowed at all, they're often restricted to positions 0, 1, 2, 3 and so on. In zeki, dimensions are strings, integers or floats (zk.Dim(str), zk.Dim(int), zk.Dim(float)), and an integer dimension holds any integers, such as underwriting years.