Files
stack/src/lead/high_needs.py

81 lines
2.6 KiB
Python

"""High Needs criteria for one quarter and for an alignment year.
The scores, the Kim index, the diagnosis flag, and the DME flag are
caller-supplied. Appendix B code lists, Kim weights, and the V28 software
are not in this repo, so this module does not invent them. The thresholds
are the ones named in the LEAD methodology for PY 2027.
A score of 3.0 is HN.4 only. A score of 0.35 is HN.5 only. The HN.6 bands
stop below those thresholds. Once any quarter meets a criterion, it applies
for the whole alignment year, and a criterion met in a prior year stays met.
"""
from __future__ import annotations
from collections.abc import Sequence
from dataclasses import dataclass
AD_HIGH = 3.0
ESRD_HIGH = 0.35
AD_BAND_LOW = 2.0
ESRD_BAND_LOW = 0.24
UNPLANNED_ADMISSIONS = 2
SNF_DAYS = 45
@dataclass(frozen=True)
class QuarterFlags:
"""One quarter's lookback, already counted by the caller."""
quarter: str
hn1_diagnosis: bool = False
hn2_dme: bool = False
kim_index: float | None = None
kim_cutoff: float | None = None
ad_score: float | None = None
esrd_score: float | None = None
unplanned_admissions: int = 0
snf_days: int = 0
def criteria_met(flags: QuarterFlags) -> frozenset[str]:
"""Target ids this quarter meets. An empty set meets none."""
met: set[str] = set()
if flags.hn1_diagnosis:
met.add("HN.1")
if flags.hn2_dme:
met.add("HN.2")
if (
flags.kim_index is not None
and flags.kim_cutoff is not None
and flags.kim_index >= flags.kim_cutoff
):
met.add("HN.3")
if flags.ad_score is not None and flags.ad_score >= AD_HIGH:
met.add("HN.4")
if flags.esrd_score is not None and flags.esrd_score >= ESRD_HIGH:
met.add("HN.5")
admissions = flags.unplanned_admissions >= UNPLANNED_ADMISSIONS
ad_band = flags.ad_score is not None and AD_BAND_LOW <= flags.ad_score < AD_HIGH
esrd_band = (
flags.esrd_score is not None and ESRD_BAND_LOW <= flags.esrd_score < ESRD_HIGH
)
if admissions and (ad_band or esrd_band):
met.add("HN.6")
if flags.snf_days >= SNF_DAYS:
met.add("HN.7")
return frozenset(met)
def alignment_year(quarters: Sequence[QuarterFlags]) -> frozenset[str]:
"""Union of the criteria met in any quarter of the alignment year."""
met: set[str] = set()
for quarter in quarters:
met |= criteria_met(quarter)
return frozenset(met)
def persists(prior: frozenset[str], this_year: frozenset[str]) -> frozenset[str]:
"""High Needs status does not go away once a criterion has been met."""
return prior | this_year