Skip to content

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)