experiencestudies 0.1.0__tar.gz

experiencestudies-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,44 @@
+# CI for experiencestudies. Depends on actuarialpy, which is pulled from PyPI by
+# the editable install below; publish a compatible actuarialpy (>=0.42) first.
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Test
+        run: pytest -q
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade pip build twine
+          python -m build
+          twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

experiencestudies-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,56 @@
+# Tag-driven release via PyPI Trusted Publishing (no tokens, no twine
+# passwords). One-time setup per package:
+#   1. On PyPI: project -> Publishing -> add a Trusted Publisher:
+#      owner OpenActuarial, repository experiencestudies, workflow release.yml,
+#      environment pypi.
+#   2. On GitHub: repo Settings -> Environments -> create "pypi".
+# Then:  git tag v{version} && git push --tags
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: |
+          python -m pip install --upgrade pip build twine
+          python -m build
+          twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Extract latest changelog section
+        run: |
+          awk '/^## /{n++} n==1' CHANGELOG.md > release_notes.md
+      - uses: softprops/action-gh-release@v2
+        with:
+          body_path: release_notes.md

experiencestudies-0.1.0/.gitignore

@@ -0,0 +1,66 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Python build artifacts
+build/
+dist/
+*.egg-info/
+.eggs/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Test and coverage outputs
+.pytest_cache/
+.coverage
+coverage.xml
+htmlcov/
+.tox/
+.nox/
+
+# Type checker / linter caches
+.mypy_cache/
+.pyright/
+.ruff_cache/
+
+# Jupyter notebooks
+.ipynb_checkpoints/
+
+# Local environment files
+.env
+.env.*
+*.local
+
+# IDE / editor files
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+
+# Logs
+*.log
+
+# Temporary files
+tmp/
+temp/
+*.tmp
+
+# Data files generated locally
+*.csv
+*.xlsx
+*.xls
+*.parquet
+*.feather
+*.pkl
+*.pickle
+
+# Keep example datasets only if intentionally committed
+# !examples/*.csv
+# !examples/*.xlsx

experiencestudies-0.1.0/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+## 0.1.0
+
+Initial release. `experiencestudies` is the experience reporting and analysis
+layer extracted from `actuarialpy` 0.42.0; it builds on the `actuarialpy`
+primitives and depends on `actuarialpy>=0.42`.
+
+### Added
+
+- The fluent `Experience` object (construct once with expense/revenue/exposure/
+  date roles, then chain `.by()`, `.rolling()`, `.deseasonalize()`, `.complete()`,
+  `.adjust()`, ...; every method returns a new `Experience` so restatements
+  compose).
+- Experience summaries and views: `summarize_experience`, `summarize_views`,
+  `status_summary`.
+- Actual-versus-expected and forecasting: `summarize_actual_vs_expected`,
+  `expected_from_rate`, `forecast_from_rate`, `forecast_experience`,
+  `compare_actual_to_expected`.
+- Claimant and concentration analysis: `summarize_claimants`, `top_claimants`,
+  `large_claimant_flags`, `claim_concentration`.
+- Cohort and duration studies: `cohort_summary`, `cohort_summary_by_period`,
+  `duration_summary`.
+- Driver/component and frequency-severity decomposition:
+  `component_driver_analysis`, `component_trend`, `summarize_components`,
+  `decompose_per_exposure_trend`, `frequency_severity_summary`.
+- Rolling monitors: `rolling_summary`.
+- Banded summaries: `summarize_by_band` (assigns bands via
+  `actuarialpy.assign_band`, then summarizes experience per band).
+
+All signatures match the pre-split `actuarialpy` versions of these functions, so
+migrating is an import change: import these names from `experiencestudies`
+instead of `actuarialpy`.

experiencestudies-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Bryant
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

experiencestudies-0.1.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: experiencestudies
+Version: 0.1.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, and the fluent Experience object. Built on actuarialpy.
+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.42
+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
+
+[![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/)
+
+Experience reporting and analysis on claims, exposure, and premium data: experience
+summaries and views, actual-versus-expected, claimant and concentration analysis, cohort
+and duration studies, driver and frequency-severity decomposition, rolling monitors,
+banded summaries, and simple forecasting — tied together by the fluent `Experience`
+object. Built on [`actuarialpy`](https://github.com/OpenActuarial/actuarialpy), which
+supplies the underlying primitives (ratios, trend, credibility, completion, seasonality,
+financial mathematics). Every result is a DataFrame or Series.
+
+## Contents
+
+- [Overview](#overview)
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [The `Experience` object](#the-experience-object)
+- [Experience summaries and views](#experience-summaries-and-views)
+- [Actual versus expected and forecasting](#actual-versus-expected-and-forecasting)
+- [Claimant and concentration analysis](#claimant-and-concentration-analysis)
+- [Cohort and duration studies](#cohort-and-duration-studies)
+- [Driver and frequency-severity decomposition](#driver-and-frequency-severity-decomposition)
+- [Rolling monitors](#rolling-monitors)
+- [Banded summaries](#banded-summaries)
+- [Relationship to actuarialpy](#relationship-to-actuarialpy)
+
+## Overview
+
+`experiencestudies` is the study layer that sits on top of the `actuarialpy` primitives.
+Where `actuarialpy` answers "what is the loss ratio / development factor / credibility
+weight for this table?", `experiencestudies` answers "how is this block performing, why is
+it moving, and where is the risk concentrated?". It does not perform data preparation or
+encode filed methodology: the caller supplies the tidy table and selects the analysis.
+
+There are two interfaces:
+
+- **Free functions** — `summarize_experience`, `summarize_actual_vs_expected`,
+  `summarize_claimants`, `cohort_summary`, `decompose_per_exposure_trend`,
+  `frequency_severity_summary`, `rolling_summary`, `summarize_by_band`, and the
+  forecasting helpers. Each takes a DataFrame and returns a DataFrame.
+- **The `Experience` object** — a fluent wrapper that remembers the expense, revenue,
+  exposure, and date columns once, then exposes the same analyses as chainable methods
+  (`.by()`, `.rolling()`, `.deseasonalize()`, `.complete()`, `.adjust()`, ...), each
+  returning a new `Experience` so restatements compose.
+
+## Installation
+
+```bash
+pip install experiencestudies
+```
+
+This pulls in `actuarialpy` (>= 0.42) automatically. For the Excel report writer, install
+the `excel` extra:
+
+```bash
+pip install "experiencestudies[excel]"
+```
+
+## Quick start
+
+```python
+import pandas as pd
+from experiencestudies import Experience, summarize_experience
+
+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] * 12,
+    "member_months": [1000] * 12,
+})
+
+# free-function form
+summary = summarize_experience(
+    df, groupby="lob",
+    expense_cols="claims", revenue_cols="premium", exposure_cols="member_months",
+)
+
+# fluent form — same result, plus composable views
+exp = Experience(df, expense="claims", revenue="premium",
+                 exposure="member_months", date="month")
+by_lob = exp.by("lob")
+trailing = exp.rolling(3)
+```
+
+## The `Experience` object
+
+Construct once with the column roles, then chain. Each method returns a new `Experience`
+(or a summary DataFrame for the terminal views), so adjustments and restatements compose
+without mutating the source:
+
+```python
+restated = (
+    exp.adjust(1.03)                      # apply a 3% trend/restatement factor
+       .deseasonalize(seasonal_factors)   # divide out a seasonal shape
+       .complete(completion_factors, valuation_date="2024-12-31")  # gross up to ultimate
+)
+restated.by("lob")                        # terminal summary
+```
+
+The seasonal factors and completion factors come from `actuarialpy`
+(`seasonality_factors`, `completion_factors`); `experiencestudies` applies them through
+the fluent lens.
+
+## Experience summaries and views
+
+`summarize_experience` and the `Experience.by()` / `.views()` methods produce grouped
+aggregates with loss ratio and per-exposure metrics. `status_summary` and
+`summarize_views` give status- and view-oriented cuts of the same underlying rollup.
+
+## Actual versus expected and forecasting
+
+`summarize_actual_vs_expected` compares realized experience against an expected column.
+`expected_from_rate` and `forecast_from_rate` build expected/forecast values from a rate
+basis; `forecast_experience` projects an experience frame forward; and
+`compare_actual_to_expected` reports the variance.
+
+## Claimant and concentration analysis
+
+`summarize_claimants`, `top_claimants`, `large_claimant_flags`, and `claim_concentration`
+identify and rank large claimants and measure how concentrated losses are (e.g. the share
+carried by the top *n*).
+
+## Cohort and duration studies
+
+`cohort_summary`, `cohort_summary_by_period`, and `duration_summary` track experience by
+entry cohort and by duration since entry.
+
+## Driver and frequency-severity decomposition
+
+`component_driver_analysis`, `component_trend`, and `summarize_components` attribute
+movement to its components; `decompose_per_exposure_trend` splits a per-exposure trend into
+frequency and severity contributions, and `frequency_severity_summary` reports the two
+sides side by side.
+
+## Rolling monitors
+
+`rolling_summary` (and `Experience.rolling(window)`) produce trailing-window rollups for
+monitoring emerging experience.
+
+## Banded summaries
+
+`summarize_by_band` assigns rows to size bands (via `actuarialpy.assign_band`) and
+summarizes experience within each band, preserving band order and surfacing empty bands.
+
+## Relationship to actuarialpy
+
+`experiencestudies` depends on `actuarialpy` and never the other way around — the
+dependency is strictly one-directional. The size-banding split is the clearest example:
+the `assign_band` primitive lives in `actuarialpy`, while `summarize_by_band` (which needs
+an experience summary) lives here. Because the study layer imports from the primitive
+layer, publish a compatible `actuarialpy` (>= 0.42) before releasing a new
+`experiencestudies`.

experiencestudies-0.1.0/README.md

@@ -0,0 +1,154 @@
+# experiencestudies
+
+[![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/)
+
+Experience reporting and analysis on claims, exposure, and premium data: experience
+summaries and views, actual-versus-expected, claimant and concentration analysis, cohort
+and duration studies, driver and frequency-severity decomposition, rolling monitors,
+banded summaries, and simple forecasting — tied together by the fluent `Experience`
+object. Built on [`actuarialpy`](https://github.com/OpenActuarial/actuarialpy), which
+supplies the underlying primitives (ratios, trend, credibility, completion, seasonality,
+financial mathematics). Every result is a DataFrame or Series.
+
+## Contents
+
+- [Overview](#overview)
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [The `Experience` object](#the-experience-object)
+- [Experience summaries and views](#experience-summaries-and-views)
+- [Actual versus expected and forecasting](#actual-versus-expected-and-forecasting)
+- [Claimant and concentration analysis](#claimant-and-concentration-analysis)
+- [Cohort and duration studies](#cohort-and-duration-studies)
+- [Driver and frequency-severity decomposition](#driver-and-frequency-severity-decomposition)
+- [Rolling monitors](#rolling-monitors)
+- [Banded summaries](#banded-summaries)
+- [Relationship to actuarialpy](#relationship-to-actuarialpy)
+
+## Overview
+
+`experiencestudies` is the study layer that sits on top of the `actuarialpy` primitives.
+Where `actuarialpy` answers "what is the loss ratio / development factor / credibility
+weight for this table?", `experiencestudies` answers "how is this block performing, why is
+it moving, and where is the risk concentrated?". It does not perform data preparation or
+encode filed methodology: the caller supplies the tidy table and selects the analysis.
+
+There are two interfaces:
+
+- **Free functions** — `summarize_experience`, `summarize_actual_vs_expected`,
+  `summarize_claimants`, `cohort_summary`, `decompose_per_exposure_trend`,
+  `frequency_severity_summary`, `rolling_summary`, `summarize_by_band`, and the
+  forecasting helpers. Each takes a DataFrame and returns a DataFrame.
+- **The `Experience` object** — a fluent wrapper that remembers the expense, revenue,
+  exposure, and date columns once, then exposes the same analyses as chainable methods
+  (`.by()`, `.rolling()`, `.deseasonalize()`, `.complete()`, `.adjust()`, ...), each
+  returning a new `Experience` so restatements compose.
+
+## Installation
+
+```bash
+pip install experiencestudies
+```
+
+This pulls in `actuarialpy` (>= 0.42) automatically. For the Excel report writer, install
+the `excel` extra:
+
+```bash
+pip install "experiencestudies[excel]"
+```
+
+## Quick start
+
+```python
+import pandas as pd
+from experiencestudies import Experience, summarize_experience
+
+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] * 12,
+    "member_months": [1000] * 12,
+})
+
+# free-function form
+summary = summarize_experience(
+    df, groupby="lob",
+    expense_cols="claims", revenue_cols="premium", exposure_cols="member_months",
+)
+
+# fluent form — same result, plus composable views
+exp = Experience(df, expense="claims", revenue="premium",
+                 exposure="member_months", date="month")
+by_lob = exp.by("lob")
+trailing = exp.rolling(3)
+```
+
+## The `Experience` object
+
+Construct once with the column roles, then chain. Each method returns a new `Experience`
+(or a summary DataFrame for the terminal views), so adjustments and restatements compose
+without mutating the source:
+
+```python
+restated = (
+    exp.adjust(1.03)                      # apply a 3% trend/restatement factor
+       .deseasonalize(seasonal_factors)   # divide out a seasonal shape
+       .complete(completion_factors, valuation_date="2024-12-31")  # gross up to ultimate
+)
+restated.by("lob")                        # terminal summary
+```
+
+The seasonal factors and completion factors come from `actuarialpy`
+(`seasonality_factors`, `completion_factors`); `experiencestudies` applies them through
+the fluent lens.
+
+## Experience summaries and views
+
+`summarize_experience` and the `Experience.by()` / `.views()` methods produce grouped
+aggregates with loss ratio and per-exposure metrics. `status_summary` and
+`summarize_views` give status- and view-oriented cuts of the same underlying rollup.
+
+## Actual versus expected and forecasting
+
+`summarize_actual_vs_expected` compares realized experience against an expected column.
+`expected_from_rate` and `forecast_from_rate` build expected/forecast values from a rate
+basis; `forecast_experience` projects an experience frame forward; and
+`compare_actual_to_expected` reports the variance.
+
+## Claimant and concentration analysis
+
+`summarize_claimants`, `top_claimants`, `large_claimant_flags`, and `claim_concentration`
+identify and rank large claimants and measure how concentrated losses are (e.g. the share
+carried by the top *n*).
+
+## Cohort and duration studies
+
+`cohort_summary`, `cohort_summary_by_period`, and `duration_summary` track experience by
+entry cohort and by duration since entry.
+
+## Driver and frequency-severity decomposition
+
+`component_driver_analysis`, `component_trend`, and `summarize_components` attribute
+movement to its components; `decompose_per_exposure_trend` splits a per-exposure trend into
+frequency and severity contributions, and `frequency_severity_summary` reports the two
+sides side by side.
+
+## Rolling monitors
+
+`rolling_summary` (and `Experience.rolling(window)`) produce trailing-window rollups for
+monitoring emerging experience.
+
+## Banded summaries
+
+`summarize_by_band` assigns rows to size bands (via `actuarialpy.assign_band`) and
+summarizes experience within each band, preserving band order and surfacing empty bands.
+
+## Relationship to actuarialpy
+
+`experiencestudies` depends on `actuarialpy` and never the other way around — the
+dependency is strictly one-directional. The size-banding split is the clearest example:
+the `assign_band` primitive lives in `actuarialpy`, while `summarize_by_band` (which needs
+an experience summary) lives here. Because the study layer imports from the primitive
+layer, publish a compatible `actuarialpy` (>= 0.42) before releasing a new
+`experiencestudies`.

experiencestudies-0.1.0/examples/README.md

@@ -0,0 +1,58 @@
+# experiencestudies examples
+
+Self-contained, runnable examples for the experience-analysis surfaces of
+`experiencestudies` and its fluent `Experience` object. Each script generates its own small
+synthetic data (via `_sample_data.py`) and prints a short report, so they run with nothing
+but the package installed:
+
+```bash
+pip install experiencestudies
+python renewal.py
+```
+
+Every script is standalone — run any one directly, in any order. They import the underlying
+primitives (`loss_ratio`, `completion_factors`, `fit_trend`, ...) from `actuarialpy` and the
+analysis layer (`Experience`, `decompose_per_exposure_trend`, ...) from `experiencestudies`.
+
+The walkthroughs are health-flavored (member-months, PMPM print labels) as a concrete book to
+work through; the core they exercise is domain-agnostic, and the domain vocabulary lives
+entirely in these callers.
+
+**Start here:** [`renewal.py`](renewal.py) is the end-to-end study — it threads the individual
+surfaces below into a single group renewal, from experience to indicated rate change. The
+others each focus on one surface.
+
+| Script | Surface | What it shows |
+|---|---|---|
+| `renewal.py` | **end-to-end** | a full group renewal: complete → trend → relativities (`adjust`) → pool large claimants → credibility-blend with the manual → load → `indicated_change` |
+| `experience_basics.py` | `Experience` facade, metrics | Bind roles once; `.by`, `.views`; metric primitives (`loss_ratio`, `per_exposure`, `pure_premium`) |
+| `claimant_concentration.py` | claimants, pooling | `claim_concentration`, `top_claimants`, `large_claimant_flags`, `pool_losses`, `excess_over_threshold` |
+| `restatement.py` | adjustments | `Experience.adjust` chain — scalar trend, per-region and per-line relativities, with a cumulative `audit_col` |
+| `rolling_trend_monitor.py` | rolling, decomposition | a monthly change-in-trend monitor: each evaluation month compares the trailing-12 window to the same window a year earlier via `decompose_per_exposure_trend`, reporting whether the year-over-year move is frequency- or severity-driven |
+| `trend_decomposition.py` | decomposition | `decompose_per_exposure_trend` two-way (frequency × severity), and the three-way `mix_by=` split — adds a mix term via LMDI, reconciling exactly; plus the `Experience.decompose_trend` facade (same split with columns bound once) |
+| `credibility.py` | credibility | `credibility_weighted_estimate`, `Experience.credibility_weighted` |
+| `lifecycle_and_banding.py` | lifecycle, banding | `derive_status`, `Experience.by_status`, `Experience.by_band` (banding via `actuarialpy.assign_band`) |
+
+## The sample data
+
+`_sample_data.py` (not part of the library) provides deterministic generators shared by these
+scripts:
+
+- **`sample_member_months()`** — a member-month experience frame spanning 2024–2025: claim
+  components, rebates, non-FFS expense, premium, per-group effective/termination dates, and a
+  subscriber count. A few members incur catastrophic claims so the concentration and pooling
+  examples have a real tail.
+- **`sample_seasonal_panel()`** — a monthly claims panel by line of business and product over
+  four years, with a real month-of-year seasonal pattern, membership growth, and a cost trend.
+- **`sample_trend_cells()`** — a deterministic two-period (2024/2025) claims panel split into
+  morbidity-segment × region cells, with uniform within-cell frequency (+3%) and unit-cost
+  (+4%) trend and an enrollment shift toward the High segment, so the book-wide two-way
+  overstates both drivers and the mix term recovers the difference; carries `claim_count`,
+  `allowed`, and `premium` for both the free `decompose_per_exposure_trend` and the
+  `Experience.decompose_trend` facade.
+
+## Note
+
+These build on the `actuarialpy` primitives and mirror the worked examples shipped alongside
+the sibling packages (`lossmodels`, `risksim`, `extremeloss`). For an end-to-end application
+that wires the packages together, see the high-cost-claimant cost-model project.