projectionmodels 0.1.0__py3-none-any.whl

projectionmodels/__init__.py

@@ -0,0 +1,50 @@
+"""
+projectionmodels -- forward projection (budgeting) for a book of business
+=========================================================================
+Part of the OpenActuarial ecosystem. Sits beside `ratingmodels` and `lossmodels`
+on top of the `actuarialpy` primitives layer, and depends only downward on
+`actuarialpy` -- never sideways on another workflow package.
+
+Rating builds a price from experience; projection takes the book AS IT IS -- stored
+premiums, historical claims, membership assumptions -- and rolls it forward for
+planning. The dividing line: the moment something computes what you *should* charge
+rather than what the projection *is*, it belongs in `ratingmodels`, not here.
+
+Layers
+------
+    PMPMProjection        credibility-blended, trended, pooled claims PMPM
+    PremiumRollforward    stored premium rolled forward by rate action / plan change
+    GroupProjection       one group: premium + claims + renewal weighting  (loop unit)
+    BookProjection        aggregate in-force renewals + new business -> book budget
+
+Each class computes on construction and exposes a frozen ``*Result`` dataclass via
+``.result``; a lowercase functional form (``project_group`` etc.) returns the result
+directly.
+
+Quick start
+-----------
+    from projectionmodels import GroupProjection, BookProjection
+
+    g = GroupProjection(prospective_membership=E, seasonal_factors=s,
+                        current_premium=..., current_member_months=...,
+                        rate_action=0.06, plan_change=-0.02,
+                        book_pmpm=..., claim_trend=0.06,
+                        exp_midpoint=..., prosp_midpoint=...,
+                        group_claims=..., group_member_months=..., group_claim_count=...,
+                        pooling_pmpm=..., renewal_prob=0.90)   # renewal likelihood from underwriting
+    book = BookProjection([g_1, g_2, new_biz], labels=[...])
+    book.loss_ratio
+"""
+from .pmpm import PMPMProjection, PMPMResult, project_pmpm
+from .premium import PremiumRollforward, PremiumResult, roll_forward_premium
+from .group import (GroupProjection, GroupProjectionResult, project_group, new_business)
+from .book import BookProjection, BookResult, project_book
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "PMPMProjection", "PMPMResult", "project_pmpm",
+    "PremiumRollforward", "PremiumResult", "roll_forward_premium",
+    "GroupProjection", "GroupProjectionResult", "project_group", "new_business",
+    "BookProjection", "BookResult", "project_book",
+]

projectionmodels/book.py

@@ -0,0 +1,65 @@
+"""
+Book projection -- aggregate group projections into the book budget.
+====================================================================
+Rolls up in-force renewals and new business into total premium, claims, and loss
+ratio (by group and by month). Totals use the EXPECTED (renewal-weighted) figures,
+so a group contributes in proportion to how likely it is to renew.
+"""
+from __future__ import annotations
+from dataclasses import dataclass
+import numpy as np
+import pandas as pd
+
+from .group import GroupProjection, GroupProjectionResult
+
+
+@dataclass(frozen=True)
+class BookResult:
+    premium: float                      # expected (renewal-weighted) book premium
+    claims: float
+    loss_ratio: float
+    by_group: pd.DataFrame              # per-group expected premium/claims/LR/renewal
+    monthly: pd.DataFrame               # expected premium/claims by month, summed over the book
+
+
+class BookProjection:
+    def __init__(self, projections, labels=None):
+        results = [p.result if isinstance(p, GroupProjection) else p for p in projections]
+        if not results:
+            raise ValueError("no projections supplied")
+        labels = list(labels) if labels is not None else [f"grp_{i}" for i in range(len(results))]
+
+        rows = []
+        prem_m = np.zeros(len(results[0].monthly))
+        clm_m = np.zeros_like(prem_m)
+        months = results[0].monthly["month"].to_numpy()
+        for lab, r in zip(labels, results):
+            rows.append({"group": lab, "premium": r.expected_premium, "claims": r.expected_claims,
+                         "loss_ratio": (r.expected_claims / r.expected_premium
+                                        if r.expected_premium else np.nan),
+                         "renewal_prob": r.renewal_prob})
+            prem_m += r.monthly["premium"].to_numpy() * r.renewal_prob
+            clm_m += r.monthly["claims"].to_numpy() * r.renewal_prob
+
+        by_group = pd.DataFrame(rows)
+        monthly = pd.DataFrame({"month": months, "premium": prem_m, "claims": clm_m})
+        monthly["loss_ratio"] = monthly["claims"] / monthly["premium"]
+        P, C = float(by_group["premium"].sum()), float(by_group["claims"].sum())
+        self.result = BookResult(premium=P, claims=C, loss_ratio=C / P,
+                                 by_group=by_group, monthly=monthly)
+
+    @property
+    def premium(self): return self.result.premium
+    @property
+    def claims(self): return self.result.claims
+    @property
+    def loss_ratio(self): return self.result.loss_ratio
+    @property
+    def by_group(self): return self.result.by_group
+    @property
+    def monthly(self): return self.result.monthly
+
+
+def project_book(projections, labels=None) -> BookResult:
+    """Functional form: returns the :class:`BookResult`."""
+    return BookProjection(projections, labels=labels).result

projectionmodels/group.py

@@ -0,0 +1,105 @@
+"""
+Group projection -- one group's forward roll, premium and claims together.
+==========================================================================
+Composes the premium roll-forward and the credibility-blended claims projection on
+the given monthly membership, then weights both by the renewal probability. This is
+the unit you loop over the in-force book (see :mod:`projectionmodels.book`).
+
+Renewal probability weights premium and claims equally (a lapsed group books
+neither), so the projected loss ratio is unaffected by it.
+"""
+from __future__ import annotations
+from dataclasses import dataclass
+import numpy as np
+import pandas as pd
+
+from .pmpm import PMPMProjection, PMPMResult
+from .premium import PremiumRollforward, PremiumResult
+
+
+@dataclass(frozen=True)
+class GroupProjectionResult:
+    monthly: pd.DataFrame               # month, member_months, premium, claims (conditional on renewal)
+    premium: float                      # conditional on renewal
+    claims: float
+    loss_ratio: float
+    renewal_prob: float
+    expected_premium: float             # renewal-weighted
+    expected_claims: float
+    pmpm: PMPMResult
+    premium_detail: PremiumResult
+
+
+class GroupProjection:
+    def __init__(self, *, prospective_membership, seasonal_factors=None,
+                 # premium (from DB)
+                 current_premium, current_member_months, rate_action=0.0, plan_change=0.0,
+                 # claims (group from DB + book)
+                 book_pmpm, claim_trend, exp_midpoint, prosp_midpoint,
+                 group_pmpm=None, group_claims=None, group_member_months=None,
+                 group_claim_count=None, credibility=None, full_credibility_claims=1082.0,
+                 pooling_pmpm=0.0, plan_affects_claims=True,
+                 # renewal likelihood -- supplied (e.g. from underwriting), not modelled here
+                 renewal_prob=1.0):
+        E = np.asarray(prospective_membership, float)
+        s = np.ones_like(E) if seasonal_factors is None else np.asarray(seasonal_factors, float)
+        plan_factor = (1.0 + plan_change) if plan_affects_claims else 1.0
+
+        prem = PremiumRollforward(current_premium=current_premium,
+                                  current_member_months=current_member_months,
+                                  rate_action=rate_action, plan_change=plan_change)
+        pmpm = PMPMProjection(book_pmpm=book_pmpm, claim_trend=claim_trend,
+                              exp_midpoint=exp_midpoint, prosp_midpoint=prosp_midpoint,
+                              group_pmpm=group_pmpm, group_claims=group_claims,
+                              group_member_months=group_member_months,
+                              group_claim_count=group_claim_count, credibility=credibility,
+                              full_credibility_claims=full_credibility_claims,
+                              plan_factor=plan_factor, pooling_pmpm=pooling_pmpm)
+
+        premium_m = prem.premium(E)
+        claims_m = pmpm.claims(E, s)
+        monthly = pd.DataFrame({"month": np.arange(1, len(E) + 1),
+                                "member_months": E.round().astype(int),
+                                "premium": premium_m, "claims": claims_m})
+        P, C = float(premium_m.sum()), float(claims_m.sum())
+        self.result = GroupProjectionResult(
+            monthly=monthly, premium=P, claims=C, loss_ratio=C / P, renewal_prob=renewal_prob,
+            expected_premium=renewal_prob * P, expected_claims=renewal_prob * C,
+            pmpm=pmpm.result, premium_detail=prem.result)
+
+    # convenient pass-through to the common result fields
+    @property
+    def monthly(self): return self.result.monthly
+    @property
+    def premium(self): return self.result.premium
+    @property
+    def claims(self): return self.result.claims
+    @property
+    def loss_ratio(self): return self.result.loss_ratio
+    @property
+    def expected_premium(self): return self.result.expected_premium
+    @property
+    def expected_claims(self): return self.result.expected_claims
+    @property
+    def renewal_prob(self): return self.result.renewal_prob
+
+
+def project_group(**kwargs) -> GroupProjectionResult:
+    """Functional form: returns the :class:`GroupProjectionResult`."""
+    return GroupProjection(**kwargs).result
+
+
+def new_business(*, book_pmpm, claim_trend, exp_midpoint, prosp_midpoint,
+                 prospective_membership, manual_premium_pmpm, seasonal_factors=None,
+                 close_ratio=1.0, plan_change=0.0, pooling_pmpm=0.0) -> GroupProjectionResult:
+    """A sold-but-new case: no experience, so claims are fully manual (credibility 0)
+    and premium is the manual/target rate on projected membership; `close_ratio`
+    plays the role of the renewal probability."""
+    E = np.asarray(prospective_membership, float)
+    return GroupProjection(
+        prospective_membership=E, seasonal_factors=seasonal_factors,
+        current_premium=manual_premium_pmpm * E.sum(), current_member_months=E.sum(),
+        rate_action=0.0, plan_change=plan_change,
+        book_pmpm=book_pmpm, claim_trend=claim_trend, exp_midpoint=exp_midpoint,
+        prosp_midpoint=prosp_midpoint, group_pmpm=book_pmpm, credibility=0.0,
+        pooling_pmpm=pooling_pmpm, renewal_prob=close_ratio).result

projectionmodels/pmpm.py

@@ -0,0 +1,70 @@
+"""
+PMPM projection -- the claims engine.
+=====================================
+Credibility-blends the group's own PMPM with the book PMPM, trends and
+plan-adjusts it, and adds a large-claim pooling load:
+
+    Z          from the group's claim count (limited fluctuation) unless supplied
+    blended    = Z * group_pmpm + (1 - Z) * book_pmpm
+    projected  = blended * trend * plan_factor + pooling_pmpm * trend
+
+`projected_pmpm` is a rate per member-month. Call `.claims(membership, seasonal)`
+to turn it into projected claim dollars by month; seasonality (factors averaging 1)
+redistributes across months without changing the annual total.
+"""
+from __future__ import annotations
+from dataclasses import dataclass
+import numpy as np
+import actuarialpy as ap
+from actuarialpy import credibility_weighted_estimate
+
+
+@dataclass(frozen=True)
+class PMPMResult:
+    group_pmpm: float
+    book_pmpm: float
+    credibility: float
+    blended_pmpm: float
+    trend_factor: float
+    plan_factor: float
+    pooling_pmpm: float
+    projected_pmpm: float
+
+
+class PMPMProjection:
+    def __init__(self, *, book_pmpm, claim_trend, exp_midpoint, prosp_midpoint,
+                 group_pmpm=None, group_claims=None, group_member_months=None,
+                 group_claim_count=None, credibility=None, full_credibility_claims=1082.0,
+                 plan_factor=1.0, pooling_pmpm=0.0):
+        if group_pmpm is None:
+            if group_claims is None or group_member_months is None:
+                raise ValueError("supply group_pmpm, or group_claims and group_member_months")
+            group_pmpm = ap.pure_premium(group_claims, group_member_months)
+        if credibility is None:
+            if group_claim_count is None:
+                raise ValueError("supply credibility, or group_claim_count to derive it")
+            credibility = min(float(ap.limited_fluctuation_z(group_claim_count, full_credibility_claims)), 1.0)
+
+        tf = float(ap.midpoint_trend_factor(exp_midpoint, prosp_midpoint, claim_trend))
+        blended = float(credibility_weighted_estimate(group_pmpm, book_pmpm, credibility))
+        projected = blended * tf * plan_factor + pooling_pmpm * tf
+        self.result = PMPMResult(
+            group_pmpm=float(group_pmpm), book_pmpm=float(book_pmpm),
+            credibility=float(credibility), blended_pmpm=blended, trend_factor=tf,
+            plan_factor=float(plan_factor), pooling_pmpm=float(pooling_pmpm),
+            projected_pmpm=float(projected))
+
+    @property
+    def projected_pmpm(self) -> float:
+        return self.result.projected_pmpm
+
+    def claims(self, membership, seasonal_factors=None):
+        """Projected claim dollars by prospective month."""
+        E = np.asarray(membership, float)
+        s = np.ones_like(E) if seasonal_factors is None else np.asarray(seasonal_factors, float)
+        return self.result.projected_pmpm * E * s
+
+
+def project_pmpm(**kwargs) -> PMPMResult:
+    """Functional form: returns the :class:`PMPMResult`."""
+    return PMPMProjection(**kwargs).result

projectionmodels/premium.py

@@ -0,0 +1,45 @@
+"""
+Premium roll-forward -- the stored premium projected by known factors.
+======================================================================
+Premiums come from the database; they are NOT rebuilt from loss experience (that is
+`ratingmodels`). This just rolls the stored figure forward:
+
+    projected_pmpm = (current_premium / current_member_months)
+                     * (1 + rate_action) * (1 + plan_change)
+
+Premium is level per member-month (it earns evenly), so `.premium(membership)`
+scales by membership with no seasonal shape -- unlike claims.
+"""
+from __future__ import annotations
+from dataclasses import dataclass
+import numpy as np
+
+
+@dataclass(frozen=True)
+class PremiumResult:
+    current_pmpm: float
+    rate_action: float
+    plan_change: float
+    projected_pmpm: float
+
+
+class PremiumRollforward:
+    def __init__(self, *, current_premium, current_member_months,
+                 rate_action=0.0, plan_change=0.0):
+        current_pmpm = current_premium / current_member_months
+        projected = current_pmpm * (1.0 + rate_action) * (1.0 + plan_change)
+        self.result = PremiumResult(float(current_pmpm), float(rate_action),
+                                    float(plan_change), float(projected))
+
+    @property
+    def projected_pmpm(self) -> float:
+        return self.result.projected_pmpm
+
+    def premium(self, membership):
+        """Projected premium dollars by prospective month (level per member-month)."""
+        return self.result.projected_pmpm * np.asarray(membership, float)
+
+
+def roll_forward_premium(**kwargs) -> PremiumResult:
+    """Functional form: returns the :class:`PremiumResult`."""
+    return PremiumRollforward(**kwargs).result

projectionmodels-0.1.0.dist-info/METADATA

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: projectionmodels
+Version: 0.1.0
+Summary: Forward projection (budgeting) for a book of business: premium roll-forward and credibility-blended, trended, seasonalized claims. Part of the OpenActuarial ecosystem.
+Project-URL: Homepage, https://github.com/OpenActuarial/projectionmodels
+Project-URL: Documentation, https://openactuarial.org/projectionmodels.html
+Project-URL: Repository, https://github.com/OpenActuarial/projectionmodels
+Project-URL: Issues, https://github.com/OpenActuarial/projectionmodels/issues
+Author: Michael Bryant
+License-Expression: MIT
+License-File: LICENSE
+Keywords: PMPM,actuarial,budgeting,forecasting,insurance,loss ratio,projection
+Classifier: Development Status :: 3 - Alpha
+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.40
+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
+
+# projectionmodels
+
+[![CI](https://github.com/OpenActuarial/projectionmodels/actions/workflows/ci.yml/badge.svg)](https://github.com/OpenActuarial/projectionmodels/actions/workflows/ci.yml) [![PyPI](https://img.shields.io/pypi/v/projectionmodels)](https://pypi.org/project/projectionmodels/)
+
+Forward projection (budgeting) for a book of business — part of the
+[OpenActuarial](https://openactuarial.org) ecosystem.
+
+`ratingmodels` builds a price from experience. `projectionmodels` does the opposite
+direction: it takes the book **as it is** — stored premiums, historical claims, and
+membership assumptions — and rolls it forward for planning and budgeting. It sits
+beside `ratingmodels` and `lossmodels` on top of the `actuarialpy` primitives layer,
+and depends only **downward** on `actuarialpy` — never sideways on another workflow
+package.
+
+## Install
+
+```bash
+pip install projectionmodels
+```
+
+## Layers
+
+| object | role |
+| --- | --- |
+| `PMPMProjection` | credibility-blended, trended, plan-adjusted claims PMPM with a pooling load |
+| `PremiumRollforward` | stored premium rolled forward by rate action and plan change |
+| `GroupProjection` | one group: premium + claims + renewal weighting — the unit you loop over the book |
+| `BookProjection` | aggregate in-force renewals + new business into the book budget |
+
+Each class computes on construction and exposes a frozen `*Result` dataclass via
+`.result`; a lowercase functional form (`project_group`, `project_book`, …) returns
+the result directly.
+
+## What it computes
+
+**Premium** is a stored value rolled forward (not rebuilt from experience), level
+per member-month:
+
+```
+prem_pmpm* = (current_premium / current_member_months) · (1 + rate_action) · (1 + plan_change)
+```
+
+**Claims** are the actuarial piece — a credibility blend of the group's own PMPM and
+the book PMPM, trended, plan-adjusted, and seasonalised onto the given membership:
+
+```
+Z         = limited-fluctuation credibility from the group's claim count
+blended   = Z · group_pmpm + (1 − Z) · book_pmpm
+projected = blended · trend · plan_factor + pooling_pmpm · trend
+claims_m  = projected · membership_m · seasonal_m
+```
+
+**Renewal probability** is supplied per group (e.g. from underwriting) via
+`renewal_prob` — it is an input, not something this package models. It weights
+premium and claims equally (a lapsed group books neither), so the projected loss
+ratio is unaffected. New business is the same `GroupProjection` with
+`group_pmpm = book_pmpm`, `credibility = 0`, and `renewal_prob = close_ratio`.
+
+## Quick start
+
+```python
+import numpy as np, pandas as pd
+from projectionmodels import GroupProjection, BookProjection
+
+g = GroupProjection(
+    prospective_membership=np.full(12, 1900.0), seasonal_factors=season_factors,
+    current_premium=4_500_000, current_member_months=21_600,
+    rate_action=0.06, plan_change=-0.02,
+    book_pmpm=180.0, claim_trend=0.06,
+    exp_midpoint=pd.Timestamp("2025-07-01"), prosp_midpoint=pd.Timestamp("2027-07-01"),
+    group_claims=3_800_000, group_member_months=21_600, group_claim_count=6_000,
+    pooling_pmpm=8.0, renewal_prob=0.90)   # renewal likelihood from underwriting
+
+book = BookProjection([g, ...], labels=["GroupA", ...])
+book.loss_ratio          # expected book loss ratio
+book.by_group            # per-group expected premium / claims / LR
+book.monthly             # book premium & claims by month
+```
+
+## Built on `actuarialpy`
+
+This package adds no primitives of its own — it composes existing `actuarialpy`
+primitives and depends only downward:
+
+- `credibility_weighted_estimate` — the credibility blend, `Z·group + (1−Z)·book`
+- `midpoint_trend_factor` — trend to the prospective midpoint
+- `seasonality_factors` / `apply_seasonality` — monthly seasonality
+- `pure_premium` — PMPM
+
+`pool_losses` / `excess_over_threshold` in `actuarialpy` cap large claims when you
+derive the pooling PMPM upstream.

projectionmodels-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+projectionmodels/__init__.py,sha256=ZU3bormnPaifAbIDpKc_-3XhdovhpbdLJ6a690brwYk,2485
+projectionmodels/book.py,sha256=eUSmccCLoHnUJr0roZr4bdrQTmyup6j74kaYMIKkbUM,2825
+projectionmodels/group.py,sha256=B0PzQCJZvYlp9iCax8vJ2Z4ez3tRVVjIXUCFglAOPBY,5246
+projectionmodels/pmpm.py,sha256=RCMnET4E-SnO-ofMT4V--vgxiunPcwfHvQjHV6_RnqY,3024
+projectionmodels/premium.py,sha256=Hx3lVm5XnTqSKB9MQ9ljpACy-CI7CnJQQMw-uhXWiZo,1687
+projectionmodels-0.1.0.dist-info/METADATA,sha256=SNoy0JitwJu50mwsK8bxKngtUC8WUnnHQnov0QQ1_8g,5631
+projectionmodels-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+projectionmodels-0.1.0.dist-info/licenses/LICENSE,sha256=2hvamn9mVK3WmUG9GyH0XLwvFoEkowbxsu4AZeCgf-g,1070
+projectionmodels-0.1.0.dist-info/RECORD,,

projectionmodels-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

projectionmodels-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenActuarial
+
+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.