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