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:
- Lazy Evaluation: Operations are captured and optimized before execution, rather than being executed immediately
- Expression Tracking: The library tracks how columns are derived, enabling model auditing and optimization
- Actuarial Functions: Built-in functions for common actuarial operations
- 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:
- Debug Mode: Direct execution for easier debugging and development
- 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:
- Define your model points (policy data)
- Create an ActuarialFrame from your data
- Define projection functions
- Run your model with the
run_model
function
For detailed examples and API documentation, see the subsequent sections of this guide.