coding-hcc-risk-adjustment

Mapping conditions to CMS-HCC V28 and estimating RAF

Surface and risk-adjust the chronic conditions OpenMed extracts by mapping them to CMS-HCC categories (the V28 model, phasing in for payment years 2024–2026) and estimating a RAF (Risk Adjustment Factor) score. CMS pays Medicare Advantage plans based on RAF, so accurate, documented capture of chronic disease matters — and much of that signal lives in the narrative note, exactly what OpenMed reads.

This is decision support for coders/clinicians, not autonomous coding. The output is "candidate HCCs + estimated RAF + the documentation that supports (or fails to support) each one," for human validation.

CMS-HCC crosswalks (ICD-10-CM → HCC) and the category coefficients are public — CMS publishes them annually. Nothing restricted is bundled.

When to use

• You want to find risk-adjustable diagnoses mentioned in a note that may not be on the coded problem list ("suspect HCCs" / recapture).
• You need to map ICD-10-CM codes to V28 HCCs and apply the hierarchy.
• You want an estimated RAF for a patient or panel for review.
• You need to check whether a diagnosis has MEAT support (Monitored, Evaluated, Assessed, Treated) in the documentation.

Pairs with coding-icd10 (you need ICD-10-CM codes first) and may consume mapping-to-snomed output upstream.

Quick start (public CMS crosswalk + coefficients)

CMS publishes the V28 ICD-10-CM→HCC mapping and the model coefficients. Load them locally (public files) and apply the model:

import csv

# 1) ICD-10-CM -> HCC (V28) crosswalk from the CMS Risk Adjustment files.
icd_to_hcc = {}                       # "E1122" -> "HCC38" (Diabetes w/ complication)
with open("cms_hcc_v28_icd_map.csv") as fh:
    for row in csv.DictReader(fh):
        icd_to_hcc[row["icd10cm"].replace(".", "")] = row["hcc_v28"]

# 2) HCC -> RAF coefficient for the relevant model segment (e.g. CNA community).
hcc_weight = {}                       # "HCC38" -> 0.166 (illustrative)
with open("cms_hcc_v28_coefficients.csv") as fh:
    for row in csv.DictReader(fh):
        hcc_weight[row["hcc"]] = float(row["coefficient"])

# 3) Apply the HCC hierarchy: a more severe HCC in a family suppresses milder
#    ones (e.g. acute MI suppresses angina). Load the hierarchy from CMS.
hierarchy = {                         # parent HCC -> HCCs it zeroes out
    # "HCC37": {"HCC38"},  # illustrative; use the official V28 hierarchy file
}

def apply_hierarchy(hccs: set[str]) -> set[str]:
    kept = set(hccs)
    for parent in hccs:
        kept -= hierarchy.get(parent, set())
    return kept

def estimate_raf(icd_codes: list[str], demo_factor: float = 0.0) -> dict:
    hccs = {icd_to_hcc[c] for c in icd_codes if c in icd_to_hcc}
    hccs = apply_hierarchy(hccs)
    disease_raf = sum(hcc_weight.get(h, 0.0) for h in hccs)
    return {"hccs": sorted(hccs),
            "disease_raf": round(disease_raf, 3),
            "estimated_raf": round(disease_raf + demo_factor, 3)}