API Overview¶

Gaspatchio's API is designed to feel like Excel formulas but work like optimized Python. Every operation is vectorized by default, lazy by design, and built for actuarial workflows.

The Three API Layers¶

1. Core API¶

The foundation for all actuarial modeling:

Component	Purpose
ActuarialFrame	Container for policy data with lazy evaluation
Expressions	Column operations and arithmetic
Conditionals	`when().then().otherwise()` business logic
Scenarios	What-if analysis and sensitivity testing

2. Domain Extensions (Accessors)¶

Specialized namespaces attached to columns for domain-specific operations:

Accessor	Access Pattern	Purpose
Excel	`af.column.excel`	Excel-compatible functions (YEARFRAC, DAYS, PV, IRR)
Date	`af.column.dt`	Date extraction and manipulation
Finance	`af.column.finance`	Rate conversions, discounting, compounding
Projection	`af.column.projection`	Time-series operations (cumulative survival, period shifting)
String	`af.column.str`	String manipulation

3. Assumption Tables¶

The Table class for high-performance dimension-based lookups. See Assumptions for details.

Quick Start Pattern¶

from gaspatchio_core import ActuarialFrame, when
from gaspatchio_core.assumptions import Table
import datetime

# 1. Create frame from policy data
af = ActuarialFrame({
    "policy_id": ["P001", "P002"],
    "issue_date": [datetime.date(2020, 1, 15), datetime.date(2021, 6, 1)],
    "issue_age": [35, 42],
    "sum_assured": [100_000, 250_000],
    "status": ["active", "active"],
    "annual_rate": [0.04, 0.05],
})

# 2. Date calculations with Excel accessor
af.years_in_force = af.issue_date.excel.yearfrac(
    datetime.date(2024, 12, 31), basis="act/act"
)

# 3. Arithmetic (auto-vectorized)
af.attained_age = af.issue_age + af.years_in_force

# 4. Financial calculations
af.pv_premiums = af.annual_rate.excel.pv(nper=20, pmt=1200)

# 5. Conditional business logic
af.benefit = when(af.status == "active").then(af.sum_assured).otherwise(0)

# 6. Execute all calculations at once
df = af.collect()

The Accessor Pattern¶

Accessors extend columns with domain-specific methods. They're available at two levels:

Column-level - operates on a specific column:

af.years = af.issue_date.excel.yearfrac(af.val_date, basis="act/act")
af.month = af.issue_date.dt.month()
af.survival = af.qx.projection.cumulative_survival()

Frame-level - operates on the entire frame:

af = af.finance.discount_factor(
    rate_col="rate",
    periods_col="month",
    output_col="disc_factor"
)

Key Concepts¶

Lazy Evaluation¶

All operations build an expression graph. Nothing executes until you call .collect():

# These just build the plan
af.a = af.x + af.y
af.b = af.a * 2
af.c = af.b.excel.pv(nper=10, pmt=100)

# This executes everything in one optimized pass
df = af.collect()

Vector-Aware Operations¶

List columns represent time series. All operations work element-wise automatically:

# Scalar * list = list (broadcast)
af.claims = af.sum_assured * af.mortality_rates  # mortality_rates is a list column

# List - list = list (element-wise)
af.net_cf = af.premiums - af.claims

Attribute Notation¶

Always use attribute notation for clean, readable code:

# Preferred
af.result = af.rate * af.amount

# Only use brackets for reserved words or special characters
af["class"] = af["policy class"].str.to_uppercase()

I want to...	Go to...
Create and manipulate frames	ActuarialFrame
Use Excel functions (PV, IRR, YEARFRAC)	Excel
Work with dates	Date
Calculate discount factors, convert rates	Finance
Handle time-series (survival, shifting)	Projection
Write if/then logic	Conditionals
Run scenarios and sensitivities	Scenarios
Look up assumption tables	Assumptions