Metadata-Version: 2.4
Name: reservingmodels
Version: 0.1.0
Summary: Claims development and stochastic reserving: chain ladder, Bornhuetter-Ferguson, Mack, and the over-dispersed-Poisson bootstrap of the predictive reserve distribution.
Project-URL: Homepage, https://github.com/OpenActuarial/reservingmodels
Project-URL: Documentation, https://openactuarial.org/reservingmodels.html
Project-URL: Repository, https://github.com/OpenActuarial/reservingmodels
Project-URL: Issues, https://github.com/OpenActuarial/reservingmodels/issues
Author: Michael Bryant
License-Expression: MIT
License-File: LICENSE
Keywords: actuarial,bootstrap,chain-ladder,health-insurance,ibnr,insurance,loss-development,reserving
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.10
Requires-Dist: actuarialpy<0.47,>=0.46
Requires-Dist: numpy>=1.23
Requires-Dist: pandas>=2.2
Provides-Extra: dev
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: risksim>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# reservingmodels

Claims development and stochastic reserve estimation, from the triangle to the predictive distribution.

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

## Overview

`reservingmodels` is the single place to reach for claims-reserving work. The
deterministic engine — chain-ladder development, completion factors, the
Bornhuetter–Ferguson / Benktander / Cape Cod methods, and Mack's analytic
standard errors — is **re-exported from `actuarialpy`**, where those triangle
primitives already live because the projection and pricing packages build on
them. On top of them this package adds the stochastic layer: the
over-dispersed-Poisson bootstrap of England & Verrall, which produces the full
*predictive distribution* of the unpaid claims, plus residual diagnostics for
checking the model before you trust the numbers.

A fitted `BootstrapODP` exposes `.sample(size, rng)`, so it plugs straight into
[`risksim`](https://github.com/OpenActuarial/risksim) as a portfolio component —
reserve risk aggregated with prospective underwriting risk, with no dependency
between the two packages.

## Installation

```bash
pip install reservingmodels
```

Requires Python 3.10 or newer. Pulls in `actuarialpy` for the shared triangle
primitives.

## Quick start

```python
import reservingmodels as rv

triangle = rv.datasets.taylor_ashe()          # a cumulative K x K triangle

# --- deterministic: the point estimate (re-exported chain ladder) ---------- #
cl = rv.ChainLadder.fit(triangle)
print(cl.project(triangle))                   # per-origin ultimate and IBNR
print(cl.mack_standard_errors(triangle))      # Mack (1993) analytic SE

# --- stochastic: the predictive distribution ------------------------------- #
boot = rv.BootstrapODP.fit(triangle)
dist = boot.reserve_distribution(size=100_000, rng=42)

print(f"reserve (point)   : {dist.point_reserve:,.0f}")
print(f"prediction error  : {dist.prediction_error():,.0f}")
print(f"75th / 99th pct   : {dist.quantile(0.75):,.0f} / {dist.quantile(0.99):,.0f}")
print(f"TVaR(99%)         : {dist.tvar(0.99):,.0f}")
print(dist.to_frame().round(0))               # per-origin + total exhibit

# --- reserve risk as a capital component ----------------------------------- #
import risksim as rs
port = rs.Portfolio([rs.PortfolioItem("reserve_risk", boot)])  # .sample seam
sim = port.simulate(100_000, rng=7)
print(f"portfolio TVaR    : {rs.metrics.tvar(sim.gross_losses, 0.99):,.0f}")
```

## What's inside

- **Triangles and deterministic methods** — re-exported from `actuarialpy`:
  `ChainLadder`, `completion_factors`, `apply_completion`, `develop_ultimate`
  (chain-ladder, Bornhuetter–Ferguson, Benktander, Cape Cod),
  `make_completion_triangle`, and Mack's `mack_standard_errors`. These are
  aliases, not copies — `rv.ChainLadder is actuarialpy.ChainLadder`.
- **Stochastic reserving** — `BootstrapODP`, the semiparametric ODP bootstrap
  (estimation error by residual resampling, process error by a gamma draw), and
  `ReserveDistribution` for percentiles, VaR, TVaR, and a per-origin exhibit.
- **Diagnostics** — `pearson_residuals`, `residual_summary`, and
  `calendar_year_effects` for checking the ODP assumptions.
- **The `risksim` seam** — `BootstrapODP.sample(size, rng)` makes the reserve a
  portfolio component; `risksim` aggregates it with other risks.
- **The Experience seam** — `reservingmodels.integrations.actuarialpy` builds a
  triangle (and a fitted bootstrap) from a claims-listing `actuarialpy.Experience`.

The full API reference and worked examples live at
**[openactuarial.org/reservingmodels.html](https://openactuarial.org/reservingmodels.html)**.

## The OpenActuarial ecosystem

`reservingmodels` shares the ecosystem conventions — tidy tables, explicit
parameterizations, reproducible random-number handling — and composes across
package seams:

| Package | Role |
|---|---|
| [actuarialpy](https://github.com/OpenActuarial/actuarialpy) | Calculation primitives the workflow packages build on (incl. triangle mechanics and Mack) |
| [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 |
| **[reservingmodels](https://github.com/OpenActuarial/reservingmodels)** | Claims development and stochastic reserving: chain ladder, BF, Mack, ODP bootstrap |
| [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/reservingmodels
cd reservingmodels
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).
