Example model¶
The example model is a small but complete insurance capital model built on zeki, driven by an Excel workbook of inputs. It shows how the parts of zeki fit together at the scale of a real model: around 1,600 lines of Python, evaluating 100,000 simulations in about 15 seconds.
What it models¶
Amounts are in thousands of dollars. Results are profits, and capital is the expected result less the 1-in-200 result.
| Component | How | zeki |
|---|---|---|
| Reserve risk, 1993 to 2026 | Gross IBNR, lognormal per class and underwriting year, with the workbook's mean and coefficient of variation. Net is gross times the net-to-gross ratio. | A collection of every reserve value, built row by row |
| Dependency | Gaussian copulas: class correlations within each underwriting year, then year-difference correlations between the years' totals | Nested copulas |
| Underwriting risk, 2027 and 2028 | Attritional losses lognormal (loss ratio times premium); large losses Poisson frequency and Pareto severity, event by event | zk.float from per-row parameter dimensions, with large losses as a jagged column |
| Outwards reinsurance | Class and aggregate excess-of-loss layers, applied in order, per occurrence, with reinstatements, aggregate deductibles and limits | Collection operations on the jagged large losses |
| Results and earnings | Net result by class and year, earned by calendar year with the earnings pattern | Broadcasting a collection against the earnings pattern |
| Cashflows | Claims paid by calendar year with the paid pattern | One graph of around 90,000 operations |
| Capital | Ultimate and one-year views, allocated to classes by co-TVaR | Statistics on the collected results |
How it's organised¶
Each part of the model is a module of functions taking and returning typed collections:
| Module | Holds |
|---|---|
dimensions |
The zk.Dims classes the model is indexed by: class and underwriting year; class, underwriting year and calendar year; calendar year; layer and underwriting year |
inputs |
One class of inputs per workbook tab, read into Polars DataFrames |
reserve |
Reserve risk, returning one collection of gross and net IBNR and best estimates |
dependency |
The reserve copulas |
underwriting |
Premium, attritional losses and large losses |
reinsurance |
Recoveries, net events, reinstatement premium and reinsurance cost, by class and by layer |
earnings |
Spreading an amount over the calendar years it earns in |
reporting |
Tail statistics, capital allocation and the output tables |
Every collection is annotated with its type, such as
zk.Collection[ClassUnderwritingYear, zk.FloatA[Literal["gross_ibnr"]]], so the type checker
follows the columns through the whole model, and flags a function given the wrong one.
Patterns worth copying¶
- One collection per concern. Reserve risk returns a single collection holding the best
estimates and simulated IBNR, gross and net, and later modules pick out the column they need with
get_column. - Copulas registered as a separate step, after the values are simulated and before anything is collected. Everything built from the reserves, such as net IBNR, follows automatically.
- Parameters as dimensions. Underwriting risk keeps each row's distribution parameters in float
dimensions, simulates with
zk.float, then drops them. -
Typed helpers over one column. A function that works on any single float column is typed by a type variable bound to the column types it accepts, so the type checker rejects a collection with several columns:
type FloatColumn = zk.FloatC[Any] | zk.FloatA[Any] | zk.FloatJ[Any] def earned[A: FloatColumn, V: FloatColumn]( amount: zk.Collection[ClassUnderwritingYear, A], fractions: zk.Collection[ClassUnderwritingYearCalendarYear, zk.FloatC[Lit["earned_fraction"]]], values: type[V], ) -> zk.Collection[CalendarYear, V]: by_calendar_year = (amount * fractions).group_by(Keys.calendar_year).sum() return by_calendar_year.rename({amount.column_names[0]: values}).validate(CalendarYear, values)