Skip to content

Core Concepts in Gaspatchio

Introduction

Gaspatchio is a Python library designed specifically for actuarial modeling. It provides a domain-specific language (DSL) that makes it easier to express complex actuarial calculations while maintaining performance and readability. If you're a modeling actuary with Python experience, this library builds on concepts you might already know from pandas, but with specific optimizations and features for actuarial work.

ActuarialFrame: The Foundation

At the heart of Gaspatchio is the ActuarialFrame, a powerful alternative to pandas DataFrames. While pandas is excellent for general data manipulation, actuarial models often require:

  • Handling of projection periods across many time steps
  • Complex calculation dependencies
  • Performance optimization for large datasets
  • Vectorized operations on grouped data

ActuarialFrame addresses these needs by wrapping Polars, a lightning-fast DataFrame library, and adding actuarial-specific functionality.

from gaspatchio_core.dsl.core import ActuarialFrame

# Create an ActuarialFrame from existing data
af = ActuarialFrame(your_data)

# Set calculation columns using natural Python syntax
af["age-last"] = af.floor(af["age"]).cast(pl.Int64)
af["premium_rate"] = af["base_rate"] * af["age_factor"]

Key Differences from pandas

If you're familiar with pandas, here are the main differences:

  1. Lazy Evaluation: Operations are captured and optimized before execution, rather than being executed immediately
  2. Expression Tracking: The library tracks how columns are derived, enabling model auditing and optimization
  3. Actuarial Functions: Built-in functions for common actuarial operations
  4. Performance Modes: Debug and optimize modes to balance development speed with production performance

Modeling Approach

Gaspatchio encourages a functional, pipeline-based approach to model building:

def life_model(af):
    # Chain operations using pipe for cleaner code
    af = (setup_ages(af)
          .pipe(mortality_rate)
          .pipe(lapse_rate)
          .pipe(premium_rate))

    # Define cashflows
    af["premium_cashflow"] = af["premium_rate"] * af["P[IF]"] * af["sum_assured"] / 1000
    af["claims_cashflow"] = af["P[death]"] * af["sum_assured"]

    return af

This approach makes models more testable, maintainable and readable.

  • Testable: Each function can be tested independently.
  • Maintainable: Clear separation of concerns.
  • Readable: Operations flow naturally from inputs to outputs.

Performance Optimization

Gaspatchio provides two execution modes:

  1. Debug Mode: Direct execution for easier debugging and development
  2. Optimize Mode: Captures operations to optimize before execution, with optional Numba acceleration
# Set mode globally
from gaspatchio_core.dsl.core import set_default_mode
set_default_mode("optimize")

# Or per frame
af = ActuarialFrame(data, mode="optimize")

Table Lookups and Assumptions

The library provides efficient ways to handle assumption tables common in actuarial work:

# Register a mortality table
registry.register_table(
    name="mortality_rates",
    df=mortality_df,
    keys=["age-last", "gender_smoking"],
    value_column="mortality_rate"
)

# Look up values in models
af["mortality_rate"] = assumption_lookup(
    "age-last", 
    "gender_smoking",
    table_name="mortality_rates"
)

Getting Started

To start building your first model with Gaspatchio, you need to:

  1. Define your model points (policy data)
  2. Create an ActuarialFrame from your data
  3. Define projection functions
  4. Run your model with the run_model function

For detailed examples and API documentation, see the subsequent sections of this guide.