hccinfhir 0.1.9__py3-none-any.whl → 0.2.1__py3-none-any.whl

hccinfhir/__init__.py

@@ -18,6 +18,7 @@ from .samples import (
     get_eob_sample_list,
     get_837_sample,
     get_837_sample_list,
+    get_834_sample,
     list_available_samples
 )
 
@@ -43,5 +44,6 @@ __all__ = [
     "get_eob_sample_list",
     "get_837_sample",
     "get_837_sample_list",
+    "get_834_sample",
     "list_available_samples"
 ]

hccinfhir/constants.py

@@ -0,0 +1,240 @@
+"""
+CMS Risk Adjustment Domain Constants
+
+This module contains constants used across the HCC risk adjustment system,
+including dual eligibility codes, OREC/CREC values, and state-specific mappings.
+
+References:
+- CMS Rate Announcement and Call Letter
+- Medicare Advantage Enrollment and Disenrollment Guidance
+- X12 834 Implementation Guides
+"""
+
+from typing import Set, Dict
+
+# =============================================================================
+# DUAL ELIGIBILITY CODES
+# =============================================================================
+# CMS Dual Eligibility Status Codes (Medicare + Medicaid)
+# Used in coefficient prefix selection (CNA_, CFA_, CPA_, etc.)
+
+VALID_DUAL_CODES: Set[str] = {'00', '01', '02', '03', '04', '05', '06', '08'}
+
+# Non-Dual Eligible
+NON_DUAL_CODE: str = '00'
+
+# Full Benefit Dual Eligible (receive both Medicare and full Medicaid benefits)
+# Uses CFA_ (Community, Full Benefit Dual, Aged) or CFD_ (Disabled) prefixes
+FULL_BENEFIT_DUAL_CODES: Set[str] = {
+    '02',  # QMB Plus (Qualified Medicare Beneficiary Plus)
+    '04',  # SLMB Plus (Specified Low-Income Medicare Beneficiary Plus)
+    '08',  # Other Full Benefit Dual Eligible
+}
+
+# Partial Benefit Dual Eligible (Medicare + limited Medicaid)
+# Uses CPA_ (Community, Partial Benefit Dual, Aged) or CPD_ (Disabled) prefixes
+PARTIAL_BENEFIT_DUAL_CODES: Set[str] = {
+    '01',  # QMB Only
+    '03',  # SLMB Only
+    '05',  # QDWI (Qualified Disabled and Working Individual)
+    '06',  # QI (Qualifying Individual)
+}
+
+# =============================================================================
+# OREC - Original Reason for Entitlement Code
+# =============================================================================
+# Determines if beneficiary has ESRD and affects coefficient prefix selection
+
+VALID_OREC_VALUES: Set[str] = {'0', '1', '2', '3'}
+
+OREC_DESCRIPTIONS: Dict[str, str] = {
+    '0': 'Old Age and Survivors Insurance (OASI)',
+    '1': 'Disability Insurance Benefits (DIB)',
+    '2': 'ESRD - End-Stage Renal Disease',
+    '3': 'DIB and ESRD',
+}
+
+# OREC codes indicating ESRD status (per CMS documentation)
+OREC_ESRD_CODES: Set[str] = {'2', '3'}
+
+# =============================================================================
+# CREC - Current Reason for Entitlement Code
+# =============================================================================
+# Current entitlement status (may differ from OREC)
+
+VALID_CREC_VALUES: Set[str] = {'0', '1', '2', '3'}
+
+CREC_DESCRIPTIONS: Dict[str, str] = {
+    '0': 'Old Age and Survivors Insurance (OASI)',
+    '1': 'Disability Insurance Benefits (DIB)',
+    '2': 'ESRD - End-Stage Renal Disease',
+    '3': 'DIB and ESRD',
+}
+
+# CREC codes indicating ESRD status
+CREC_ESRD_CODES: Set[str] = {'2', '3'}
+
+# =============================================================================
+# COEFFICIENT PREFIX GROUPS
+# =============================================================================
+# Used for prefix_override logic in model_demographics.py
+
+# ESRD model prefixes
+ESRD_PREFIXES: Set[str] = {'DI_', 'DNE_', 'GI_', 'GNE_', 'GFPA_', 'GFPN_', 'GNPA_', 'GNPN_'}
+
+# CMS-HCC new enrollee prefixes
+NEW_ENROLLEE_PREFIXES: Set[str] = {'NE_', 'SNPNE_', 'DNE_', 'GNE_'}
+
+# CMS-HCC community prefixes
+COMMUNITY_PREFIXES: Set[str] = {'CNA_', 'CND_', 'CFA_', 'CFD_', 'CPA_', 'CPD_'}
+
+# Institutionalized prefixes
+INSTITUTIONAL_PREFIXES: Set[str] = {'INS_', 'GI_'}
+
+# Full Benefit Dual prefixes
+FULL_BENEFIT_DUAL_PREFIXES: Set[str] = {'CFA_', 'CFD_', 'GFPA_', 'GFPN_'}
+
+# Partial Benefit Dual prefixes
+PARTIAL_BENEFIT_DUAL_PREFIXES: Set[str] = {'CPA_', 'CPD_'}
+
+# Non-Dual prefixes
+NON_DUAL_PREFIXES: Set[str] = {'CNA_', 'CND_', 'GNPA_', 'GNPN_'}
+
+# =============================================================================
+# DEMOGRAPHIC CODES
+# =============================================================================
+
+VALID_SEX_CODES: Set[str] = {'M', 'F'}
+
+# X12 834 Gender Code mappings
+X12_SEX_CODE_MAPPING: Dict[str, str] = {
+    'M': 'M',
+    'F': 'F',
+    '1': 'M',  # X12 numeric code
+    '2': 'F',  # X12 numeric code
+}
+
+# =============================================================================
+# X12 834 MAINTENANCE TYPE CODES
+# =============================================================================
+# INS03 - Maintenance Type Code
+
+MAINTENANCE_TYPE_CHANGE: str = '001'
+MAINTENANCE_TYPE_ADD: str = '021'
+MAINTENANCE_TYPE_CANCEL: str = '024'
+MAINTENANCE_TYPE_REINSTATE: str = '025'
+
+MAINTENANCE_TYPE_DESCRIPTIONS: Dict[str, str] = {
+    '001': 'Change',
+    '021': 'Addition',
+    '024': 'Cancellation/Termination',
+    '025': 'Reinstatement',
+}
+
+# =============================================================================
+# STATE-SPECIFIC MAPPINGS
+# =============================================================================
+
+# -----------------------------------------------------------------------------
+# California DHCS Medi-Cal Aid Codes
+# -----------------------------------------------------------------------------
+# Maps California-specific aid codes to CMS dual eligibility codes
+# Source: California DHCS 834 Implementation Guide
+
+MEDI_CAL_AID_CODES: Dict[str, str] = {
+    # 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
+}
+
+# -----------------------------------------------------------------------------
+# Medicare Status Code Mappings
+# -----------------------------------------------------------------------------
+# Maps Medicare status codes (from various sources) to CMS dual eligibility codes
+# Used in X12 834 REF*ABB segment and other payer files
+
+MEDICARE_STATUS_CODE_MAPPING: Dict[str, str] = {
+    # QMB - Qualified Medicare Beneficiary
+    'QMB': '01',         # QMB Only (Partial)
+    'QMBONLY': '01',
+    'QMBPLUS': '02',     # QMB Plus (Full Benefit)
+    'QMB+': '02',
+
+    # SLMB - Specified Low-Income Medicare Beneficiary
+    'SLMB': '03',        # SLMB Only (Partial)
+    'SLMBONLY': '03',
+    'SLMBPLUS': '04',    # SLMB Plus (Full Benefit)
+    'SLMB+': '04',
+
+    # Other dual eligibility programs
+    'QDWI': '05',        # Qualified Disabled and Working Individual
+    'QI': '06',          # Qualifying Individual
+    'QI1': '06',
+    'FBDE': '08',        # Full Benefit Dual Eligible (Other)
+    'OTHERFULL': '08',
+}
+
+# =============================================================================
+# HELPER FUNCTIONS
+# =============================================================================
+
+def is_full_benefit_dual(dual_code: str) -> bool:
+    """Check if dual eligibility code is Full Benefit Dual"""
+    return dual_code in FULL_BENEFIT_DUAL_CODES
+
+def is_partial_benefit_dual(dual_code: str) -> bool:
+    """Check if dual eligibility code is Partial Benefit Dual"""
+    return dual_code in PARTIAL_BENEFIT_DUAL_CODES
+
+def is_esrd_by_orec(orec: str) -> bool:
+    """Check if OREC indicates ESRD status"""
+    return orec in OREC_ESRD_CODES
+
+def is_esrd_by_crec(crec: str) -> bool:
+    """Check if CREC indicates ESRD status"""
+    return crec in CREC_ESRD_CODES
+
+def normalize_medicare_status_code(status: str) -> str:
+    """Normalize Medicare status code (uppercase, no spaces/hyphens)"""
+    if not status:
+        return ''
+    return status.upper().replace(' ', '').replace('-', '')
+
+def map_medicare_status_to_dual_code(status: str) -> str:
+    """Map Medicare status code to dual eligibility code
+
+    Args:
+        status: Medicare status code (e.g., 'QMB Plus', 'SLMB', 'QI')
+
+    Returns:
+        Dual eligibility code ('01'-'08') or '00' if not found
+    """
+    if not status:
+        return NON_DUAL_CODE
+
+    normalized = normalize_medicare_status_code(status)
+    return MEDICARE_STATUS_CODE_MAPPING.get(normalized, NON_DUAL_CODE)
+
+def map_aid_code_to_dual_status(aid_code: str) -> str:
+    """Map California Medi-Cal aid code to dual eligibility code
+
+    Args:
+        aid_code: California aid code (e.g., '4N', '5B')
+
+    Returns:
+        Dual eligibility code ('01'-'08') or '00' if not found
+    """
+    if not aid_code:
+        return NON_DUAL_CODE
+
+    return MEDI_CAL_AID_CODES.get(aid_code, NON_DUAL_CODE)

hccinfhir/datamodels.py

@@ -11,16 +11,47 @@ ModelName = Literal[
     "RxHCC Model V08"
 ]
 
-ProcFilteringFilename = Literal[
-    "ra_eligible_cpt_hcpcs_2023.csv",
-    "ra_eligible_cpt_hcpcs_2024.csv",
-    "ra_eligible_cpt_hcpcs_2025.csv",
-    "ra_eligible_cpt_hcpcs_2026.csv"
+# Filename types: allow bundled filenames (with autocomplete) OR any custom string path
+ProcFilteringFilename = Union[
+    Literal[
+        "ra_eligible_cpt_hcpcs_2023.csv",
+        "ra_eligible_cpt_hcpcs_2024.csv",
+        "ra_eligible_cpt_hcpcs_2025.csv",
+        "ra_eligible_cpt_hcpcs_2026.csv"
+    ],
+    str  # Allow any custom file path
 ]
 
-DxCCMappingFilename = Literal[
-    "ra_dx_to_cc_2025.csv",
-    "ra_dx_to_cc_2026.csv"
+DxCCMappingFilename = Union[
+    Literal[
+        "ra_dx_to_cc_2025.csv",
+        "ra_dx_to_cc_2026.csv"
+    ],
+    str
+]
+
+HierarchiesFilename = Union[
+    Literal[
+        "ra_hierarchies_2025.csv",
+        "ra_hierarchies_2026.csv"
+    ],
+    str
+]
+
+IsChronicFilename = Union[
+    Literal[
+        "hcc_is_chronic.csv",
+        "hcc_is_chronic_without_esrd_model.csv"
+    ],
+    str
+]
+
+CoefficientsFilename = Union[
+    Literal[
+        "ra_coefficients_2025.csv",
+        "ra_coefficients_2026.csv"
+    ],
+    str
 ]
 
 PrefixOverride = Literal[

hccinfhir/defaults.py

@@ -0,0 +1,31 @@
+"""
+Central location for all default data file loading.
+
+This module loads all default data files at import time and provides them
+to the public API functions (calculate_raf) and tests. Internal model_*
+modules should not load their own defaults - they should receive data
+as explicit parameters.
+
+Default files are for the 2026 model year.
+"""
+from typing import Dict, Set, Tuple
+from hccinfhir.datamodels import ModelName
+from hccinfhir.utils import (
+    load_dx_to_cc_mapping,
+    load_hierarchies,
+    load_is_chronic,
+    load_coefficients,
+    load_proc_filtering
+)
+
+# Load all default data files once at module import time
+# These are used by:
+# - calculate_raf() function for direct usage
+# - HCCInFHIR class (though it can override with custom files)
+# - Tests that need default data
+
+dx_to_cc_default: Dict[Tuple[str, ModelName], Set[str]] = load_dx_to_cc_mapping('ra_dx_to_cc_2026.csv')
+hierarchies_default: Dict[Tuple[str, ModelName], Set[str]] = load_hierarchies('ra_hierarchies_2026.csv')
+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')

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,9 +1,9 @@
-from typing import List, Dict, Any, Union, Optional
+from typing import List, Dict, Any, Union, Optional, Tuple, Set
 from hccinfhir.extractor import extract_sld_list
 from hccinfhir.filter import apply_filter
 from hccinfhir.model_calculate import calculate_raf
-from hccinfhir.datamodels import Demographics, ServiceLevelData, RAFResult, ModelName, ProcFilteringFilename, DxCCMappingFilename, PrefixOverride
-from hccinfhir.utils import load_proc_filtering, load_dx_to_cc_mapping
+from hccinfhir.datamodels import Demographics, ServiceLevelData, RAFResult, ModelName, ProcFilteringFilename, DxCCMappingFilename, HierarchiesFilename, IsChronicFilename, CoefficientsFilename, PrefixOverride
+from hccinfhir.utils import load_proc_filtering, load_dx_to_cc_mapping, load_hierarchies, load_is_chronic, load_coefficients
 
 class HCCInFHIR:
     """
@@ -13,26 +13,40 @@ class HCCInFHIR:
     of the hccinfhir library.
     """
     
-    def __init__(self, 
-                 filter_claims: bool = True, 
+    def __init__(self,
+                 filter_claims: bool = True,
                  model_name: ModelName = "CMS-HCC Model V28",
                  proc_filtering_filename: ProcFilteringFilename = "ra_eligible_cpt_hcpcs_2026.csv",
-                 dx_cc_mapping_filename: DxCCMappingFilename = "ra_dx_to_cc_2026.csv"):
+                 dx_cc_mapping_filename: DxCCMappingFilename = "ra_dx_to_cc_2026.csv",
+                 hierarchies_filename: HierarchiesFilename = "ra_hierarchies_2026.csv",
+                 is_chronic_filename: IsChronicFilename = "hcc_is_chronic.csv",
+                 coefficients_filename: CoefficientsFilename = "ra_coefficients_2026.csv"):
         """
         Initialize the HCCInFHIR processor.
-        
+
         Args:
             filter_claims: Whether to apply filtering rules to claims. Default is True.
             model_name: The name of the model to use for the calculation. Default is "CMS-HCC Model V28".
-            proc_filtering_filename: The filename of the professional cpt filtering file. Default is "ra_eligible_cpt_hcpcs_2026.csv".
-            dx_cc_mapping_filename: The filename of the dx to cc mapping file. Default is "ra_dx_to_cc_2026.csv".
+            proc_filtering_filename: Filename or path to the CPT/HCPCS filtering file. Default is "ra_eligible_cpt_hcpcs_2026.csv".
+            dx_cc_mapping_filename: Filename or path to the diagnosis to CC mapping file. Default is "ra_dx_to_cc_2026.csv".
+            hierarchies_filename: Filename or path to the hierarchies file. Default is "ra_hierarchies_2026.csv".
+            is_chronic_filename: Filename or path to the chronic conditions file. Default is "hcc_is_chronic.csv".
+            coefficients_filename: Filename or path to the coefficients file. Default is "ra_coefficients_2026.csv".
         """
         self.filter_claims = filter_claims
         self.model_name = model_name
         self.proc_filtering_filename = proc_filtering_filename
         self.dx_cc_mapping_filename = dx_cc_mapping_filename
+        self.hierarchies_filename = hierarchies_filename
+        self.is_chronic_filename = is_chronic_filename
+        self.coefficients_filename = coefficients_filename
+
+        # Load all data files once at initialization
         self.professional_cpt = load_proc_filtering(proc_filtering_filename)
         self.dx_to_cc_mapping = load_dx_to_cc_mapping(dx_cc_mapping_filename)
+        self.hierarchies_mapping = load_hierarchies(hierarchies_filename)
+        self.is_chronic_mapping = load_is_chronic(is_chronic_filename)
+        self.coefficients_mapping = load_coefficients(coefficients_filename)
 
 
     def _ensure_demographics(self, demographics: Union[Demographics, Dict[str, Any]]) -> Demographics:
@@ -47,7 +61,7 @@ class HCCInFHIR:
                                                       maci: float = 0.0,
                                                       norm_factor: float = 1.0,
                                                       frailty_score: float = 0.0) -> RAFResult:
-        """Calculate RAF score using demographics data."""
+        """Calculate RAF score using demographics data and loaded data files."""
         return calculate_raf(
             diagnosis_codes=diagnosis_codes,
             model_name=self.model_name,
@@ -62,6 +76,9 @@ class HCCInFHIR:
             lti=demographics.lti,
             graft_months=demographics.graft_months,
             dx_to_cc_mapping=self.dx_to_cc_mapping,
+            is_chronic_mapping=self.is_chronic_mapping,
+            hierarchies_mapping=self.hierarchies_mapping,
+            coefficients_mapping=self.coefficients_mapping,
             prefix_override=prefix_override,
             maci=maci,
             norm_factor=norm_factor,