Metadata-Version: 2.4
Name: lossratio
Version: 0.0.1.dev4
Summary: Loss ratio analysis for insurance experience data (Python sibling of the R lossratio package; in development).
Project-URL: Homepage, https://seokhoonj.github.io/lossratio/
Project-URL: Source, https://github.com/seokhoonj/lossratio-py
Project-URL: R package, https://github.com/seokhoonj/lossratio
Project-URL: Issues, https://github.com/seokhoonj/lossratio-py/issues
Author-email: Seokhoon Joo <seokhoonj@gmail.com>
License-Expression: MPL-2.0
License-File: LICENSE
Keywords: actuarial,chain ladder,health insurance,insurance,loss ratio,reserving
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.9
Requires-Dist: numpy>=1.24
Requires-Dist: polars>=1.0
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: pandas>=2.0; extra == 'dev'
Requires-Dist: pyarrow>=10; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Provides-Extra: pandas
Requires-Dist: pandas>=2.0; extra == 'pandas'
Requires-Dist: pyarrow>=10; extra == 'pandas'
Description-Content-Type: text/markdown

# lossratio (Python)

Python sibling of the R `lossratio` package: loss-ratio analysis and
projection for long-term health insurance from long-format experience
data. Stage-adaptive (SA) projection uses an exposure-driven (ED)
model before the maturity point and chain ladder (Mack, CL) after,
supported by maturity point detection, cohort regime detection, and
a calendar-diagonal backtest framework.

This Python implementation is in active development.

## Current status

Working components so far:

- `Experience` — validates loss-ratio experience data (`cym`, `uym`,
  `loss`, `rp`), accepts polars or pandas input.
- `Triangle` — cohort × dev aggregation with incremental (`loss`,
  `rp`) and cumulative (`closs`, `crp`) sums and ratios (`lr`,
  `clr`) per (group, cohort, dev) lane.

Additional components (loss-ratio projection with stage-adaptive
method, maturity point and cohort regime detection, calendar-diagonal
backtest) are being added incrementally. The full working reference
implementation is the R `lossratio` package; see the section below
for a link.

## Quick Start

```python
import polars as pl
import lossratio as lr

# Three cohorts (2024-01, 02, 03) each observed over up to three months
df = pl.DataFrame({
    "cym": [
        "2024-01-01", "2024-02-01", "2024-03-01",   # cohort 2024-01, dev 1-3
        "2024-02-01", "2024-03-01",                  # cohort 2024-02, dev 1-2
        "2024-03-01",                                # cohort 2024-03, dev 1
    ],
    "uym": [
        "2024-01-01", "2024-01-01", "2024-01-01",
        "2024-02-01", "2024-02-01",
        "2024-03-01",
    ],
    "loss": [12.0, 18.0, 25.0, 15.0, 22.0,  9.0],
    "rp":   [100.0, 100.0, 100.0, 110.0, 110.0, 120.0],
})

exp = lr.Experience(df)
tri = exp.triangle()
print(tri.df)
#> shape: (6, 8)
#> ┌────────────┬─────┬──────┬───────┬───────┬───────┬──────────┬──────────┐
#> │ cohort     ┆ dev ┆ loss ┆ rp    ┆ closs ┆ crp   ┆ lr       ┆ clr      │
#> │ date       ┆ i64 ┆ f64  ┆ f64   ┆ f64   ┆ f64   ┆ f64      ┆ f64      │
#> ╞════════════╪═════╪══════╪═══════╪═══════╪═══════╪══════════╪══════════╡
#> │ 2024-01-01 ┆ 1   ┆ 12.0 ┆ 100.0 ┆ 12.0  ┆ 100.0 ┆ 0.12     ┆ 0.12     │
#> │ 2024-01-01 ┆ 2   ┆ 18.0 ┆ 100.0 ┆ 30.0  ┆ 200.0 ┆ 0.18     ┆ 0.15     │
#> │ 2024-01-01 ┆ 3   ┆ 25.0 ┆ 100.0 ┆ 55.0  ┆ 300.0 ┆ 0.25     ┆ 0.183333 │
#> │ 2024-02-01 ┆ 1   ┆ 15.0 ┆ 110.0 ┆ 15.0  ┆ 110.0 ┆ 0.136364 ┆ 0.136364 │
#> │ 2024-02-01 ┆ 2   ┆ 22.0 ┆ 110.0 ┆ 37.0  ┆ 220.0 ┆ 0.2      ┆ 0.168182 │
#> │ 2024-03-01 ┆ 1   ┆  9.0 ┆ 120.0 ┆  9.0  ┆ 120.0 ┆ 0.075    ┆ 0.075    │
#> └────────────┴─────┴──────┴───────┴───────┴───────┴──────────┴──────────┘
```

The same triangle can be sliced by an optional grouping variable
(coverage, product, age band, sum insured, ...):

```python
df_grouped = df.with_columns(pl.lit("SUR").alias("cv_nm"))
tri = lr.Experience(df_grouped).triangle(group_var="cv_nm")
```

Pandas inputs are accepted too; outputs mirror the input type
(pandas in → pandas out, polars in → polars out). Install with the
optional `pandas` extra:

```bash
pip install lossratio[pandas]
```

## R package

- Source: <https://github.com/seokhoonj/lossratio>
- Documentation: <https://seokhoonj.github.io/lossratio/>
- 한국어 문서: <https://seokhoonj.github.io/lossratio/ko/>

```r
remotes::install_github("seokhoonj/lossratio")
library(lossratio)
```

## Author

Seokhoon Joo (<seokhoonj@gmail.com>) — also maintains the R
`lossratio` package.

## License

MPL-2.0 (Mozilla Public License 2.0).
