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:

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.