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

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 typing import Dict, Tuple, Optional, Set
 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:
 
@@ -91,10 +65,10 @@ def get_coefficent_prefix(demographics: Demographics,
 
 
 def apply_coefficients(demographics: Demographics,
-                      hcc_set: set[str],
+                      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_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_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/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/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.