Metadata-Version: 2.4
Name: actuarialpy
Version: 0.44.1
Summary: Shared actuarial primitives and general tooling: ratios, credibility, trend, completion, seasonality, financial mathematics, exposure, banding, pooling, and margins on tidy tables.
Project-URL: Homepage, https://github.com/OpenActuarial/actuarialpy
Project-URL: Documentation, https://openactuarial.org/actuarialpy.html
Project-URL: Repository, https://github.com/OpenActuarial/actuarialpy
Project-URL: Issues, https://github.com/OpenActuarial/actuarialpy/issues
Author: Michael Bryant
License-Expression: MIT
License-File: LICENSE
Keywords: actuarial,analytics,claims,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: 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: pytest>=7; extra == 'dev'
Requires-Dist: twine>=5; extra == 'dev'
Description-Content-Type: text/markdown

# actuarialpy

Purpose-neutral actuarial calculation primitives — the foundation of the OpenActuarial ecosystem.

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

## Overview

`actuarialpy` provides the atomic building blocks the rest of the ecosystem
is written against: ratios and per-exposure metrics, claim development and
completion, trend fitting and projection, credibility, large-claim pooling,
and financial mathematics. Everything operates on plain floats, NumPy arrays,
and pandas objects, with a consistent type-mirroring convention (scalar in,
`float` out; `Series` in, `Series` out with the index preserved).

The package deliberately contains no workflow orchestration and no
domain-specific vocabulary — those belong to the workflow packages built on
top of it. If a function here needs to know *why* you are calling it, it does
not belong here.

## Installation

```bash
pip install actuarialpy
```

Requires Python 3.10 or newer.

## Quick start

```python
import pandas as pd
import actuarialpy as ap

# ratios and per-exposure rates on any aggregate
print(ap.loss_ratio(1_240_000, 1_500_000))       # 0.8267
print(ap.per_exposure(1_240_000, 12_000))        # 103.33 per exposure unit

# fit a trend to a monthly series and project it forward
monthly = pd.DataFrame({
    "month": pd.date_range("2024-01-01", periods=24, freq="MS"),
    "loss_ratio": [0.80 * 1.004 ** i for i in range(24)],
})
fit = ap.fit_trend(monthly, date_col="month", value_col="loss_ratio")
print(f"annual trend: {fit.annual_trend:+.2%}")
print(round(ap.project_forward(monthly["loss_ratio"].iloc[-1],
                               fit.annual_trend, months=6), 4))

# cap large claims at a pooling point; the excess moves to its own column
claims = pd.DataFrame({"member": ["a", "b", "c"],
                       "paid": [612_000.0, 340_000.0, 96_500.0]})
pooled = ap.pool_losses(claims, loss_col="paid", pooling_point=250_000)
print(pooled)
```

## What's inside

- **Metrics** — loss/expense ratios, per-exposure rates, weighted statistics,
  contribution and comparison helpers.
- **Reserving** — completion triangles, chain-ladder development factors,
  Mack standard errors, completion applied back to tidy data.
- **Trend and seasonality** — trend fitting, forward projection, seasonal
  adjustment.
- **Credibility** — Bühlmann, Bühlmann–Straub, and limited-fluctuation
  credibility.
- **Pooling** — large-claim capping and excess extraction.
- **Financial** — time-value-of-money primitives (present/future value,
  annuities, rate conversions).
- **Data utilities** — exposure handling, banding, period alignment, member
  lifecycle status, margins and adjustments.

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

## The OpenActuarial ecosystem

`actuarialpy` 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/actuarialpy
cd actuarialpy
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).
