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¶
New to Gaspatchio? Run the Level 1 base model — it's 60 lines and covers the four core concepts:
uv run python tutorial/level-1-hello-world/base/model.py
Want a complete VA model to study? Run the Level 3 base model — a full variable annuity projection in a single file with inline data:
uv run python tutorial/level-3-mini-va/base/model.py
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()— lazy evaluation, execute when 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 |
# Run the base model
uv run python tutorial/level-1-hello-world/base/model.py
# Run Step 03
uv run python tutorial/level-1-hello-world/steps/03-time-shifting/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 |
uv run python tutorial/level-2-assumptions/base/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 |
# Base model (inline data, self-contained)
uv run python tutorial/level-3-mini-va/base/model.py
# Step 01 with model point file
uv run gspio run-single-policy tutorial/level-3-mini-va/steps/01-from-files/model.py \
tutorial/level-3-mini-va/steps/01-from-files/data/model_points.parquet 1
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 rollforward. The model is ~860 lines with 14 assumption table files.
# Run the model
uv run gspio run-model tutorial/level-4-lifelib/base/model.py \
tutorial/level-4-lifelib/base/model_points.parquet
# Reconcile against lifelib reference
uv run python tutorial/level-4-lifelib/reconcile.py
Level 5: Scenarios¶
Deterministic scenario analysis for the reconciled VA model. Each step builds on the previous, adding more sophisticated scenario techniques.
| Step | What It Adds |
|---|---|
| Base | with_scenarios() for BASE/UP/DOWN interest rate scenarios, grouped bar + waterfall charts |
| 01 — Parameter Shocks | Declarative JSON shocks, Table.with_shock(), tornado chart |
| 02 — Conditional Shocks | where filters, when time conditions, pipeline chains, cashflow line charts |
| 03 — Sensitivity | 1D sweeps via sensitivity_analysis(), 2D heatmap interaction grid |
| 04 — Scenario Comparison | Named regulatory scenarios, audit trail, full stress test report |
# Run base scenarios
uv run python tutorial/level-5-scenarios/base/run_scenarios.py
# Run sensitivity sweep
uv run python tutorial/level-5-scenarios/steps/03-sensitivity/run_sensitivity.py
Running Models¶
Three ways to run any tutorial model:
Standalone Python — run the model directly:
uv run python tutorial/level-3-mini-va/base/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