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
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.
653 lines
23 KiB
Python
653 lines
23 KiB
Python
"""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))
|