experiencestudies 0.5.0

Experience reporting and analysis on tidy tables: experience summaries and views, actual-versus-expected, claimant and cohort studies, driver and frequency-severity decomposition, rolling monitors, banded summaries. Study functions over the canonical actuarialpy.Experience.

experiencestudies

Experience reporting and monitoring workflows on tidy data.

Overview

experiencestudies turns tidy period-by-cell tables into the reports an experience team actually ships: experience summaries, actual-versus-expected against a plan, claimant and concentration analysis, cohort and duration studies, driver decomposition, rolling monitors, and a one-call Excel packet.

Every workflow is available both as a free function on a DataFrame and over the canonical actuarialpy.Experience, which carries column roles (revenue, expense, exposure, date) so views compose without repeating configuration.

Installation

pip install experiencestudies

Requires Python 3.10 or newer.

Quick start

import pandas as pd
import experiencestudies as es

df = pd.DataFrame({
    "month": pd.date_range("2024-01-01", periods=12, freq="MS"),
    "lob": ["med"] * 12,
    "claims": [820, 910, 875, 1010, 990, 1105, 1080, 1240, 1180, 1035, 995, 1150.0],
    "premium": [1500.0] * 12,
    "member_months": [1000.0] * 12,
})

# free-function form
summary = es.summarize_experience(
    df, groupby="lob",
    expense_cols="claims", revenue_cols="premium", exposure_cols="member_months",
)
print(summary)

# Experience form — same result, plus composable views
from actuarialpy import Experience

exp = Experience(df, expense="claims", revenue="premium",
                 exposure="member_months", date="month")
print(es.summary(exp, "lob"))
print(es.rolling(exp, 3).tail(3))

What's inside

• Experience summaries — grouped ratios, per-exposure rates, and rollups via summarize_experience or study functions over the Experience.
• Actual versus expected — plan merge, A/E summaries, and forecast comparison.
• Claimant analysis — top claimants, large-claimant flags, and claim_concentration threshold statements.
• Cohorts and durations — cohort assembly and duration-based studies.
• Decomposition — frequency/severity/mix drivers that reconcile exactly to the total change.
• Rolling monitors — trailing windows for emerging-experience review.
• Reporting — underwriting_summary and to_excel_report for a multi-sheet packet.

The full API reference and end-to-end worked examples live at openactuarial.org/experiencestudies.html.

The OpenActuarial ecosystem

experiencestudies is one of seven packages that share conventions — tidy tables, explicit distribution parameterizations, reproducible random-number handling — and compose across package seams:

Package	Role
actuarialpy	Calculation primitives the workflow packages build on
experiencestudies	Experience reporting, actual-vs-expected, claimant and concentration analysis
projectionmodels	Claim, premium, and expense projection over a renewal horizon
ratingmodels	Manual and experience rating, credibility, indication, GLM relativities
lossmodels	Severity and frequency fitting, aggregate loss distributions
extremeloss	Extreme-value tails: POT/GPD, GEV, return levels, splicing
risksim	Portfolio Monte Carlo, dependence, reinsurance contracts, risk measures

Install everything at once with pip install openactuarial.

Development

git clone https://github.com/OpenActuarial/experiencestudies
cd experiencestudies
python -m pip install -e ".[dev]"
pytest
ruff check src tests

CI runs the same gate on Python 3.10–3.14 across Linux and Windows.

Versioning and stability

All ecosystem packages are pre-1.0: minor releases may change APIs, and every release is documented in CHANGELOG.md. Current per-package API stability is tracked at openactuarial.org/stability.html.

License

MIT — see LICENSE.