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()— 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 |
# 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 |
# 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 rollforward. 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¶
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 |
# 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