hccinfhir 0.2.0__py3-none-any.whl → 0.2.2__py3-none-any.whl

hccinfhir/datamodels.py

@@ -93,6 +93,22 @@ PrefixOverride = Literal[
     "Rx_NE_LTI_",  # New Enrollee, Long-Term Institutionalized
 ]
 
+class HCCDetail(BaseModel):
+    """
+    Detailed information about an HCC category.
+
+    Attributes:
+        hcc: HCC code (e.g., "18", "85")
+        label: Human-readable description (e.g., "Diabetes with Chronic Complications")
+        is_chronic: Whether this HCC is considered a chronic condition
+        coefficient: The coefficient value applied for this HCC in the RAF calculation
+    """
+    hcc: str = Field(..., description="HCC code (e.g., '18', '85')")
+    label: Optional[str] = Field(None, description="Human-readable HCC description")
+    is_chronic: bool = Field(False, description="Whether this HCC is a chronic condition")
+    coefficient: Optional[float] = Field(None, description="Coefficient value for this HCC")
+
+
 class ServiceLevelData(BaseModel):
     """
     Represents standardized service-level data extracted from healthcare claims.
@@ -167,6 +183,7 @@ class RAFResult(BaseModel):
     risk_score_hcc: float = Field(..., description="HCC conditions risk score")
     risk_score_payment: float = Field(..., description="Payment RAF score (adjusted for MACI, normalization, and frailty)")
     hcc_list: List[str] = Field(default_factory=list, description="List of active HCC categories")
+    hcc_details: List[HCCDetail] = Field(default_factory=list, description="Detailed HCC information with labels and chronic status")
     cc_to_dx: Dict[str, Set[str]] = Field(default_factory=dict, description="Condition categories mapped to diagnosis codes")
     coefficients: Dict[str, float] = Field(default_factory=dict, description="Applied model coefficients")
     interactions: Dict[str, float] = Field(default_factory=dict, description="Disease interaction coefficients")

hccinfhir/defaults.py

@@ -15,7 +15,8 @@ from hccinfhir.utils import (
     load_hierarchies,
     load_is_chronic,
     load_coefficients,
-    load_proc_filtering
+    load_proc_filtering,
+    load_labels
 )
 
 # Load all default data files once at module import time
@@ -29,3 +30,4 @@ hierarchies_default: Dict[Tuple[str, ModelName], Set[str]] = load_hierarchies('r
 is_chronic_default: Dict[Tuple[str, ModelName], bool] = load_is_chronic('hcc_is_chronic.csv')
 coefficients_default: Dict[Tuple[str, ModelName], float] = load_coefficients('ra_coefficients_2026.csv')
 proc_filtering_default: Set[str] = load_proc_filtering('ra_eligible_cpt_hcpcs_2026.csv')
+labels_default: Dict[Tuple[str, ModelName], str] = load_labels('ra_labels_2026.csv')

hccinfhir/extractor_834.py

@@ -1,29 +1,23 @@
-from typing import List, Optional, Dict
+from typing import List, Optional, Dict, Any, Tuple
 from pydantic import BaseModel
 from datetime import datetime, date
 from hccinfhir.datamodels import Demographics, EnrollmentData
+from hccinfhir.constants import (
+    VALID_DUAL_CODES,
+    FULL_BENEFIT_DUAL_CODES,
+    PARTIAL_BENEFIT_DUAL_CODES,
+    VALID_OREC_VALUES,
+    VALID_CREC_VALUES,
+    X12_SEX_CODE_MAPPING,
+    NON_DUAL_CODE,
+    map_medicare_status_to_dual_code,
+    map_aid_code_to_dual_status,
+)
 
 TRANSACTION_TYPES = {
     "005010X220A1": "834",  # Benefit Enrollment and Maintenance
 }
 
-# California Medi-Cal Aid Codes mapping to dual eligibility status
-MEDI_CAL_AID_CODES = {
-    # Full Benefit Dual (QMB Plus, SLMB Plus)
-    '4N': '02',  # QMB Plus - Aged
-    '4P': '02',  # QMB Plus - Disabled
-    '5B': '04',  # SLMB Plus - Aged
-    '5D': '04',  # SLMB Plus - Disabled
-
-    # Partial Benefit Dual (QMB Only, SLMB Only, QI)
-    '4M': '01',  # QMB Only - Aged
-    '4O': '01',  # QMB Only - Disabled
-    '5A': '03',  # SLMB Only - Aged
-    '5C': '03',  # SLMB Only - Disabled
-    '5E': '06',  # QI - Aged
-    '5F': '06',  # QI - Disabled
-}
-
 class MemberContext(BaseModel):
     """Tracks member-level data across segments within 834 transaction"""
     # Identifiers
@@ -95,7 +89,7 @@ def is_medicaid_terminated(enrollment: EnrollmentData) -> bool:
     """Check if Medicaid coverage is being terminated (maintenance type 024)"""
     return enrollment.maintenance_type == '024'
 
-def medicaid_status_summary(enrollment: EnrollmentData) -> Dict[str, any]:
+def medicaid_status_summary(enrollment: EnrollmentData) -> Dict[str, Any]:
     """Get summary of Medicaid coverage status for monitoring
 
     Args:
@@ -157,45 +151,28 @@ def get_segment_value(segment: List[str], index: int, default: Optional[str] = N
         pass
     return default
 
-def map_medicare_status_to_dual_code(status: Optional[str]) -> Optional[str]:
-    """Map Medicare status codes to dual eligibility codes
+def parse_composite_ref_value(value: str) -> str:
+    """Parse X12 composite element format: 'qualifier;id;...'
 
-    California Medi-Cal uses these status codes:
-    - QMB = Qualified Medicare Beneficiary
-    - QMBPLUS = QMB Plus (Full Benefit)
-    - SLMB = Specified Low-Income Medicare Beneficiary
-    - SLMBPLUS = SLMB Plus (Full Benefit)
-    - QI = Qualifying Individual
-    - QDWI = Qualified Disabled Working Individual
+    X12 uses semicolons to separate sub-elements within a composite data element.
+    Example: REF*23*9;20061234; where 9 is the ID type qualifier
+
+    Args:
+        value: Raw REF segment value (e.g., '9;20061234;' or '20061234')
+
+    Returns:
+        The last non-empty sub-element (the actual ID)
     """
-    if not status:
-        return None
+    if not value:
+        return value
 
-    status_upper = status.upper().replace(' ', '').replace('-', '')
-
-    mapping = {
-        'QMB': '01',         # QMB Only (Partial)
-        'QMBONLY': '01',
-        'QMBPLUS': '02',     # QMB Plus (Full Benefit)
-        'QMB+': '02',
-        'SLMB': '03',        # SLMB Only (Partial)
-        'SLMBONLY': '03',
-        'SLMBPLUS': '04',    # SLMB Plus (Full Benefit)
-        'SLMB+': '04',
-        'QDWI': '05',
-        'QI': '06',
-        'QI1': '06',
-        'FBDE': '08',        # Full Benefit Dual Eligible (Other)
-        'OTHERFULL': '08',
-    }
+    if ';' in value:
+        # Split by semicolon and filter out empty parts
+        parts = [p for p in value.split(';') if p]
+        return parts[-1] if parts else value
 
-    return mapping.get(status_upper)
+    return value
 
-def map_aid_code_to_dual_status(aid_code: Optional[str]) -> Optional[str]:
-    """Map California Medi-Cal aid code to dual eligibility status"""
-    if not aid_code:
-        return None
-    return MEDI_CAL_AID_CODES.get(aid_code)
 
 def determine_dual_status(member: MemberContext) -> str:
     """Intelligently derive dual eligibility code from available data
@@ -208,19 +185,19 @@ def determine_dual_status(member: MemberContext) -> str:
     5. Default to non-dual ('00')
     """
     # Priority 1: Explicit dual_elgbl_cd
-    if member.dual_elgbl_cd and member.dual_elgbl_cd in ['01','02','03','04','05','06','08']:
+    if member.dual_elgbl_cd and member.dual_elgbl_cd in VALID_DUAL_CODES:
         return member.dual_elgbl_cd
 
     # Priority 2: California aid code mapping
     if member.medi_cal_aid_code:
         dual_code = map_aid_code_to_dual_status(member.medi_cal_aid_code)
-        if dual_code:
+        if dual_code != NON_DUAL_CODE:
             return dual_code
 
     # Priority 3: Medicare status code
     if member.medicare_status_code:
         dual_code = map_medicare_status_to_dual_code(member.medicare_status_code)
-        if dual_code:
+        if dual_code != NON_DUAL_CODE:
             return dual_code
 
     # Priority 4: Both Medicare and Medicaid coverage present
@@ -229,9 +206,9 @@ def determine_dual_status(member: MemberContext) -> str:
         return '08'
 
     # Default: Non-dual
-    return '00'
+    return NON_DUAL_CODE
 
-def classify_dual_benefit_level(dual_code: str) -> tuple[bool, bool]:
+def classify_dual_benefit_level(dual_code: str) -> Tuple[bool, bool]:
     """Classify as Full Benefit Dual (FBD) or Partial Benefit Dual (PBD)
 
     Full Benefit Dual codes: 02, 04, 08
@@ -242,11 +219,8 @@ def classify_dual_benefit_level(dual_code: str) -> tuple[bool, bool]:
     - Uses CPA_ (Community, Partial Benefit Dual, Aged) prefix
     - Uses CPD_ (Community, Partial Benefit Dual, Disabled) prefix
     """
-    full_benefit_codes = {'02', '04', '08'}
-    partial_benefit_codes = {'01', '03', '05', '06'}
-
-    is_fbd = dual_code in full_benefit_codes
-    is_pbd = dual_code in partial_benefit_codes
+    is_fbd = dual_code in FULL_BENEFIT_DUAL_CODES
+    is_pbd = dual_code in PARTIAL_BENEFIT_DUAL_CODES
 
     return is_fbd, is_pbd
 
@@ -284,7 +258,7 @@ def parse_834_enrollment(segments: List[List[str]]) -> List[EnrollmentData]:
     enrollments = []
     member = MemberContext()
 
-    for i, segment in enumerate(segments):
+    for segment in segments:
         if len(segment) < 2:
             continue
 
@@ -330,11 +304,11 @@ def parse_834_enrollment(segments: List[List[str]]) -> List[EnrollmentData]:
 
             # Medicaid Identifiers
             elif qualifier == '1D':  # Medicaid/Recipient ID
-                member.medicaid_id = value
+                member.medicaid_id = parse_composite_ref_value(value)
                 member.has_medicaid = True
             elif qualifier == '23':  # Medicaid Recipient ID (alternative)
                 if not member.medicaid_id:
-                    member.medicaid_id = value
+                    member.medicaid_id = parse_composite_ref_value(value)
                 member.has_medicaid = True
 
             # California Medi-Cal Specific
@@ -345,13 +319,13 @@ def parse_834_enrollment(segments: List[List[str]]) -> List[EnrollmentData]:
 
             # Custom dual eligibility indicators
             elif qualifier == 'F5':  # Dual Eligibility Code (custom)
-                if value in ['01','02','03','04','05','06','08']:
+                if value in VALID_DUAL_CODES:
                     member.dual_elgbl_cd = value
             elif qualifier == 'DX':  # OREC (custom)
-                if value in ['0','1','2','3']:
+                if value in VALID_OREC_VALUES:
                     member.orec = value
             elif qualifier == 'DY':  # CREC (custom)
-                if value in ['0','1','2','3']:
+                if value in VALID_CREC_VALUES:
                     member.crec = value
             elif qualifier == 'EJ':  # Low Income Subsidy indicator
                 member.low_income = (value.upper() in ['Y', 'YES', '1', 'TRUE'])
@@ -376,8 +350,8 @@ def parse_834_enrollment(segments: List[List[str]]) -> List[EnrollmentData]:
 
             # DMG03 = Gender Code
             sex = get_segment_value(segment, 3)
-            if sex in ['M', 'F', '1', '2']:
-                member.sex = 'M' if sex in ['M', '1'] else 'F'
+            if sex in X12_SEX_CODE_MAPPING:
+                member.sex = X12_SEX_CODE_MAPPING[sex]
 
         # ===== DTP - Date Time Periods =====
         elif seg_id == 'DTP' and len(segment) >= 4:
@@ -440,6 +414,13 @@ def parse_834_enrollment(segments: List[List[str]]) -> List[EnrollmentData]:
                     member.has_medicare = True
                     member.has_medicaid = True
 
+            # Detect LTI (Long Term Institutionalized)
+            if any(keyword in combined for keyword in [
+                'LTC', 'LONG TERM CARE', 'LONG-TERM CARE', 'NURSING HOME',
+                'SKILLED NURSING', 'SNF', 'INSTITUTIONALIZED'
+            ]):
+                member.lti = True
+
     # Don't forget last member
     if member.member_id or member.has_medicare or member.has_medicaid:
         enrollments.append(create_enrollment_data(member))

hccinfhir/extractor_837.py

@@ -1,4 +1,4 @@
-from typing import List, Optional, Dict
+from typing import List, Optional, Dict, Tuple
 from pydantic import BaseModel
 from hccinfhir.datamodels import ServiceLevelData
 
@@ -65,7 +65,7 @@ def parse_diagnosis_codes(segment: List[str]) -> Dict[str, str]:
             dx_lookup[str(pos)] = code
     return dx_lookup
 
-def process_service_line(segments: List[List[str]], start_index: int) -> tuple[Optional[str], Optional[str]]:
+def process_service_line(segments: List[List[str]], start_index: int) -> Tuple[Optional[str], Optional[str]]:
     """Extract NDC and service date from service line segments"""
     ndc = None
     service_date = None

hccinfhir/hccinfhir.py

@@ -1,4 +1,4 @@
-from typing import List, Dict, Any, Union, Optional, Tuple, Set
+from typing import List, Dict, Any, Union, Optional, Tuple, Set, Iterable
 from hccinfhir.extractor import extract_sld_list
 from hccinfhir.filter import apply_filter
 from hccinfhir.model_calculate import calculate_raf
@@ -184,16 +184,16 @@ class HCCInFHIR:
         # Create new result with service data included
         return raf_result.model_copy(update={'service_level_data': standardized_data})
         
-    def calculate_from_diagnosis(self, diagnosis_codes: List[str],
+    def calculate_from_diagnosis(self, diagnosis_codes: Iterable[str],
                                demographics: Union[Demographics, Dict[str, Any]],
                                prefix_override: Optional[PrefixOverride] = None,
                                maci: float = 0.0,
                                norm_factor: float = 1.0,
                                frailty_score: float = 0.0) -> RAFResult:
-        """Calculate RAF scores from a list of diagnosis codes.
+        """Calculate RAF scores from diagnosis codes.
 
         Args:
-            diagnosis_codes: List of diagnosis codes
+            diagnosis_codes: Iterable of diagnosis codes (list, tuple, numpy array, etc.)
             demographics: Demographics information
             prefix_override: Optional prefix to override auto-detected demographic prefix.
                 Use when demographic categorization is incorrect (e.g., ESRD patients with orec=0).
@@ -201,14 +201,14 @@ class HCCInFHIR:
             norm_factor: Normalization factor (default 1.0)
             frailty_score: Frailty adjustment score (default 0.0)
 
-        Raises:
-            ValueError: If diagnosis_codes is empty or not a list
+        Returns:
+            RAFResult object containing calculated scores
         """
-        if not isinstance(diagnosis_codes, list):
-            raise ValueError("diagnosis_codes must be a list")
-        
+        # Convert to list to ensure consistent handling downstream
+        diagnosis_list = list(diagnosis_codes) if diagnosis_codes is not None else []
+
         demographics = self._ensure_demographics(demographics)
         raf_result = self._calculate_raf_from_demographics_and_dx_codes(
-            diagnosis_codes, demographics, prefix_override, maci, norm_factor, frailty_score
+            diagnosis_list, demographics, prefix_override, maci, norm_factor, frailty_score
         )
         return raf_result

hccinfhir/model_calculate.py

@@ -1,11 +1,11 @@
 from typing import List, Union, Dict, Tuple, Set, Optional
-from hccinfhir.datamodels import ModelName, RAFResult, PrefixOverride
+from hccinfhir.datamodels import ModelName, RAFResult, PrefixOverride, HCCDetail
 from hccinfhir.model_demographics import categorize_demographics
 from hccinfhir.model_dx_to_cc import apply_mapping
 from hccinfhir.model_hierarchies import apply_hierarchies
 from hccinfhir.model_coefficients import apply_coefficients
 from hccinfhir.model_interactions import apply_interactions
-from hccinfhir.defaults import dx_to_cc_default, hierarchies_default, is_chronic_default, coefficients_default
+from hccinfhir.defaults import dx_to_cc_default, hierarchies_default, is_chronic_default, coefficients_default, labels_default
 
 def calculate_raf(diagnosis_codes: List[str],
                   model_name: ModelName = "CMS-HCC Model V28",
@@ -23,6 +23,7 @@ def calculate_raf(diagnosis_codes: List[str],
                   is_chronic_mapping: Dict[Tuple[str, ModelName], bool] = is_chronic_default,
                   hierarchies_mapping: Dict[Tuple[str, ModelName], Set[str]] = hierarchies_default,
                   coefficients_mapping: Dict[Tuple[str, ModelName], float] = coefficients_default,
+                  labels_mapping: Dict[Tuple[str, ModelName], str] = labels_default,
                   prefix_override: Optional[PrefixOverride] = None,
                   maci: float = 0.0,
                   norm_factor: float = 1.0,
@@ -47,6 +48,7 @@ def calculate_raf(diagnosis_codes: List[str],
         is_chronic_mapping: Mapping of HCCs to a chronic flag for the selected model; defaults to packaged mappings.
         hierarchies_mapping: Mapping of parent HCCs to child HCCs for hierarchical rules; defaults to packaged 2026 mappings.
         coefficients_mapping: Mapping of coefficient names to values; defaults to packaged 2026 mappings.
+        labels_mapping: Mapping of (cc, model_name) to human-readable HCC labels; defaults to packaged 2026 mappings.
         prefix_override: Optional prefix to override auto-detected demographic prefix.
             Use when demographic categorization from orec/crec is incorrect.
             Common values: 'DI_' (ESRD Dialysis), 'DNE_' (ESRD Dialysis New Enrollee),
@@ -136,6 +138,19 @@ def calculate_raf(diagnosis_codes: List[str],
     risk_score_hcc = risk_score - risk_score_demographics
     risk_score_payment = risk_score * (1 - maci) / norm_factor + frailty_score
 
+    # Build HCC details with labels and chronic status
+    hcc_details = []
+    for hcc in hcc_set:
+        label = labels_mapping.get((hcc, model_name))
+        is_chronic = is_chronic_mapping.get((hcc, model_name), False)
+        coef = coefficients.get(hcc)
+        hcc_details.append(HCCDetail(
+            hcc=hcc,
+            label=label,
+            is_chronic=is_chronic,
+            coefficient=coef
+        ))
+
     return RAFResult(
         risk_score=risk_score,
         risk_score_demographics=risk_score_demographics,
@@ -143,6 +158,7 @@ def calculate_raf(diagnosis_codes: List[str],
         risk_score_hcc=risk_score_hcc,
         risk_score_payment=risk_score_payment,
         hcc_list=list(hcc_set),
+        hcc_details=hcc_details,
         cc_to_dx=cc_to_dx,
         coefficients=coefficients,
         interactions=interactions,

hccinfhir/model_coefficients.py

@@ -1,4 +1,4 @@
-from typing import Dict, Tuple, Optional
+from typing import Dict, Tuple, Optional, Set
 from hccinfhir.datamodels import ModelName, Demographics, PrefixOverride
 
 def get_coefficent_prefix(demographics: Demographics, 
@@ -65,7 +65,7 @@ def get_coefficent_prefix(demographics: Demographics,
 
 
 def apply_coefficients(demographics: Demographics,
-                      hcc_set: set[str],
+                      hcc_set: Set[str],
                       interactions: dict,
                       model_name: ModelName,
                       coefficients: Dict[Tuple[str, ModelName], float],

hccinfhir/model_demographics.py

@@ -1,5 +1,18 @@
 from typing import Union, Optional
 from hccinfhir.datamodels import Demographics, PrefixOverride
+from hccinfhir.constants import (
+    FULL_BENEFIT_DUAL_CODES,
+    PARTIAL_BENEFIT_DUAL_CODES,
+    OREC_ESRD_CODES,
+    CREC_ESRD_CODES,
+    ESRD_PREFIXES,
+    NEW_ENROLLEE_PREFIXES,
+    COMMUNITY_PREFIXES,
+    INSTITUTIONAL_PREFIXES,
+    FULL_BENEFIT_DUAL_PREFIXES,
+    PARTIAL_BENEFIT_DUAL_PREFIXES,
+    NON_DUAL_PREFIXES,
+)
     
 def categorize_demographics(age: Union[int, float],
                        sex: str,
@@ -75,56 +88,40 @@ def categorize_demographics(age: Union[int, float],
     disabled = age < 65 and (orec is not None and orec != "0")
     orig_disabled = (orec is not None and orec == '1') and not disabled
 
-    # Reference: https://resdac.org/cms-data/variables/medicare-medicaid-dual-eligibility-code-january 
-    # Full benefit dual codes
-    fbd_codes = {'02', '04', '08'}
-    
-    # Partial benefit dual codes
-    pbd_codes = {'01', '03', '05', '06'}
-    
-    is_fbd = dual_elgbl_cd in fbd_codes
-    is_pbd = dual_elgbl_cd in pbd_codes
+    # Reference: https://resdac.org/cms-data/variables/medicare-medicaid-dual-eligibility-code-january
+    is_fbd = dual_elgbl_cd in FULL_BENEFIT_DUAL_CODES
+    is_pbd = dual_elgbl_cd in PARTIAL_BENEFIT_DUAL_CODES
 
-    esrd_orec = orec in {'2', '3', '6'}
-    esrd_crec = crec in {'2', '3'} if crec else False
+    # ESRD detection from OREC/CREC (CMS official codes: 2=ESRD, 3=DIB+ESRD)
+    esrd_orec = orec in OREC_ESRD_CODES
+    esrd_crec = crec in CREC_ESRD_CODES if crec else False
     esrd = esrd_orec or esrd_crec
 
     # Override demographics based on prefix_override
     if prefix_override:
-        # ESRD model prefixes
-        esrd_prefixes = {'DI_', 'DNE_', 'GI_', 'GNE_', 'GFPA_', 'GFPN_', 'GNPA_', 'GNPN_'}
-        # CMS-HCC new enrollee prefixes
-        new_enrollee_prefixes = {'NE_', 'SNPNE_', 'DNE_', 'GNE_'}
-        # CMS-HCC community prefixes
-        community_prefixes = {'CNA_', 'CND_', 'CFA_', 'CFD_', 'CPA_', 'CPD_'}
-        # Institutionalized prefix
-        institutional_prefixes = {'INS_', 'GI_'}
-        
-        # TODO: RxHCC prefixes
-
         # Set esrd flag
-        if prefix_override in esrd_prefixes:
+        if prefix_override in ESRD_PREFIXES:
             esrd = True
 
         # Set new_enrollee flag
-        if prefix_override in new_enrollee_prefixes:
+        if prefix_override in NEW_ENROLLEE_PREFIXES:
             new_enrollee = True
-        elif prefix_override in community_prefixes or prefix_override in institutional_prefixes:
+        elif prefix_override in COMMUNITY_PREFIXES or prefix_override in INSTITUTIONAL_PREFIXES:
             new_enrollee = False
 
         # Set dual eligibility flags based on prefix
-        if prefix_override in {'CFA_', 'CFD_', 'GFPA_', 'GFPN_'}:
+        if prefix_override in FULL_BENEFIT_DUAL_PREFIXES:
             is_fbd = True
             is_pbd = False
-        elif prefix_override in {'CPA_', 'CPD_'}:
+        elif prefix_override in PARTIAL_BENEFIT_DUAL_PREFIXES:
             is_fbd = False
             is_pbd = True
-        elif prefix_override in {'CNA_', 'CND_', 'GNPA_', 'GNPN_'}:
+        elif prefix_override in NON_DUAL_PREFIXES:
             is_fbd = False
             is_pbd = False
 
         # Set lti flag based on prefix
-        if prefix_override in institutional_prefixes:
+        if prefix_override in INSTITUTIONAL_PREFIXES:
             lti = True
 
     result_dict = {

hccinfhir/model_interactions.py

@@ -1,7 +1,7 @@
 from hccinfhir.datamodels import Demographics, ModelName
-from typing import Optional
+from typing import Optional, List, Set, Dict
 
-def has_any_hcc(hcc_list: list[str], hcc_set: set[str]) -> int:
+def has_any_hcc(hcc_list: List[str], hcc_set: Set[str]) -> int:
     """Returns 1 if any HCC in the list is present, 0 otherwise"""
     return int(bool(set(hcc_list) & hcc_set))
 
@@ -81,7 +81,7 @@ def create_dual_interactions(demographics: Demographics) -> dict:
         
     return interactions
 
-def create_hcc_counts(hcc_set: set[str]) -> dict:
+def create_hcc_counts(hcc_set: Set[str]) -> Dict:
     """Creates HCC count variables"""
     counts = {}
     hcc_count = len(hcc_set)
@@ -95,7 +95,7 @@ def create_hcc_counts(hcc_set: set[str]) -> dict:
 
     return counts
 
-def get_diagnostic_categories(model_name: ModelName, hcc_set: set[str]) -> dict:
+def get_diagnostic_categories(model_name: ModelName, hcc_set: Set[str]) -> Dict:
     """Creates disease categories based on model version"""
     categories = {}
     
@@ -343,9 +343,9 @@ def create_disease_interactions(model_name: ModelName,
     
     return interactions
 
-def apply_interactions(demographics: Demographics, 
-                      hcc_set: set[str], 
-                      model_name: ModelName = "CMS-HCC Model V28") -> dict:
+def apply_interactions(demographics: Demographics,
+                      hcc_set: Set[str],
+                      model_name: ModelName = "CMS-HCC Model V28") -> Dict:
     """
     Calculate HCC interactions across CMS models. Handles CMS-HCC, ESRD, and RxHCC models.
     """

hccinfhir/utils.py

@@ -244,4 +244,71 @@ def load_coefficients(file_path: str) -> Dict[Tuple[str, ModelName], float]:
         except (ValueError, IndexError):
             continue  # Skip malformed lines
 
-    return coefficients
+    return coefficients
+
+
+def load_labels(file_path: str) -> Dict[Tuple[str, ModelName], str]:
+    """
+    Load HCC labels from a CSV file.
+    Expected format: cc,label,model_domain,model_version,...
+
+    Args:
+        file_path: Filename or path to the CSV file
+
+    Returns:
+        Dictionary mapping (cc, model_name) to label string
+
+    Raises:
+        FileNotFoundError: If file cannot be found
+        RuntimeError: If file cannot be loaded or parsed
+    """
+    labels: Dict[Tuple[str, ModelName], str] = {}
+
+    try:
+        resolved_path = resolve_data_file(file_path)
+        with open(resolved_path, "r", encoding="utf-8") as file:
+            content = file.read()
+    except FileNotFoundError as e:
+        raise FileNotFoundError(f"Could not load labels: {e}")
+    except Exception as e:
+        raise RuntimeError(f"Error loading labels file '{file_path}': {e}")
+
+    for line in content.splitlines()[1:]:  # Skip header
+        try:
+            parts = line.strip().split(',')
+            if len(parts) < 4:
+                continue
+            cc_raw, label, model_domain, model_version = parts[0], parts[1], parts[2], parts[3]
+
+            # Strip HCC prefix if present to get just the number
+            cc = cc_raw.replace('HCC', '').replace('RxHCC', '')
+
+            # Handle quoted labels with commas
+            if label.startswith('"'):
+                # Find closing quote
+                label_parts = [label]
+                for i, p in enumerate(parts[2:], start=2):
+                    if p.endswith('"'):
+                        label_parts.append(p)
+                        # Recalculate domain and version after the quoted label
+                        model_domain = parts[i + 1] if len(parts) > i + 1 else ''
+                        model_version = parts[i + 2] if len(parts) > i + 2 else ''
+                        break
+                    label_parts.append(p)
+                label = ','.join(label_parts).strip('"')
+
+            # Construct model name based on domain
+            if model_domain == 'ESRD':
+                model_name = f"CMS-HCC {model_domain} Model {model_version}"
+            elif model_domain == 'RxHCC':
+                model_name = f"{model_domain} Model {model_version}"
+            else:
+                model_name = f"{model_domain} Model {model_version}"
+
+            key = (cc, model_name)
+            if key not in labels:
+                labels[key] = label
+        except (ValueError, IndexError):
+            continue  # Skip malformed lines
+
+    return labels