ratingmodels 0.1.0__py3-none-any.whl

ratingmodels/__init__.py

@@ -0,0 +1,157 @@
+r"""ratingmodels -- actuarial pricing and rate-indication tools.
+
+A small, dependency-light toolkit for the group rating workflow: credibility,
+trend, manual and experience rate construction, credibility blending, rate
+indication, rate-change decomposition, GLM relativity estimation, and renewal
+constraints. Part of the OpenActuarial ecosystem.
+
+Quick start
+-----------
+>>> import ratingmodels as rm
+>>> exp = rm.ExperienceRate(
+...     incurred_claims=4_200_000, exposure=96_000,
+...     trend_annual=0.075, trend_years=1.5,
+...     pooled_excess=350_000, pooling_charge_pmpm=4.0,
+...     target_loss_ratio=0.85,
+... )
+>>> man = rm.ManualRate(base_pmpm=480, factors={"area": 1.05, "industry": 0.97})
+>>> z = rm.limited_fluctuation_credibility(n=96_000, n_full=120_000)
+>>> ind = rm.RateIndication(
+...     experience_claims_pmpm=exp.claims_pmpm(),
+...     manual_claims_pmpm=man.claims_pmpm(),
+...     credibility=z, current_rate=560, target_loss_ratio=0.85,
+...     trend_total_factor=exp.trend_factor(),
+... )
+>>> round(ind.indicated_rate_change(), 4)  # doctest: +SKIP
+"""
+from __future__ import annotations
+
+from .base_rate import (
+    BaseRateResult,
+    average_relativity,
+    base_rate_from_experience,
+    off_balance_factor,
+    rebalance_base_rate,
+)
+from .blend import blend
+from .buildup import (
+    BuildUp,
+    BuildUpResult,
+    Step,
+    add,
+    checkpoint,
+    combine_streams,
+    evaluate,
+    multiply,
+    participation_blend,
+    segment_multiply,
+    start,
+)
+from .constraints import apply_cap, band, cap_change, corridor, round_rate
+from .credibility import (
+    BuhlmannStraubResult,
+    buhlmann_credibility,
+    buhlmann_straub,
+    full_credibility_standard,
+    limited_fluctuation_credibility,
+)
+from .decomposition import RateChangeDecomposition, decompose_rate_change
+from .experience_rate import (
+    ExperienceRate,
+    expected_excess_charge,
+    pool_claims,
+)
+from .indication import RateIndication
+from .loading import (
+    RetentionLoad,
+    gross_rate,
+    permissible_loss_ratio,
+)
+from .manual_rate import (
+    ManualRate,
+    aggregate_demographic_factor,
+    manual_pmpm,
+)
+from .relativity import (
+    FactorTable,
+    GLMRelativities,
+    one_way_relativities,
+)
+from .renewal import RenewalAction, member_level_renewal, renew
+from .trend import (
+    apply_trend,
+    combine_trend,
+    period_midpoint,
+    split_total_trend,
+    trend_factor,
+    trend_factor_between,
+    years_between,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    # credibility
+    "full_credibility_standard",
+    "limited_fluctuation_credibility",
+    "buhlmann_credibility",
+    "buhlmann_straub",
+    "BuhlmannStraubResult",
+    # trend
+    "trend_factor",
+    "trend_factor_between",
+    "apply_trend",
+    "combine_trend",
+    "split_total_trend",
+    "period_midpoint",
+    "years_between",
+    # relativity
+    "FactorTable",
+    "one_way_relativities",
+    "GLMRelativities",
+    # manual / experience
+    "ManualRate",
+    "manual_pmpm",
+    "aggregate_demographic_factor",
+    "ExperienceRate",
+    "pool_claims",
+    "expected_excess_charge",
+    # base rate / off-balance
+    "base_rate_from_experience",
+    "BaseRateResult",
+    "average_relativity",
+    "off_balance_factor",
+    "rebalance_base_rate",
+    # build-up engine
+    "Step",
+    "start",
+    "multiply",
+    "add",
+    "segment_multiply",
+    "checkpoint",
+    "evaluate",
+    "BuildUp",
+    "BuildUpResult",
+    "participation_blend",
+    "combine_streams",
+    # retention / loading
+    "RetentionLoad",
+    "gross_rate",
+    "permissible_loss_ratio",
+    # blend / indication
+    "blend",
+    "RateIndication",
+    # decomposition
+    "decompose_rate_change",
+    "RateChangeDecomposition",
+    # constraints / renewal
+    "cap_change",
+    "apply_cap",
+    "band",
+    "round_rate",
+    "corridor",
+    "renew",
+    "RenewalAction",
+    "member_level_renewal",
+]

ratingmodels/_utils.py

@@ -0,0 +1,53 @@
+"""Internal helpers: validation and small numeric utilities."""
+from __future__ import annotations
+
+from typing import Iterable
+
+import numpy as np
+
+
+def as_float_array(x, name: str = "value") -> np.ndarray:
+    """Coerce to a 1-D float array, raising a clear error on bad input."""
+    arr = np.asarray(x, dtype=float)
+    if arr.ndim == 0:
+        arr = arr.reshape(1)
+    if arr.ndim != 1:
+        raise ValueError(f"{name} must be scalar or 1-D, got shape {arr.shape}")
+    if not np.all(np.isfinite(arr)):
+        raise ValueError(f"{name} contains non-finite values")
+    return arr
+
+
+def require_positive(x: float, name: str) -> float:
+    x = float(x)
+    if not np.isfinite(x) or x <= 0:
+        raise ValueError(f"{name} must be a positive finite number, got {x!r}")
+    return x
+
+
+def require_nonnegative(x: float, name: str) -> float:
+    x = float(x)
+    if not np.isfinite(x) or x < 0:
+        raise ValueError(f"{name} must be non-negative and finite, got {x!r}")
+    return x
+
+
+def require_unit_interval(x: float, name: str, *, closed: bool = True) -> float:
+    x = float(x)
+    lo_ok = (x >= 0) if closed else (x > 0)
+    hi_ok = (x <= 1) if closed else (x < 1)
+    if not (np.isfinite(x) and lo_ok and hi_ok):
+        bound = "[0, 1]" if closed else "(0, 1)"
+        raise ValueError(f"{name} must lie in {bound}, got {x!r}")
+    return x
+
+
+def product(values: Iterable[float]) -> float:
+    """Numerically stable product via logs when all positive, else direct."""
+    vals = list(values)
+    if not vals:
+        return 1.0
+    arr = np.asarray(vals, dtype=float)
+    if np.all(arr > 0):
+        return float(np.exp(np.sum(np.log(arr))))
+    return float(np.prod(arr))

ratingmodels/base_rate.py

@@ -0,0 +1,151 @@
+r"""Base-rate construction from book experience, with off-balancing.
+
+The base rate is the cost level for the reference cell (all relativities equal
+1). It is backed out from the book so that base times relativities reproduces
+the book's losses. For risks :math:`i` with exposure :math:`e_i`, relativity
+:math:`r_i = \prod_k f_{ki}`, and trended/developed loss :math:`L_i`:
+
+.. math::
+    \bar r = \frac{\sum_i e_i r_i}{\sum_i e_i}, \qquad
+    B = \frac{\sum_i L_i}{\sum_i e_i r_i} = \frac{\bar L}{\bar r}.
+
+By construction :math:`\sum_i e_i\, B r_i = \sum_i L_i`. When relativities are
+revised, the average relativity moves and the overall premium level drifts
+unless the base is **off-balanced**. Moving from average :math:`\bar r_0` to
+:math:`\bar r_1`, with an intended overall change :math:`\Delta`:
+
+.. math::
+    B_1 = B_0 \, \frac{\bar r_0}{\bar r_1} \, (1 + \Delta),
+
+where :math:`\bar r_0 / \bar r_1` is the off-balance correction that holds the
+book level neutral.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Sequence
+
+import numpy as np
+import pandas as pd
+
+from ._utils import product, require_positive
+
+
+@dataclass
+class BaseRateResult:
+    """Result of :func:`base_rate_from_experience`."""
+
+    base_loss_cost: float
+    average_relativity: float
+    average_loss_cost: float
+    total_exposure: float
+
+    def __repr__(self) -> str:  # pragma: no cover - cosmetic
+        return (
+            f"BaseRateResult(base_loss_cost={self.base_loss_cost:.4f}, "
+            f"average_relativity={self.average_relativity:.4f}, "
+            f"average_loss_cost={self.average_loss_cost:.4f})"
+        )
+
+
+def _relativity_vector(
+    data: pd.DataFrame,
+    relativity: str | None,
+    factor_cols: Sequence[str] | None,
+) -> np.ndarray:
+    if relativity is not None:
+        rel = data[relativity].to_numpy(dtype=float)
+    elif factor_cols:
+        rel = np.array(
+            [product(row[c] for c in factor_cols) for _, row in data.iterrows()],
+            dtype=float,
+        )
+    else:
+        raise ValueError("provide either `relativity` or `factor_cols`")
+    if np.any(rel <= 0):
+        raise ValueError("relativities must be positive")
+    return rel
+
+
+def average_relativity(
+    data: pd.DataFrame,
+    exposure: str,
+    relativity: str | None = None,
+    factor_cols: Sequence[str] | None = None,
+) -> float:
+    r"""Exposure-weighted average relativity :math:`\bar r = \sum e_i r_i / \sum e_i`.
+
+    Supply relativities either as a single ``relativity`` column or as
+    ``factor_cols`` (per-row factors that are multiplied together).
+    """
+    e = data[exposure].to_numpy(dtype=float)
+    if np.any(e <= 0):
+        raise ValueError("exposures must be positive")
+    rel = _relativity_vector(data, relativity, factor_cols)
+    return float(np.sum(e * rel) / np.sum(e))
+
+
+def base_rate_from_experience(
+    data: pd.DataFrame,
+    exposure: str,
+    loss: str,
+    relativity: str | None = None,
+    factor_cols: Sequence[str] | None = None,
+) -> BaseRateResult:
+    r"""Indicated base loss cost from book experience (off-balance method).
+
+    Returns :math:`B = \sum_i L_i / \sum_i e_i r_i` together with the average
+    relativity and average loss cost. Gross ``base_loss_cost`` to a charged base
+    rate with a :class:`ratingmodels.RetentionLoad`.
+
+    Parameters
+    ----------
+    data : DataFrame
+        One row per risk or rating cell.
+    exposure, loss : str
+        Column names for exposure (e.g. member-months) and trended/developed
+        loss.
+    relativity : str, optional
+        Column of precomputed relativities :math:`r_i`.
+    factor_cols : sequence of str, optional
+        Columns of individual rating factors to multiply into :math:`r_i`
+        (used when ``relativity`` is not supplied).
+    """
+    e = data[exposure].to_numpy(dtype=float)
+    if np.any(e <= 0):
+        raise ValueError("exposures must be positive")
+    losses = data[loss].to_numpy(dtype=float)
+    rel = _relativity_vector(data, relativity, factor_cols)
+
+    total_exposure = float(np.sum(e))
+    exposure_weighted_rel = float(np.sum(e * rel))  # = sum(e_i r_i)
+    base = float(np.sum(losses) / exposure_weighted_rel)
+    return BaseRateResult(
+        base_loss_cost=base,
+        average_relativity=exposure_weighted_rel / total_exposure,
+        average_loss_cost=float(np.sum(losses) / total_exposure),
+        total_exposure=total_exposure,
+    )
+
+
+def off_balance_factor(current_avg_relativity: float, new_avg_relativity: float) -> float:
+    r"""Off-balance correction :math:`\bar r_0 / \bar r_1` from revising relativities."""
+    require_positive(current_avg_relativity, "current_avg_relativity")
+    require_positive(new_avg_relativity, "new_avg_relativity")
+    return current_avg_relativity / new_avg_relativity
+
+
+def rebalance_base_rate(
+    current_base: float,
+    current_avg_relativity: float,
+    new_avg_relativity: float,
+    overall_change: float = 0.0,
+) -> float:
+    r"""Off-balanced new base rate :math:`B_1 = B_0 (\bar r_0/\bar r_1)(1+\Delta)`.
+
+    Holds the overall premium level neutral when relativities change, then
+    applies the intended overall rate change ``overall_change`` (:math:`\Delta`).
+    """
+    require_positive(current_base, "current_base")
+    factor = off_balance_factor(current_avg_relativity, new_avg_relativity)
+    return current_base * factor * (1.0 + overall_change)

ratingmodels/blend.py

@@ -0,0 +1,20 @@
+r"""Credibility blending of experience and manual quantities.
+
+.. math::
+    \text{blended} = Z \cdot \text{experience} + (1 - Z)\cdot \text{manual}.
+
+This is the atomic credibility-weighting operation; it delegates to
+:func:`actuarialpy.credibility_weighted_estimate` so the primitive lives in one
+place across the ecosystem.
+"""
+from __future__ import annotations
+
+import actuarialpy as ap
+
+from ._utils import require_unit_interval
+
+
+def blend(experience: float, manual: float, credibility: float) -> float:
+    r""":math:`Z \cdot \text{experience} + (1-Z)\cdot \text{manual}`."""
+    z = require_unit_interval(credibility, "credibility")
+    return ap.credibility_weighted_estimate(experience, manual, z)

ratingmodels/buildup.py

@@ -0,0 +1,253 @@
+r"""Ordered rate build-up with an audit trail.
+
+Every group rate is assembled the same way: start from a base claim cost and
+apply an ordered sequence of operations -- multiply by a relativity, add or
+subtract a dollar amount (a copay credit, a per-member fee), apply a factor to
+only a segment of the cost -- recording labeled subtotals along the way, then
+combine streams (in-/out-of-network by participation, medical + drug). This
+module provides that grammar; it ships **no factor values**. The numbers are
+yours (filed tables, state amounts, vendor fees); the engine just applies them
+and produces a reconciling, auditable breakdown.
+
+Operations
+----------
+* ``start(label, value)``      -- set the running total.
+* ``multiply(label, factor)``  -- ``running *= factor`` (a relativity / trend).
+* ``add(label, amount)``       -- ``running += amount`` (copay credit < 0, fee > 0).
+* ``segment_multiply(label, factor, weight)`` -- apply ``factor`` to a fraction
+  ``weight`` of the running total:
+  :math:`\text{running} \leftarrow \text{running}\,(1 - w + w f)`.
+* ``checkpoint(label)``        -- record a labeled subtotal; total unchanged.
+
+Combining streams
+-----------------
+* :func:`participation_blend` -- :math:`\text{par}\,p + \text{nonpar}\,(1-p)`.
+* :func:`combine_streams`     -- additive combine (e.g. medical + drug).
+
+Both return a :class:`BuildUpResult`, so intermediate results carry their own
+breakdown and can be fed into credibility, trend, and retention.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Mapping, Sequence, Union
+
+import numpy as np
+import pandas as pd
+
+_BREAKDOWN_COLUMNS = ["step", "operation", "label", "operand", "running_total"]
+
+
+@dataclass(frozen=True)
+class Step:
+    """A single build-up operation. ``operand`` is the factor (multiply /
+    segment), amount (add), or value (start); ``weight`` is used by
+    ``segment_multiply`` only."""
+
+    op: str
+    label: str
+    operand: float = 1.0
+    weight: float = 1.0
+
+
+def start(label: str, value: float) -> Step:
+    """Set the running total to ``value`` (normally the first step)."""
+    return Step("start", label, float(value))
+
+
+def multiply(label: str, factor: float) -> Step:
+    """Multiply the running total by ``factor`` (a relativity or trend)."""
+    return Step("multiply", label, float(factor))
+
+
+def add(label: str, amount: float) -> Step:
+    """Add ``amount`` to the running total (negative for a copay credit)."""
+    return Step("add", label, float(amount))
+
+
+def segment_multiply(label: str, factor: float, weight: float) -> Step:
+    r"""Apply ``factor`` to a fraction ``weight`` of the running total.
+
+    :math:`\text{running} \leftarrow \text{running}\,(1 - w + w f)`.
+    """
+    if not 0.0 <= weight <= 1.0:
+        raise ValueError("weight must lie in [0, 1]")
+    return Step("segment_multiply", label, float(factor), float(weight))
+
+
+def checkpoint(label: str) -> Step:
+    """Record a labeled subtotal without changing the running total."""
+    return Step("checkpoint", label, float("nan"))
+
+
+@dataclass
+class BuildUpResult:
+    """Result of evaluating a build-up.
+
+    Attributes
+    ----------
+    value : float
+        Final running total.
+    breakdown : pandas.DataFrame
+        One row per step: ``step, operation, label, operand, running_total``.
+        For ``segment_multiply`` the ``operand`` shown is the *effective*
+        factor :math:`(1 - w + w f)`, so the column reconciles by multiplication.
+    subtotals : dict
+        Ordered mapping of checkpoint label -> running total at that point.
+    steps : list[Step]
+        The raw steps (nominal factor and weight preserved).
+    """
+
+    value: float
+    breakdown: pd.DataFrame
+    subtotals: dict
+    steps: list = field(default_factory=list, repr=False)
+
+    def subtotal(self, label: str) -> float:
+        """Running total recorded at the named checkpoint."""
+        if label not in self.subtotals:
+            raise KeyError(f"no checkpoint labeled {label!r}")
+        return self.subtotals[label]
+
+    def to_frame(self) -> pd.DataFrame:
+        return self.breakdown
+
+    def __repr__(self) -> str:  # pragma: no cover - cosmetic
+        return f"BuildUpResult(value={self.value:.4f}, steps={len(self.steps)})"
+
+
+def evaluate(steps: Sequence[Step]) -> BuildUpResult:
+    """Run an ordered sequence of :class:`Step` and return a :class:`BuildUpResult`.
+
+    The running total starts at 0; a leading :func:`start` sets the base.
+    """
+    running = 0.0
+    rows = []
+    subtotals: dict = {}
+    for i, s in enumerate(steps, start=1):
+        if s.op == "start":
+            running = s.operand
+            shown = s.operand
+        elif s.op == "multiply":
+            running *= s.operand
+            shown = s.operand
+        elif s.op == "add":
+            running += s.operand
+            shown = s.operand
+        elif s.op == "segment_multiply":
+            effective = 1.0 - s.weight + s.weight * s.operand
+            running *= effective
+            shown = effective
+        elif s.op == "checkpoint":
+            subtotals[s.label] = running
+            shown = np.nan
+        else:
+            raise ValueError(f"unknown operation {s.op!r}")
+        rows.append(
+            {
+                "step": i,
+                "operation": s.op,
+                "label": s.label,
+                "operand": shown,
+                "running_total": running,
+            }
+        )
+    breakdown = pd.DataFrame(rows, columns=_BREAKDOWN_COLUMNS)
+    return BuildUpResult(
+        value=float(running),
+        breakdown=breakdown,
+        subtotals=subtotals,
+        steps=list(steps),
+    )
+
+
+class BuildUp:
+    """Fluent builder for a build-up; sugar over a list of :class:`Step`.
+
+    >>> r = (BuildUp()
+    ...      .start("Par Base", 941.63)
+    ...      .add("$30 specialist copay", -11.44)
+    ...      .multiply("Rating Region", 1.083)
+    ...      .checkpoint("Medical Par Base Claim Cost")
+    ...      .evaluate())
+    """
+
+    def __init__(self) -> None:
+        self._steps: list[Step] = []
+
+    def start(self, label: str, value: float) -> "BuildUp":
+        self._steps.append(start(label, value))
+        return self
+
+    def multiply(self, label: str, factor: float) -> "BuildUp":
+        self._steps.append(multiply(label, factor))
+        return self
+
+    def add(self, label: str, amount: float) -> "BuildUp":
+        self._steps.append(add(label, amount))
+        return self
+
+    def segment_multiply(self, label: str, factor: float, weight: float) -> "BuildUp":
+        self._steps.append(segment_multiply(label, factor, weight))
+        return self
+
+    def checkpoint(self, label: str) -> "BuildUp":
+        self._steps.append(checkpoint(label))
+        return self
+
+    def steps(self) -> list:
+        return list(self._steps)
+
+    def evaluate(self) -> BuildUpResult:
+        return evaluate(self._steps)
+
+
+# --------------------------------------------------------------------------- #
+# combining streams
+# --------------------------------------------------------------------------- #
+ValueLike = Union[BuildUpResult, float]
+
+
+def _val(x: ValueLike) -> float:
+    return float(x.value) if isinstance(x, BuildUpResult) else float(x)
+
+
+def combine_streams(
+    streams: Mapping[str, ValueLike],
+    label: str = "Combined",
+) -> BuildUpResult:
+    """Additively combine named streams (e.g. ``{"Medical": ..., "Drug": ...}``).
+
+    Implemented as a build-up (start + adds) so the result carries a running
+    total and an audit trail.
+    """
+    items = list(streams.items())
+    if not items:
+        raise ValueError("provide at least one stream")
+    steps = [start(items[0][0], _val(items[0][1]))]
+    for lab, v in items[1:]:
+        steps.append(add(lab, _val(v)))
+    steps.append(checkpoint(label))
+    return evaluate(steps)
+
+
+def participation_blend(
+    par: ValueLike,
+    nonpar: ValueLike,
+    participation_rate: float,
+    label: str = "PPO Claim Cost",
+) -> BuildUpResult:
+    r"""In-/out-of-network blend :math:`\text{par}\,p + \text{nonpar}\,(1-p)`.
+
+    ``participation_rate`` is the in-network (par) share ``p``.
+    """
+    if not 0.0 <= participation_rate <= 1.0:
+        raise ValueError("participation_rate must lie in [0, 1]")
+    p = participation_rate
+    return combine_streams(
+        {
+            f"Par x {p:.1%}": _val(par) * p,
+            f"Non-Par x {1 - p:.1%}": _val(nonpar) * (1 - p),
+        },
+        label=label,
+    )

ratingmodels/constraints.py

@@ -0,0 +1,58 @@
+r"""Constraints applied to indicated rates before they become rate actions.
+
+Indicated rates are rarely charged as-is. Common adjustments:
+
+* **Caps / floors** on the rate change to limit renewal shock.
+* **Banding** -- snapping small changes to zero, or to discrete steps.
+* **Rounding** to a filed precision.
+* **Corridors** -- limiting how far a rate may move over successive renewals.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+
+def cap_change(change: float, cap: float | None = None, floor: float | None = None) -> float:
+    """Clip a proportional rate change to ``[floor, cap]`` (either may be None)."""
+    out = float(change)
+    if cap is not None:
+        out = min(out, float(cap))
+    if floor is not None:
+        out = max(out, float(floor))
+    return out
+
+
+def apply_cap(
+    current_rate: float,
+    indicated_rate: float,
+    cap: float | None = None,
+    floor: float | None = None,
+) -> float:
+    """Return the charged rate after capping the implied change."""
+    if current_rate <= 0:
+        raise ValueError("current_rate must be positive")
+    change = indicated_rate / current_rate - 1.0
+    return current_rate * (1.0 + cap_change(change, cap, floor))
+
+
+def band(change: float, deadband: float = 0.0, step: float | None = None) -> float:
+    """Snap a change to zero within ``deadband``; optionally to ``step`` grid."""
+    out = 0.0 if abs(change) <= deadband else float(change)
+    if step is not None and step > 0:
+        out = round(out / step) * step
+    return out
+
+
+def round_rate(rate: float, ndigits: int = 2) -> float:
+    """Round a rate to a filed precision (default cents)."""
+    return float(np.round(rate, ndigits))
+
+
+def corridor(
+    current_rate: float,
+    indicated_rate: float,
+    max_up: float,
+    max_down: float,
+) -> float:
+    """Limit a single renewal move to ``[-max_down, +max_up]`` proportionally."""
+    return apply_cap(current_rate, indicated_rate, cap=max_up, floor=-abs(max_down))