Tutorials¶
A progressive tutorial for building actuarial models with Gaspatchio. Each level introduces new concepts while producing a working model you can run and inspect.
The tutorial is designed for actuaries who know Excel and are learning Python-based modelling. The models themselves teach the Python — you don't need prior Python experience to start.
Levels¶
| Level | Name | What You'll Learn | Start Here If... |
|---|---|---|---|
| 1 — Hello World | ActuarialFrame, column arithmetic, when/then/otherwise, .collect() |
You're new to Gaspatchio | |
| 2 — Assumptions | Table.lookup(), multi-dimension tables, loading from files |
You know DataFrames but not Gaspatchio Tables | |
| 3 — Mini Variable Annuity | Full VA projection: mortality, lapse, AV, claims, discounting. 6 incremental steps. | You want the full picture first | |
| 4 — Reconciled Lifelib Model | Production model reconciled against lifelib IntegratedLife at 0.0000% across 1,016 model points, 35 variables, ~9M data points | You're ready to build a production model | |
| 5 — Scenarios | Deterministic scenarios, parameter shocks, sensitivity sweeps, regulatory-style reports with Altair charts | You need scenario analysis |
Using the Tutorials with AI¶
If you have the gaspatchio plugin installed, you can work through these tutorials using natural language. Open your editor and ask:
- "Start me on the Level 1 Hello World tutorial."
- "I've done Level 2 — take me to Level 3."
- "I want to reconcile a model against lifelib. Which level do I need?"
- "Guide me through Level 3 step by step."
The tooling loads the tutorial content, presents each step in actuarial terms, and supports you in running and modifying the models at your own pace.
Quick Start¶
Tutorials ship with the gaspatchio package. Use the CLI to get started:
# See what's available
gspio tutorial list
# Initialize Level 1 into your working directory
gspio tutorial init level-1
# Run it
cd my-first-model
uv run python model.py
# Verify the output matches expected
gspio tutorial verify level-1
New to Gaspatchio? Start with Level 1 — it's 60 lines and covers the four core concepts.
Want a complete VA model to study? Initialize Level 3 — a full variable annuity projection in a single file with inline data:
gspio tutorial init level-3 --dest ./va-model
Read the docstring, read the code section by section, then run it.
Level 1: Hello World¶
Three term life insurance policies, no prior Python experience required. The base model is about 60 lines and introduces:
- ActuarialFrame — the central data structure
- Column arithmetic — operators work on entire projection vectors
when/then/otherwise— conditional logic for actuarial rules.collect()— run the full calculation when you are ready
| Step | What It Adds |
|---|---|
| Base | 3 policies, scalar arithmetic, no projections |
| 01 — Projections | Add time dimension (list columns) |
| 02 — Survival | Cumulative survival probability |
| 03 — Time Shifting | previous_period(), per-period deaths |
# Initialize and run the base model
gspio tutorial init level-1
cd my-first-model && uv run python model.py
Level 2: Assumptions¶
Teaches assumption table lookups — the core mechanism for separating business assumptions from model logic.
| Step | What It Adds |
|---|---|
| Base | Mortality from Table (age lookup) |
| 01 — Multi-Dimension | Age x sex mortality Table |
| 02 — From Files | Load data from parquet files |
| 03 — Lapse | Lapse rate Table, combined decrements |
| 04 — Conditionals | when/then/otherwise on list columns |
gspio tutorial init level-2
cd my-first-model && uv run python model.py
Level 3: Mini VA¶
A complete variable annuity projection built incrementally. The base model uses inline data — no external files needed. Each step adds one feature so you can see exactly what changed and why.
| Step | What It Adds |
|---|---|
| Base | Inline data, simplest VA model |
| 01 — From Files | Data from parquet files |
| 02 — Select Mortality | Select/ultimate mortality tables, multi-key lookup, mortality scalars |
| 03 — Guarantees | GMDB, GMAB guarantees, surrender charges, nested conditionals |
| 04 — Dynamic Lapse | ITM ratio, dynamic lapse formula, duration-based lapse tables |
| 05 — Rate Curves | Risk-free rate curve discounting, term-structure lookup |
| 06 — Reconcile | Bridge to Level 4: 4 actuarial gaps discovered and fixed via reconciliation against lifelib |
| 07 — Rollforward | Replace cum_prod() AV growth with the rollforward state-machine kernel — same numbers, explicit recurrence |
# Initialize and run the base model (inline data, self-contained)
gspio tutorial init level-3 --dest ./va-model
cd va-model && uv run python model.py
Level 4: Reconciled Lifelib¶
The full appliedlife model, reconciled against lifelib's IntegratedLife implementation. Projects monthly cashflows and present values for GMDB/GMAB variable annuity products.
Key achievement: 0.0000% difference across 1,016 model points (IF + NB), 35 variables, ~9M data points.
Uses accumulate() for the AV accumulation. The model is ~860 lines with 14 assumption table files.
# Initialize and run the model
gspio tutorial init level-4 --dest ./lifelib-model
cd lifelib-model && uv run gspio run-model model.py model_points.parquet
Level 5: Scenarios¶
Scenario analysis for the reconciled VA model — every step uses the typed ScenarioRun plan and the bounded-memory for_each_scenario loop. Each plan has a stable SHA, an audit sidecar, and produces per-scenario aggregates ready for tornado / sensitivity / heatmap visualisation.
| Step | What It Adds |
|---|---|
| Base | Interest-rate scenarios (BASE/UP/DOWN) via with_scenarios, scenario-aware Curve discounting |
| 01 — Parameter Shocks | ScenarioRun plan, MultiplicativeShock against assumption tables, mergeable aggregators with .over("scenario_id"), audit sidecar, tornado data |
| 02 — Conditional Shocks | FilteredShock (e.g. age ≥ 65), TimeConditionalShock (e.g. duration ≤ 5), PipelineShock (e.g. Solvency II ×1.5 then clip 1.0) |
| 03 — Sensitivity | 1D sweep (mortality multiplier across a range) and 2D mortality × lapse interaction grid for heatmap visualisation — built as plain ScenarioRun plans, no special helper |
| 04 — Scenario Comparison | Named regulatory stresses (CENTRAL_ESTIMATE, ADVERSE_MORTALITY, ECONOMIC_DOWNTURN, OPERATIONAL_SHOCK), full audit chain (source_sha, to_yaml, JSON audit sidecar), reproducibility memo |
| 05 — Stochastic Monte Carlo | 200 paths via master_seed; drivers["rng_seed"] flows to the model; CTE + Quantile aggregators give SCR-shape capital figures; same seed → same SHA → byte-identical aggregates |
# Initialize and run base scenarios
gspio tutorial init level-5 --dest ./scenarios-model
cd scenarios-model && uv run python run_scenarios.py
Running Models¶
Initialize any tutorial with gspio tutorial init, then run it:
Standalone Python — run the model directly:
uv run python model.py
Single policy — debug one policy, see every variable:
uv run gspio run-single-policy model.py data.parquet 1
All policies — run the full model point set:
uv run gspio run-model model.py data.parquet
Verify output — confirm the model produces expected results:
gspio tutorial verify level-1