Metadata-Version: 2.4
Name: experiencestudies
Version: 0.4.0
Summary: 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.
Project-URL: Homepage, https://github.com/OpenActuarial/experiencestudies
Project-URL: Documentation, https://openactuarial.org/experiencestudies.html
Project-URL: Repository, https://github.com/OpenActuarial/experiencestudies
Project-URL: Issues, https://github.com/OpenActuarial/experiencestudies/issues
Author: Michael Bryant
License-Expression: MIT
License-File: LICENSE
Keywords: actuarial,analytics,claims,experience analysis,insurance,loss ratio,risk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.10
Requires-Dist: actuarialpy>=0.45
Requires-Dist: numpy>=1.23
Requires-Dist: pandas>=1.5
Provides-Extra: dev
Requires-Dist: build>=1; extra == 'dev'
Requires-Dist: hypothesis>=6; extra == 'dev'
Requires-Dist: openpyxl>=3.1; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: twine>=5; extra == 'dev'
Provides-Extra: excel
Requires-Dist: openpyxl>=3.1; extra == 'excel'
Description-Content-Type: text/markdown

# experiencestudies

Experience reporting and monitoring workflows on tidy data.

[![CI](https://github.com/OpenActuarial/experiencestudies/actions/workflows/ci.yml/badge.svg)](https://github.com/OpenActuarial/experiencestudies/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/experiencestudies)](https://pypi.org/project/experiencestudies/)
[![Python](https://img.shields.io/pypi/pyversions/experiencestudies)](https://pypi.org/project/experiencestudies/)

## 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

```bash
pip install experiencestudies
```

Requires Python 3.10 or newer.

## Quick start

```python
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](https://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](https://github.com/OpenActuarial/actuarialpy) | Calculation primitives the workflow packages build on |
| **[experiencestudies](https://github.com/OpenActuarial/experiencestudies)** | Experience reporting, actual-vs-expected, claimant and concentration analysis |
| [projectionmodels](https://github.com/OpenActuarial/projectionmodels) | Claim, premium, and expense projection over a renewal horizon |
| [ratingmodels](https://github.com/OpenActuarial/ratingmodels) | Manual and experience rating, credibility, indication, GLM relativities |
| [lossmodels](https://github.com/OpenActuarial/lossmodels) | Severity and frequency fitting, aggregate loss distributions |
| [extremeloss](https://github.com/OpenActuarial/extremeloss) | Extreme-value tails: POT/GPD, GEV, return levels, splicing |
| [risksim](https://github.com/OpenActuarial/risksim) | Portfolio Monte Carlo, dependence, reinsurance contracts, risk measures |

Install everything at once with `pip install openactuarial`.

## Development

```bash
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](CHANGELOG.md). Current per-package API
stability is tracked at
[openactuarial.org/stability.html](https://openactuarial.org/stability.html).

## License

MIT — see [LICENSE](LICENSE).
