hccinfhir 0.1.9__py3-none-any.whl → 0.2.0__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/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/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,

hccinfhir/model_calculate.py

@@ -5,15 +5,7 @@ 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.utils import load_dx_to_cc_mapping, load_is_chronic
-
-# Load default mappings from csv file
-mapping_file_default = 'ra_dx_to_cc_2026.csv'
-dx_to_cc_default = load_dx_to_cc_mapping(mapping_file_default)
-
-# Load default mappings from csv file
-mapping_file_default = 'hcc_is_chronic.csv'
-is_chronic_default = load_is_chronic(mapping_file_default)
+from hccinfhir.defaults import dx_to_cc_default, hierarchies_default, is_chronic_default, coefficients_default
 
 def calculate_raf(diagnosis_codes: List[str],
                   model_name: ModelName = "CMS-HCC Model V28",
@@ -29,6 +21,8 @@ def calculate_raf(diagnosis_codes: List[str],
                   graft_months: int =  None,
                   dx_to_cc_mapping: Dict[Tuple[str, ModelName], Set[str]] = dx_to_cc_default,
                   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,
                   prefix_override: Optional[PrefixOverride] = None,
                   maci: float = 0.0,
                   norm_factor: float = 1.0,
@@ -37,24 +31,32 @@ def calculate_raf(diagnosis_codes: List[str],
     Calculate Risk Adjustment Factor (RAF) based on diagnosis codes and demographic information.
 
     Args:
-        diagnosis_codes: List of ICD-10 diagnosis codes
-        model_name: Name of the HCC model to use
-        age: Patient's age
-        sex: Patient's sex ('M' or 'F')
-        dual_elgbl_cd: Dual eligibility code
-        orec: Original reason for entitlement code
-        crec: Current reason for entitlement code
-        new_enrollee: Whether the patient is a new enrollee
-        snp: Special Needs Plan indicator
-        low_income: Low income subsidy indicator
-        graft_months: Number of months since transplant
+        diagnosis_codes: List of ICD-10 diagnosis codes.
+        model_name: Name of the HCC model to use.
+        age: Patient's age.
+        sex: Patient's sex ('M' or 'F').
+        dual_elgbl_cd: Dual eligibility code.
+        orec: Original reason for entitlement code.
+        crec: Current reason for entitlement code.
+        new_enrollee: Whether the patient is a new enrollee.
+        snp: Special Needs Plan indicator.
+        low_income: Low income subsidy indicator.
+        lti: Long-term institutional status indicator.
+        graft_months: Number of months since transplant.
+        dx_to_cc_mapping: Mapping of diagnosis codes to condition categories; defaults to packaged 2026 mappings.
+        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.
         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),
             'INS_' (Institutionalized), 'CFA_' (Community Full Dual Aged), etc.
+        maci: Medicare Advantage coding intensity adjustment applied to payment score.
+        norm_factor: Normalization factor applied to payment score.
+        frailty_score: Frailty adjustment added to payment score.
 
     Returns:
-        Dictionary containing RAF score and coefficients used in calculation
+        RAFResult with the calculated risk scores, intermediate inputs, and metadata for the model run.
 
     Raises:
         ValueError: If input parameters are invalid
@@ -89,10 +91,10 @@ def calculate_raf(diagnosis_codes: List[str],
                              model_name,
                              dx_to_cc_mapping=dx_to_cc_mapping)
     hcc_set = set(cc_to_dx.keys())
-    hcc_set = apply_hierarchies(hcc_set, model_name)
+    hcc_set = apply_hierarchies(hcc_set, model_name, hierarchies_mapping)
     interactions = apply_interactions(demographics, hcc_set, model_name)
     coefficients = apply_coefficients(demographics, hcc_set, interactions, model_name,
-                                     prefix_override=prefix_override)
+                                     coefficients_mapping, prefix_override=prefix_override)
 
     hcc_chronic = set()
     interactions_chronic = {}
@@ -116,11 +118,13 @@ def calculate_raf(diagnosis_codes: List[str],
                                                    set(),
                                                    demographic_interactions,
                                                    model_name,
+                                                   coefficients_mapping,
                                                    prefix_override=prefix_override)
     coefficients_chronic_only = apply_coefficients(demographics,
                                                    hcc_chronic,
                                                    interactions_chronic,
                                                    model_name,
+                                                   coefficients_mapping,
                                                    prefix_override=prefix_override)
     
     # Calculate risk scores

hccinfhir/model_coefficients.py

@@ -1,32 +1,6 @@
 from typing import Dict, Tuple, Optional
-import importlib.resources
 from hccinfhir.datamodels import ModelName, Demographics, PrefixOverride
 
-# Load default mappings from csv file
-coefficients_file_default = 'ra_coefficients_2026.csv'
-coefficients_default: Dict[Tuple[str, ModelName], float] = {}  # (diagnosis_code, model_name) -> value
-
-try:
-    with importlib.resources.open_text('hccinfhir.data', coefficients_file_default) as f:
-        for line in f.readlines()[1:]:  # Skip header
-            try:
-                coefficient, value, model_domain, model_version = line.strip().split(',')
-                if model_domain == 'ESRD':  
-                    model_name = f"CMS-HCC {model_domain} Model V{model_version[-2:]}"
-                else:
-                    model_name = f"{model_domain} Model V{model_version[-2:]}"
-                
-                key = (coefficient.lower(), model_name)
-                if key not in coefficients_default:
-                    coefficients_default[key] = float(value)
-                else:
-                    coefficients_default[key] = float(value)
-            except ValueError:
-                continue  # Skip malformed lines
-except Exception as e:
-    print(f"Error loading mapping file: {e}")
-    coefficients_default = {}
-
 def get_coefficent_prefix(demographics: Demographics, 
                           model_name: ModelName = "CMS-HCC Model V28") -> str:
 
@@ -93,8 +67,8 @@ def get_coefficent_prefix(demographics: Demographics,
 def apply_coefficients(demographics: Demographics,
                       hcc_set: set[str],
                       interactions: dict,
-                      model_name: ModelName = "CMS-HCC Model V28",
-                      coefficients: Dict[Tuple[str, ModelName], float] = coefficients_default,
+                      model_name: ModelName,
+                      coefficients: Dict[Tuple[str, ModelName], float],
                       prefix_override: Optional[PrefixOverride] = None) -> dict:
     """Apply risk adjustment coefficients to HCCs and interactions.
 
@@ -108,7 +82,6 @@ def apply_coefficients(demographics: Demographics,
         interactions: Dictionary of interaction variables and their values (0 or 1)
         model_name: Name of the risk adjustment model to use (default: "CMS-HCC Model V28")
         coefficients: Dictionary mapping (variable, model) tuples to coefficient values
-            (default: coefficients_default)
         prefix_override: Optional prefix to override auto-detected demographic prefix.
             Common values: 'DI_' (ESRD Dialysis), 'DNE_' (ESRD Dialysis New Enrollee),
             'INS_' (Institutionalized), 'CFA_' (Community Full Dual Aged), etc.

hccinfhir/model_dx_to_cc.py

@@ -1,15 +1,10 @@
 from typing import List, Dict, Set, Tuple, Optional
 from hccinfhir.datamodels import ModelName
-from hccinfhir.utils import load_dx_to_cc_mapping
-
-# Load default mappings from csv file
-mapping_file_default = 'ra_dx_to_cc_2026.csv'
-dx_to_cc_default = load_dx_to_cc_mapping(mapping_file_default)
 
 def get_cc(
     diagnosis_code: str,
-    model_name: ModelName = "CMS-HCC Model V28",
-    dx_to_cc_mapping: Dict[Tuple[str, ModelName], Set[str]] = dx_to_cc_default
+    model_name: ModelName,
+    dx_to_cc_mapping: Dict[Tuple[str, ModelName], Set[str]]
 ) -> Optional[Set[str]]:
     """
     Get CC for a single diagnosis code.
@@ -17,7 +12,7 @@ def get_cc(
     Args:
         diagnosis_code: ICD-10 diagnosis code
         model_name: HCC model name to use for mapping
-        dx_to_cc_mapping: Optional custom mapping dictionary
+        dx_to_cc_mapping: Mapping dictionary of (diagnosis_code, model_name) to CC codes
 
     Returns:
         CC code if found, None otherwise
@@ -26,8 +21,8 @@ def get_cc(
 
 def apply_mapping(
     diagnoses: List[str],
-    model_name: ModelName = "CMS-HCC Model V28", 
-    dx_to_cc_mapping: Dict[Tuple[str, ModelName], Set[str]] = dx_to_cc_default
+    model_name: ModelName,
+    dx_to_cc_mapping: Dict[Tuple[str, ModelName], Set[str]]
 ) -> Dict[str, Set[str]]:
     """
     Apply ICD-10 to CC mapping for a list of diagnosis codes.
@@ -35,7 +30,7 @@ def apply_mapping(
     Args:
         diagnoses: List of ICD-10 diagnosis codes
         model_name: HCC model name to use for mapping
-        dx_to_cc_mapping: Optional custom mapping dictionary
+        dx_to_cc_mapping: Mapping dictionary of (diagnosis_code, model_name) to CC codes
         
     Returns:
         Dictionary mapping CCs to lists of diagnosis codes that map to them

hccinfhir/model_hierarchies.py

@@ -1,47 +1,18 @@
 from typing import Dict, Set, Tuple
-import importlib.resources
-from hccinfhir.datamodels import ModelName  
-
-def load_hierarchies(hierarchies_file: str) -> Dict[Tuple[str, ModelName], Set[str]]:
-    """Load hierarchies from a CSV file."""
-    hierarchies = {}
-    try:
-        with importlib.resources.open_text('hccinfhir.data', hierarchies_file) as f:
-            for line in f.readlines()[1:]:  # Skip header
-                try:
-                    cc_parent, cc_child, model_domain, model_version, _ = line.strip().split(',')
-                    if model_domain == 'ESRD':
-                        model_name = f"CMS-HCC {model_domain} Model {model_version}"
-                    else:
-                        model_name = f"{model_domain} Model {model_version}"
-                    key = (cc_parent, model_name)
-                    if key not in hierarchies:
-                        hierarchies[key] = {cc_child}
-                    else:
-                        hierarchies[key].add(cc_child)
-                except ValueError:
-                    continue  # Skip malformed lines
-    except Exception as e:
-        print(f"Error loading mapping file: {e}")
-        hierarchies = {}
-    return hierarchies
-
-# Load default mappings from csv file
-hierarchies_file_default = 'ra_hierarchies_2026.csv'
-hierarchies_default: Dict[Tuple[str, ModelName], Set[str]] = load_hierarchies(hierarchies_file_default)
+from hccinfhir.datamodels import ModelName
 
 def apply_hierarchies(
-    cc_set: Set[str],  # Set of active CCs
-    model_name: ModelName = "CMS-HCC Model V28",
-    hierarchies: Dict[Tuple[str, ModelName], Set[str]] = hierarchies_default
+    cc_set: Set[str],
+    model_name: ModelName,
+    hierarchies: Dict[Tuple[str, ModelName], Set[str]]
 ) -> Set[str]:
     """
     Apply hierarchical rules to a set of CCs based on model version.
 
     Args:
-        ccs: Set of current active CCs
+        cc_set: Set of current active CCs
         model_name: HCC model name to use for hierarchy rules
-        hierarchies: Optional custom hierarchy dictionary
+        hierarchies: Mapping dictionary of (parent_cc, model_name) to child CCs
         
     Returns:
         Set of CCs after applying hierarchies

hccinfhir/samples.py

@@ -157,7 +157,36 @@ class SampleData:
                 raise FileNotFoundError(f"Sample 837 case {case_num} not found")
         
         return output
-    
+
+    @staticmethod
+    def get_834_sample(case_number: int = 1) -> str:
+        """
+        Retrieve a specific 834 enrollment sample by case number.
+
+        Args:
+            case_number: The case number (currently only 1 is available). Default is 1.
+
+        Returns:
+            A string containing the 834 X12 enrollment data
+
+        Raises:
+            ValueError: If case_number is not 1
+            FileNotFoundError: If the sample file cannot be found
+
+        Example:
+            >>> sample_834 = SampleData.get_834_sample(1)
+            >>> print("ISA" in sample_834)
+            True
+        """
+        if case_number != 1:
+            raise ValueError("case_number must be 1 (only one 834 sample currently available)")
+
+        try:
+            with importlib.resources.open_text('hccinfhir.sample_files', f'sample_834_0{case_number}.txt') as f:
+                return f.read()
+        except FileNotFoundError:
+            raise FileNotFoundError(f"Sample 834 case {case_number} not found")
+
     @staticmethod
     def list_available_samples() -> Dict[str, Any]:
         """
@@ -174,7 +203,7 @@ class SampleData:
         return {
             "eob_samples": [
                 "sample_eob_1.json",
-                "sample_eob_2.json", 
+                "sample_eob_2.json",
                 "sample_eob_3.json",
                 "sample_eob_200.ndjson"
             ],
@@ -182,9 +211,12 @@ class SampleData:
             "eob_list_size": 200,
             "837_samples": [f"sample_837_{i}.txt" for i in range(13)],
             "837_case_numbers": list(range(13)),
+            "834_samples": ["sample_834_01.txt"],
+            "834_case_numbers": [1],
             "description": {
                 "eob": "Explanation of Benefits (FHIR resources) for testing HCC calculations",
-                "837": "X12 837 claim data for testing claim processing"
+                "837": "X12 837 claim data for testing claim processing",
+                "834": "X12 834 enrollment data for dual eligibility and demographics"
             }
         }
 
@@ -232,16 +264,29 @@ def get_837_sample(case_number: int = 0) -> str:
 def get_837_sample_list(case_numbers: Optional[List[int]] = None) -> List[str]:
     """
     Convenience function to get multiple 837 claim samples.
-    
+
     Args:
         case_numbers: List of case numbers to retrieve. If None, returns all 12 samples.
-        
+
     Returns:
         A list of 837 X12 claim data strings
     """
     return SampleData.get_837_sample_list(case_numbers)
 
 
+def get_834_sample(case_number: int = 1) -> str:
+    """
+    Convenience function to get an 834 enrollment sample.
+
+    Args:
+        case_number: The case number (currently only 1 is available). Default is 1.
+
+    Returns:
+        A string containing the 834 X12 enrollment data
+    """
+    return SampleData.get_834_sample(case_number)
+
+
 def list_available_samples() -> Dict[str, Any]:
     """
     Convenience function to get information about available samples.