Files
stack/src/lead/benchmark.py
kert cb9976e160
All checks were successful
CI / lint (push) Successful in 44s
CI / notebooks-smoke (push) Successful in 1m33s
Deploy / changes (push) Successful in 14s
CI / test (push) Successful in 3m9s
Infra CI / zotero (push) Successful in 14s
Infra CI / notebooks (push) Successful in 55s
Infra CI / api (push) Successful in 1m9s
Infra CI / docs (push) Successful in 1m23s
Infra CI / llm (push) Successful in 1m1s
Infra CI / mc (push) Successful in 16s
Infra CI / bcda (push) Successful in 1m43s
Deploy / notebooks (push) Has been skipped
Deploy / zotero (push) Has been skipped
Deploy / docs (push) Has been skipped
Package Supply Chain / pkg-supply-chain (push) Successful in 1m30s
Deploy / api (push) Successful in 1m17s
Deploy / llm (push) Successful in 1m18s
Deploy / mc (push) Has been skipped
Deploy / bcda (push) Successful in 1m42s
Deploy / report (push) Successful in 1m36s
feat(lead): LEAD PY2027 financial methodology — settlement and benchmark engines
Ports the public CMS "LEAD Model PY 2027 Alignment and Financial
Methodology Paper" v1.2 (bib E4PEU3HV) as generic engines: parameters
come from the paper, everything CMS computes per ACO or per year comes
from the caller. No participant data, no organization-specific rules.

- lead.params: Table 5.2.1 discounts, 3% Quality Withhold, 2% retention
  incentive, Box 5.3.3 Stop-Loss bands, Tables 5.4.1/5.4.3 corridors, 2%
  sequestration, base-year weights, Table 3.5.1 ACPT guardrails,
  risk-score growth caps, REA/PSA shares and caps, voluntary guardrail
  and 500 minimum, Table 2.6.1 base-year alignment minimums.
- lead.settlement: Final Financial Settlement, Table 5.6.1 line by line
  (settle(SettlementInputs) -> SettlementLines).
- lead.stop_loss: Box 5.3.3 charge, banded payout, neutrality factor,
  application to PY expenditure.
- lead.monies_owed: Table 5.5.1 Total Monies Owed, APO reconciliation.
- lead.timing: run-out end, settlement-basis rule, settlement-stage inputs.
- lead.benchmark: §3 formulas — risk standardization, two-/three-way
  trend, base-year weights and sufficiency, voluntary guardrail,
  regional FFS, spending designation, REA, PSA, risk-score cap, hybrid
  alignment dollars, category blend.
- lead.express: the same as narwhals Exprs; express.settlement.settle
  settles a frame of scenarios on any backend.

Rounding: every dollar line rounds to the cent (half away from zero) as
it is produced; PBPMs, rates and factors never do. It is the only rule
under which Tables 3.3.3, 3.5.3.2, 3.5.4, 5.5.1 and 5.6.1 all reproduce
(3.5.4 line 24 sums cent-rounded cells; 3.3.3 carries unrounded PBPMs).
The Expr cents snaps its ÷100 with round(2): polars 2.0 divides a column
by a literal as a reciprocal multiply (k × 0.01), one ulp off k/100 for
~15% of values.

Missing inputs stay missing (None/null or a refused input model); the
only zeros are the paper's own (Professional "N/A" discount, no
Stop-Loss election, sequestration on losses, ineligible REA/PSA).

Paper inconsistencies recorded in tests: Table 5.5.1 line 2 is a cent
below Table 5.6.1 line 28 (.43 vs .44); Box 3.3.2 prints 1.104 then says
1.103; §3.5.1 prose widens the ACPT lower bound a year later than
Table 3.5.1 (the table is followed).

Tests: 283 in tests/lead — every published line to the cent, Expr
builders on polars and DuckDB, bit-for-bit scalar/frame parity over 160
scenarios; 100% of src/lead.
2026-10-27 14:11:10 -04:00

653 lines
23 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
"""LEAD Performance Year Benchmark formulas (§3), as published.
The order: Historical Baseline Expenditure PBPMs are risk standardized
(§3.3.1), trended to BY 3 with the national-regional blend (§3.3.2) and
weighted by base year (§3.3.3–3.3.4) into the Historical Benchmark; the
voluntary guardrail applies (§3.2.5); a Regional Efficiency Adjustment or
Prior Savings Adjustment is added (§3.4); the Adjusted Historical
Benchmark is trended with the three-way blend (§3.5.1), risk adjusted with
the growth-capped PY risk score (§3.5.2), multiplied out over full-year and
hybrid-aligned months (§3.5.3), and the categories summed (§3.5.4).
Only the arithmetic CMS publishes is here. Every data-derived input —
expenditures, risk scores, months, ACPT, modified USPCC amounts, hybrid
factors, CMS's alignment-standard and SSP-TIN determinations — is a caller
input. PBPMs, rates and factors are never rounded; dollar totals are
rounded to the cent (:func:`lead.money.cents`), which is what reproduces
Table 3.5.4 line 24.
Missing inputs give ``None``, never a stand-in value: a growth rate,
market share or PBPM without a positive denominator is None, and so is
anything computed from it.
Source: LEAD PY2027 methodology (bib E4PEU3HV) §3.
"""
from __future__ import annotations
from collections.abc import Iterable, Mapping, Sequence
from dataclasses import dataclass
from lead.money import cents
from lead.params import (
ACPT_GUARDRAILS,
ACPT_WEIGHT,
BASE_YEAR_ALIGNMENT_MINIMUMS,
BASE_YEAR_WEIGHTS,
BASE_YEARS,
BENCHMARK_ADJUSTMENT_CAP_RATE,
GLOBAL,
HIGHER_SPENDING,
LOWER_SPENDING,
NEWLY_ENTERING,
PRIOR_SAVINGS_PRORATION_CAP,
PRIOR_SAVINGS_SHARE,
REDUCED_BENCHMARK_ADJUSTMENT_CAP_RATE,
REGIONAL_EFFICIENCY_SHARE,
RISK_SCORE_GROWTH_CAPS,
VOLUNTARY_BENCHMARK_MINIMUM,
VOLUNTARY_GUARDRAIL_RATE,
AlignmentMinimumType,
BeneficiaryCategory,
EntryType,
RiskOption,
SpendingDesignation,
model_year,
)
# ── Shared arithmetic ─────────────────────────────────────────────────────
def ratio(numerator: float | None, denominator: float | None) -> float | None:
"""Return numerator ÷ denominator, or None unless both are known and
the denominator is positive.
Source: LEAD PY2027 methodology (bib E4PEU3HV) §3 (every ratio it
defines has a positive denominator).
"""
if numerator is None or denominator is None or denominator <= 0:
return None
return numerator / denominator
def month_weighted_average(
values_and_months: Iterable[tuple[float | None, float | None]],
) -> float | None:
"""Return the beneficiary month-weighted average of the values.
Pairs with a missing value or no positive months carry no weight; with
no weight at all the result is None. This is the paper's average risk
score, its claims/voluntary PBPM combination, its weighted REA for
excluded TINs and Box 5.3.3's month-weighted Stop-Loss values.
Source: LEAD PY2027 methodology (bib E4PEU3HV) §3.3.1 / §3.5.2 /
§3.5.4 / Table 3.4.3.6 / Box 5.3.3.
"""
weighted = 0.0
months = 0.0
for value, weight in values_and_months:
if value is None or weight is None or weight <= 0:
continue
weighted += value * weight
months += weight
return ratio(weighted, months)
# ── §3.3 Risk standardize, trend, weight ──────────────────────────────────
def expenditure_pbpm(total_expenditure: float, eligible_months: float) -> float | None:
"""Return expenditure per beneficiary per month (Table 3.3.3 line 3).
Source: LEAD PY2027 methodology (bib E4PEU3HV) §3.3 / Table 3.3.3 line 3.
"""
return ratio(total_expenditure, eligible_months)
def risk_standardize(
pbpm: float | None, average_risk_score: float | None
) -> float | None:
"""Divide a PBPM by the same population's average risk score for the
same year (Table 3.3.3 line 5).
Source: LEAD PY2027 methodology (bib E4PEU3HV) §3.3.1 / Table 3.3.3 line 5.
"""
return ratio(pbpm, average_risk_score)
def growth_rate(later: float | None, earlier: float | None) -> float | None:
"""Return a growth rate later ÷ earlier: BY 3 ÷ BY n FFS expenditures,
national (Step 1) or regional (Step 2). None unless both are positive.
Source: LEAD PY2027 methodology (bib E4PEU3HV) Box 3.3.2 Steps 1–2.
"""
if later is None or later <= 0:
return None
return ratio(later, earlier)
def national_trend_weight(
counties: Sequence[tuple[float, float]],
) -> float | None:
"""Return the weight on the national growth rate: the ACO's
county-weighted average market share.
Each county is (ACO-aligned months, alignment-eligible months). Market
share = aligned ÷ eligible; county weight = aligned ÷ ACO total aligned;
the national weight is Σ share × weight. None without aligned months or
when a county has no eligible months.
Source: LEAD PY2027 methodology (bib E4PEU3HV) Box 3.3.2 Step 3.
"""
total_aligned = sum(aligned for aligned, _ in counties)
weight_sum = 0.0
for aligned, eligible in counties:
share = ratio(aligned, eligible)
weight = ratio(aligned, total_aligned)
if share is None or weight is None:
return None
weight_sum += share * weight
return weight_sum if counties else None
def two_way_blended_trend(
national_growth: float | None,
regional_growth: float | None,
national_weight: float | None,
) -> float | None:
"""Blend the growth rates: national × weight + regional × (1 − weight).
Box 3.3.2's example gives 1.120 × 18% + 1.100 × 82% = 1.1036 (printed
1.104; its next sentence says 1.103, a slip in the paper).
Source: LEAD PY2027 methodology (bib E4PEU3HV) Box 3.3.2 Step 4.
"""
if national_growth is None or regional_growth is None or national_weight is None:
return None
return national_growth * national_weight + regional_growth * (1.0 - national_weight)
def base_year_weights(
entry_type: EntryType, sufficient_base_years: Iterable[str]
) -> dict[str, float]:
"""Return the weight of each sufficient base year.
Three sufficient years: 10/30/60 (Newly Entering) or equal thirds
(Renewing). Two: two-thirds recent / one-third older (Newly Entering)
or equal halves (Renewing). One: 100 percent. None sufficient: an empty
mapping — no Historical Benchmark can be built.
Source: LEAD PY2027 methodology (bib E4PEU3HV) §3.3.3 / §3.3.4.
"""
if entry_type not in BASE_YEAR_WEIGHTS:
raise ValueError(f"unknown entry type {entry_type!r}")
sufficient = set(sufficient_base_years)
unknown = sufficient - set(BASE_YEARS)
if unknown:
raise ValueError(f"unknown base years {sorted(unknown)}")
years = [year for year in BASE_YEARS if year in sufficient]
if len(years) == 3:
return dict(BASE_YEAR_WEIGHTS[entry_type])
if len(years) == 2:
older, recent = years
if entry_type == NEWLY_ENTERING:
return {older: 1 / 3, recent: 2 / 3}
return {older: 0.5, recent: 0.5}
return {year: 1.0 for year in years}
def base_year_alignment_minimum(
standard: AlignmentMinimumType, performance_year: int
) -> int:
"""Return the claims-based alignment minimum a base year must meet, for
the alignment standard CMS assigned the ACO and the PY.
Source: LEAD PY2027 methodology (bib E4PEU3HV) §2.6 / Table 2.6.1.
"""
return BASE_YEAR_ALIGNMENT_MINIMUMS[standard][model_year(performance_year) - 1]
def base_year_is_sufficient(
claims_aligned_beneficiaries: int,
standard: AlignmentMinimumType,
performance_year: int,
) -> bool:
"""Whether a base year has sufficient claims history: ACO-level
claims-based alignment meets or exceeds the Table 2.6.1 minimum.
Source: LEAD PY2027 methodology (bib E4PEU3HV) §3.3.4.
"""
return claims_aligned_beneficiaries >= base_year_alignment_minimum(
standard, performance_year
)
def historical_benchmark(
risk_standardized_pbpm: Mapping[str, float],
trend_to_by3: Mapping[str, float],
weights: Mapping[str, float],
) -> float | None:
"""Return the Historical Benchmark PBPM: Σ risk-standardized PBPM ×
trend to BY 3 × base-year weight over the weighted base years.
BY 3's trend factor is 1.000. None when a weighted year lacks its PBPM
or trend, or when no year is weighted.
Source: LEAD PY2027 methodology (bib E4PEU3HV) §3.3.3 / Table 3.3.3
lines 5–9.
"""
if not weights:
return None
total = 0.0
for year, weight in weights.items():
pbpm = risk_standardized_pbpm.get(year)
trend = trend_to_by3.get(year)
if pbpm is None or trend is None:
return None
total += pbpm * trend * weight
return total
# ── §3.2.5 Voluntarily aligned benchmarks ─────────────────────────────────
WITHIN_GUARDRAIL = "within_voluntary_guardrail"
CAPPED_AT_UPPER = "capped_at_110_percent_of_claims_aligned"
RAISED_TO_LOWER = "raised_to_90_percent_of_claims_aligned"
def voluntary_guardrail(
voluntary_historical_pbpm: float,
claims_historical_pbpm: float,
rate: float = VOLUNTARY_GUARDRAIL_RATE,
) -> tuple[float, str]:
"""Hold the voluntarily aligned Historical Benchmark within ±10 percent
of the claims-aligned one for the same category, after base-year
blending and before any REA or PSA. Returns (benchmark, status).
Source: LEAD PY2027 methodology (bib E4PEU3HV) §3.2.5 ($1,000 claims →
$900–$1,100).
"""
lower = claims_historical_pbpm * (1.0 - rate)
upper = claims_historical_pbpm * (1.0 + rate)
if voluntary_historical_pbpm > upper:
return upper, CAPPED_AT_UPPER
if voluntary_historical_pbpm < lower:
return lower, RAISED_TO_LOWER
return voluntary_historical_pbpm, WITHIN_GUARDRAIL
def contributes_to_voluntary_benchmark(
category: BeneficiaryCategory, by3_category: BeneficiaryCategory | None
) -> bool:
"""Whether a voluntarily aligned beneficiary contributes base-year
expenditures (and counts toward the 500 minimum): every A&D and ESRD
beneficiary, and a High Needs one only if High Needs in BY 3.
Source: LEAD PY2027 methodology (bib E4PEU3HV) §3.2.5.
"""
return category != "High Needs" or by3_category == "High Needs"
def voluntary_benchmark_minimum_met(contributing_beneficiaries: int) -> bool:
"""Whether at least 500 contributing voluntarily aligned beneficiaries
exist; otherwise the claims-aligned benchmarks apply to them.
Source: LEAD PY2027 methodology (bib E4PEU3HV) §3.2.5.
"""
return contributing_beneficiaries >= VOLUNTARY_BENCHMARK_MINIMUM
# ── §3.4 ACO-specific benchmark adjustments ───────────────────────────────
def regional_ffs_expenditure(
counties: Sequence[tuple[float | None, float | None, float]],
) -> float | None:
"""Return regional FFS expenditure: Σ county weight × risk-standardized
county FFS PBPM.
Each county is (county PBPM FFS expenditure, county average risk score,
ACO-aligned months in the county); the weight is the county's share of
the ACO's aligned months. None if any county lacks a PBPM or score, or
the ACO has no aligned months.
Source: LEAD PY2027 methodology (bib E4PEU3HV) §3.4.1.
"""
standardized = [risk_standardize(pbpm, risk) for pbpm, risk, _ in counties]
if None in standardized:
return None
return month_weighted_average(
(value, months)
for value, (_, _, months) in zip(standardized, counties, strict=True)
)
@dataclass(frozen=True)
class SpendingDesignationResult:
"""The §3.4.2 ACO-level spending difference and the designation."""
weighted_difference: float
designation: SpendingDesignation | None
def spending_designation(
categories: Sequence[tuple[float, float, float]],
) -> SpendingDesignationResult:
"""Designate the ACO higher or lower spending.
Each category is (BY 3 regional FFS PBPM, Historical Benchmark PBPM,
BY 3 aligned months). The ACO-level difference is Σ (regional −
historical) × the category's share of BY 3 aligned months: positive is
lower spending, negative higher. The paper names no tie, so an exact
zero is left undetermined (``designation=None``).
Source: LEAD PY2027 methodology (bib E4PEU3HV) §3.4.2 / Table 3.4.2.
"""
total_months = sum(months for _, _, months in categories)
if total_months <= 0:
raise ValueError("the spending designation needs BY 3 aligned months")
difference = sum(
(regional - historical) * months / total_months
for regional, historical, months in categories
)
designation: SpendingDesignation | None = (
LOWER_SPENDING
if difference > 0
else HIGHER_SPENDING
if difference < 0
else None
)
return SpendingDesignationResult(difference, designation)
def benchmark_adjustment_cap_rate(reduced: bool) -> float:
"""Return the benchmark adjustment cap rate: 5 percent, or 3 percent
when CMS finds a lower-spending ACO has more than 40 percent of its
Participant TINs from a Shared Savings Program ACO (``reduced``).
Source: LEAD PY2027 methodology (bib E4PEU3HV) §3.4 / §3.4.3.
"""
return (
REDUCED_BENCHMARK_ADJUSTMENT_CAP_RATE
if reduced
else BENCHMARK_ADJUSTMENT_CAP_RATE
)
def benchmark_adjustment_cap(
uspcc_amount: float, py_average_risk_score: float, cap_rate: float
) -> float:
"""Return the risk-adjusted cap: modified-USPCC amount × PY average risk
score × cap rate ($3,500 × 1.030 × 5% = $180.25).
Source: LEAD PY2027 methodology (bib E4PEU3HV) §3.4.3 / Table 3.4.3.3.
"""
return uspcc_amount * py_average_risk_score * cap_rate
def regional_efficiency_eligible(
spending: SpendingDesignation, risk_option: RiskOption
) -> bool:
"""Whether the Regional Efficiency Adjustment applies: lower-spending
ACOs in the Global Risk track only.
Source: LEAD PY2027 methodology (bib E4PEU3HV) §3.4.3.
"""
return spending == LOWER_SPENDING and risk_option == GLOBAL
@dataclass(frozen=True)
class RegionalEfficiencyAdjustment:
"""Tables 3.4.3.1 and 3.4.3.3 for one category and alignment type."""
difference: float
uncapped: float
cap: float | None
applied: float | None
def regional_efficiency_adjustment(
regional_ffs_pbpm: float,
historical_benchmark_pbpm: float,
*,
eligible: bool,
uspcc_amount: float | None,
py_average_risk_score: float | None,
cap_rate: float,
) -> RegionalEfficiencyAdjustment:
"""Return the REA for one category and alignment type.
Uncapped = 50 percent of the positive regional − historical difference;
applied = the lesser of it and the cap. An ineligible ACO, or one at or
above regional spending, gets zero. A positive uncapped REA whose cap
inputs are missing is None — never the uncapped amount.
Source: LEAD PY2027 methodology (bib E4PEU3HV) §3.4.3 / Tables
3.4.3.1–3.4.3.4.
"""
difference = regional_ffs_pbpm - historical_benchmark_pbpm
uncapped = max(0.0, difference) * REGIONAL_EFFICIENCY_SHARE
cap = (
None
if uspcc_amount is None or py_average_risk_score is None
else benchmark_adjustment_cap(uspcc_amount, py_average_risk_score, cap_rate)
)
if not eligible or uncapped == 0.0:
applied: float | None = 0.0
else:
applied = None if cap is None else min(uncapped, cap)
return RegionalEfficiencyAdjustment(difference, uncapped, cap, applied)
def prior_savings_pbpm(
py_benchmark: float, py_expenditure: float, aligned_months: float
) -> float | None:
"""Return a prior year's gross savings (losses) PBPM: (benchmark −
expenditure) ÷ aligned beneficiary months.
Source: LEAD PY2027 methodology (bib E4PEU3HV) §3.4.4 / Table 3.4.3.7.
"""
return ratio(py_benchmark - py_expenditure, aligned_months)
@dataclass(frozen=True)
class PriorSavingsAdjustment:
"""§3.4.4 Examples 1–3."""
average_savings_pbpm: float
eligible: bool
proration_factor: float
prorated_average_savings: float
uncapped: float
cap: float | None
applied: float | None
def prior_savings_adjustment(
average_savings_pbpm: float,
predecessor_months: float,
py_months: float,
cap: float | None,
) -> PriorSavingsAdjustment:
"""Return the Prior Savings Adjustment PBPM.
Eligible only when the average PBPM savings is positive. Proration =
predecessor average months ÷ PY months, capped at 100 percent;
uncapped = 50 percent of the prorated average; applied = the lesser of
it and the ACO-level cap (None when an eligible ACO's cap is missing).
Source: LEAD PY2027 methodology (bib E4PEU3HV) §3.4.4 (Examples 1–3).
"""
if py_months <= 0:
raise ValueError("the proration factor needs PY beneficiary months")
eligible = average_savings_pbpm > 0
proration = min(predecessor_months / py_months, PRIOR_SAVINGS_PRORATION_CAP)
prorated = average_savings_pbpm * proration
uncapped = prorated * PRIOR_SAVINGS_SHARE if eligible else 0.0
if not eligible:
applied: float | None = 0.0
else:
applied = None if cap is None else min(uncapped, cap)
return PriorSavingsAdjustment(
average_savings_pbpm, eligible, proration, prorated, uncapped, cap, applied
)
def prior_savings_cap(
subpopulations: Sequence[tuple[float, float, float]], cap_rate: float
) -> float:
"""Return the ACO-level Prior Savings Adjustment cap: Σ sub-population
cap × its share of PY alignment, each sub-population being (share,
USPCC-based amount, PY average risk score).
Source: LEAD PY2027 methodology (bib E4PEU3HV) §3.4.4 / Table 3.4.3.9.
"""
return sum(
share * benchmark_adjustment_cap(uspcc, risk, cap_rate)
for share, uspcc, risk in subpopulations
)
# ── §3.5 Update to the Performance Year ───────────────────────────────────
@dataclass(frozen=True)
class ThreeWayTrend:
"""§3.5.1: the raw three-way factor, its guardrail band and the factor
applied."""
raw: float
lower_bound: float
upper_bound: float
applied: float
def three_way_blended_trend(
two_way_trend: float, acpt: float, performance_year: int
) -> ThreeWayTrend:
"""Blend two-thirds two-way trend and one-third ACPT, then hold the
result within the PY's guardrail around the two-way trend.
Both factors are cumulative from BY 3 to the PY.
Source: LEAD PY2027 methodology (bib E4PEU3HV) §3.5.1 / Table 3.5.1.
"""
raw = (1.0 - ACPT_WEIGHT) * two_way_trend + ACPT_WEIGHT * acpt
low, high = ACPT_GUARDRAILS[model_year(performance_year)]
lower, upper = two_way_trend + low, two_way_trend + high
return ThreeWayTrend(raw, lower, upper, min(max(raw, lower), upper))
def cumulative_acpt(annual_rates: Sequence[float | None]) -> float | None:
"""Return the cumulative BY 3 → PY ACPT factor: Π (1 + each year's
ACPT). Each year keeps its original prospective value even when a
guardrail bound an earlier year. One missing year leaves it None.
Source: LEAD PY2027 methodology (bib E4PEU3HV) §3.5.1 (ACPT Guardrail
Policy).
"""
if not annual_rates:
return None
factor = 1.0
for rate in annual_rates:
if rate is None:
return None
factor *= 1.0 + rate
return factor
WITHIN_CAP = "within_risk_score_growth_cap"
CAPPED = "capped_at_risk_score_growth_cap"
FLOORED = "raised_to_risk_score_growth_floor"
def capped_risk_score(
by3_risk_score: float, py_risk_score: float, category: BeneficiaryCategory
) -> tuple[float, str]:
"""Hold the PY average risk score within BY 3 × (1 ± cap): 3 percent
for A&D and ESRD, 4 percent for High Needs. Returns (score, status).
Source: LEAD PY2027 methodology (bib E4PEU3HV) §3.5.2 (Risk Score
Growth Cap).
"""
cap = RISK_SCORE_GROWTH_CAPS[category]
upper = by3_risk_score * (1.0 + cap)
lower = by3_risk_score * (1.0 - cap)
if py_risk_score > upper:
return upper, CAPPED
if py_risk_score < lower:
return lower, FLOORED
return py_risk_score, WITHIN_CAP
def performance_year_benchmark_pbpm(
historical_benchmark_pbpm: float,
benchmark_adjustment: float | None,
trend_factor: float,
capped_py_risk_score: float,
) -> float | None:
"""Return the PY Benchmark PBPM: (Historical Benchmark + REA or PSA) ×
three-way trend × capped PY risk score ($1,100 × 1.030 = $1,133).
A missing adjustment (None, e.g. an uncomputable cap) stays missing.
Source: LEAD PY2027 methodology (bib E4PEU3HV) §3.5 / §3.5.2.
"""
if benchmark_adjustment is None:
return None
adjusted = historical_benchmark_pbpm + benchmark_adjustment
return adjusted * trend_factor * capped_py_risk_score
def hybrid_adjustment_factor(
partial_period_pbpm: float, full_year_pbpm: float
) -> float | None:
"""Return a hybrid alignment adjustment factor: average PBPM over the
partial-year period ÷ average full-year PBPM.
Source: LEAD PY2027 methodology (bib E4PEU3HV) §3.5.3 / Table 3.5.3.1.
"""
return ratio(partial_period_pbpm, full_year_pbpm)
@dataclass(frozen=True)
class BenchmarkDollars:
"""Table 3.5.3.2 lines 6–8 for one category and alignment type."""
full_year: float
hybrid: float
total: float
def benchmark_dollars(
py_benchmark_pbpm: float,
full_year_months: float,
hybrid_months_and_factors: Sequence[tuple[float, float]] = (),
) -> BenchmarkDollars:
"""Multiply a PY Benchmark PBPM out to dollars over full-year months
and hybrid-aligned months at their adjustment factors.
``total`` = cents(PBPM × [full months + Σ hybrid months × factor]), one
product as Table 3.5.4 lines 8 and 22 state it; ``full_year`` and
``hybrid`` are the Table 3.5.3.2 lines 6 and 7 components.
Source: LEAD PY2027 methodology (bib E4PEU3HV) §3.5.3 / Table 3.5.3.2 /
Table 3.5.4 lines 8 and 22.
"""
hybrid_months = sum(months * factor for months, factor in hybrid_months_and_factors)
return BenchmarkDollars(
full_year=cents(py_benchmark_pbpm * full_year_months),
hybrid=cents(py_benchmark_pbpm * hybrid_months),
total=cents(py_benchmark_pbpm * (full_year_months + hybrid_months)),
)
def total_benchmark(category_dollars: Iterable[float]) -> float:
"""Sum aggregate benchmark dollars (claims + voluntary per category,
then A&D + ESRD + High Needs) into the PY Benchmark.
Source: LEAD PY2027 methodology (bib E4PEU3HV) §3.5.4 / Table 3.5.4
line 24.
"""
return cents(sum(category_dollars))