hccinfhir 0.1.0__py3-none-any.whl → 0.1.2__py3-none-any.whl

hccinfhir/datamodels.py

@@ -14,11 +14,13 @@ ModelName = Literal[
 ProcFilteringFilename = Literal[
     "ra_eligible_cpt_hcpcs_2023.csv",
     "ra_eligible_cpt_hcpcs_2024.csv",
-    "ra_eligible_cpt_hcpcs_2025.csv"
+    "ra_eligible_cpt_hcpcs_2025.csv",
+    "ra_eligible_cpt_hcpcs_2026.csv"
 ]
 
 DxCCMappingFilename = Literal[
-    "ra_dx_to_cc_2025.csv"
+    "ra_dx_to_cc_2025.csv",
+    "ra_dx_to_cc_2026.csv"
 ]
 
 class ServiceLevelData(BaseModel):

hccinfhir/filter.py

@@ -3,7 +3,7 @@ from hccinfhir.datamodels import ServiceLevelData
 from hccinfhir.utils import load_proc_filtering
 
 # use import importlib.resources to load the professional_cpt_fn file as a list of strings
-professional_cpt_default_fn = 'ra_eligible_cpt_hcpcs_2023.csv'
+professional_cpt_default_fn = 'ra_eligible_cpt_hcpcs_2025.csv'
 professional_cpt_default = load_proc_filtering(professional_cpt_default_fn)
 
 def apply_filter(
@@ -14,28 +14,26 @@ def apply_filter(
 ) -> List[ServiceLevelData]:
     # tob (Type of Bill) Filter is based on:
     # https://www.hhs.gov/guidance/sites/default/files/hhs-guidance-documents/2012181486-wq-092916_ra_webinar_slides_5cr_092816.pdf
-    # https://www.hhs.gov/guidance/sites/default/files/hhs-guidance-documents/final%20industry%20memo%20medicare%20filtering%20logic%2012%2022%2015_85.pdf
+    # https://www.hhs.gov/guidance/sites/default/files/hhs-guidance-documents/FinalEncounterDataDiagnosisFilteringLogic.pdf
 
-    # Break down the inpatient ToB into facility and service types
-    inpatient_facility_types = {tob[0] for tob in inpatient_tob}
-    inpatient_service_types = {tob[1] for tob in inpatient_tob}
+    # NOTE: If no facility_type or service_type, then the claim is professional, in our implementation.
+    # NOTE: The original CMS logic is for the "record" level, not the service level.
+    #  Thus, when preparing the service level data, put all diagnosis codes into the diagnosis field.
 
-    # Break down the outpatient ToB into facility and service types
-    outpatient_facility_types = {tob[0] for tob in outpatient_tob}
-    outpatient_service_types = {tob[1] for tob in outpatient_tob}       
-
-    # If ServiceLevelData has a facility_type and service_type, then filter the data based on the facility_type and service_type
-    # If not, then filter the data based on the CPT code
     filtered_data = []
     for item in data:
-        if item.facility_type and item.service_type:
-            if item.facility_type in inpatient_facility_types and item.service_type in inpatient_service_types:
-                filtered_data.append(item)
-            elif (item.facility_type in outpatient_facility_types and 
-                  item.service_type in outpatient_service_types and
-                  item.procedure_code in professional_cpt):
+        item_tob = '?' if item.facility_type is None else item.facility_type 
+        item_tob += '?' if item.service_type is None else item.service_type 
+        item_tob += 'X'
+
+        if '?' in item_tob: # professional claims
+            if item.procedure_code in professional_cpt:
                 filtered_data.append(item)
         else:
-            if item.procedure_code in professional_cpt:
-                filtered_data.append(item)  
+            if item_tob in inpatient_tob:
+                filtered_data.append(item)
+            elif item_tob in outpatient_tob:
+                if item.procedure_code in professional_cpt:
+                    filtered_data.append(item)
+            
     return filtered_data

hccinfhir/hccinfhir.py

@@ -16,16 +16,16 @@ class HCCInFHIR:
     def __init__(self, 
                  filter_claims: bool = True, 
                  model_name: ModelName = "CMS-HCC Model V28",
-                 proc_filtering_filename: ProcFilteringFilename = "ra_eligible_cpt_hcpcs_2025.csv",
-                 dx_cc_mapping_filename: DxCCMappingFilename = "ra_dx_to_cc_2025.csv"):
+                 proc_filtering_filename: ProcFilteringFilename = "ra_eligible_cpt_hcpcs_2026.csv",
+                 dx_cc_mapping_filename: DxCCMappingFilename = "ra_dx_to_cc_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_2025.csv".
-            dx_cc_mapping_filename: The filename of the dx to cc mapping file. Default is "ra_dx_to_cc_2025.csv".
+            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".
         """
         self.filter_claims = filter_claims
         self.model_name = model_name
@@ -81,8 +81,9 @@ class HCCInFHIR:
         
         # Extract and filter service level data
         sld_list = extract_sld_list(eob_list)
+
         if self.filter_claims:
-            sld_list = apply_filter(sld_list, self.professional_cpt)
+            sld_list = apply_filter(sld_list, professional_cpt=self.professional_cpt)
             
         # Calculate RAF score
         unique_dx_codes = self._get_unique_diagnosis_codes(sld_list)

hccinfhir/model_calculate.py

@@ -8,7 +8,7 @@ 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_2025.csv'
+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
@@ -87,8 +87,25 @@ def calculate_raf(diagnosis_codes: List[str],
         if is_chronic_mapping.get((hcc, model_name), False):
             hcc_chronic.add(hcc)
 
-    coefficients_demographics = apply_coefficients(demographics, set(), {}, model_name)
-    coefficients_chronic_only = apply_coefficients(demographics, hcc_chronic, {}, model_name)
+    demographic_interactions = {}
+    for key, value in interactions.items():
+        if key.startswith('NMCAID_'):
+            demographic_interactions[key] = value
+        elif key.startswith('MCAID_'):
+            demographic_interactions[key] = value
+        elif key.startswith('LTI_'):
+            demographic_interactions[key] = value
+        elif key.startswith('OriginallyDisabled_'):
+            demographic_interactions[key] = value
+
+    coefficients_demographics = apply_coefficients(demographics, 
+                                                   set(), 
+                                                   demographic_interactions, 
+                                                   model_name)
+    coefficients_chronic_only = apply_coefficients(demographics, 
+                                                   hcc_chronic, 
+                                                   demographic_interactions, 
+                                                   model_name)
     
     # Calculate risk scores
     risk_score = sum(coefficients.values())

hccinfhir/model_coefficients.py

@@ -3,7 +3,7 @@ import importlib.resources
 from hccinfhir.datamodels import ModelName, Demographics
 
 # Load default mappings from csv file
-coefficients_file_default = 'ra_coefficients_2025.csv'
+coefficients_file_default = 'ra_coefficients_2026.csv'
 coefficients_default: Dict[Tuple[str, ModelName], float] = {}  # (diagnosis_code, model_name) -> value
 
 try:
@@ -80,6 +80,7 @@ def get_coefficent_prefix(demographics: Demographics,
         return 'INS_'
         
     if demographics.new_enrollee:
+
         return 'SNPNE_' if demographics.snp else 'NE_'
         
     # Community case
@@ -139,5 +140,6 @@ def apply_coefficients(demographics: Demographics,
             value = coefficients[key]
             output[interaction_key] = value
 
+
     return output
 

hccinfhir/model_demographics.py

@@ -57,6 +57,14 @@ def categorize_demographics(age: Union[int, float],
         raise ValueError("Sex must be 'M', 'F', '1', or '2'")
     
     # Determine if person is disabled or originally disabled
+    # SAS code:
+    # DISABL = (&AGEF < 65 & &OREC ne "0");
+    # ORIGDS  = (&OREC = '1')*(DISABL = 0);
+    # The vairable names can be misleading. 
+    # disabled is true if the person is disabled and the age is less than 65
+    # - basically, the person is in Medicare due to disability not due to age
+    # orig_disabled is true if the person started Medicare due to disability, but now aged in
+    # - basically, the person is in Medicare due to age (not disability anymore)
     disabled = age < 65 and (orec is not None and orec != "0")
     orig_disabled = (orec is not None and orec == '1') and not disabled
 

hccinfhir/model_dx_to_cc.py

@@ -3,7 +3,7 @@ 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_2025.csv'
+mapping_file_default = 'ra_dx_to_cc_2026.csv'
 dx_to_cc_default = load_dx_to_cc_mapping(mapping_file_default)
 
 def get_cc(

hccinfhir/model_hierarchies.py

@@ -2,29 +2,33 @@ from typing import Dict, Set, Tuple
 import importlib.resources
 from hccinfhir.datamodels import ModelName  
 
-# Load default mappings from csv file
-hierarchies_file_default = 'ra_hierarchies_2025.csv'
-hierarchies_default: Dict[Tuple[str, ModelName], Set[str]] = {}  # (diagnosis_code, model_name) -> {cc}
+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
 
-try:
-    with importlib.resources.open_text('hccinfhir.data', hierarchies_file_default) 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_default:
-                    hierarchies_default[key] = {cc_child}
-                else:
-                    hierarchies_default[key].add(cc_child)
-            except ValueError:
-                continue  # Skip malformed lines
-except Exception as e:
-    print(f"Error loading mapping file: {e}")
-    hierarchies_default = {}
+# 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)
 
 def apply_hierarchies(
     cc_set: Set[str],  # Set of active CCs

hccinfhir/sample_utils.py

@@ -0,0 +1,252 @@
+"""
+Sample Data Module for HCCInFHIR
+
+This module provides easy access to sample data files for testing and demonstration purposes.
+End users can call functions to retrieve sample EOB (Explanation of Benefits) and 837 claim data.
+"""
+
+import importlib.resources
+import json
+from typing import List, Dict, Any, Union, Optional
+from pathlib import Path
+
+
+class SampleData:
+    """
+    A class that provides access to sample data files included with the HCCInFHIR package.
+    
+    This class allows end users to easily retrieve sample EOB and 837 claim data
+    for testing, development, and demonstration purposes.
+    """
+    
+    @staticmethod
+    def get_eob_sample(case_number: int = 1) -> Dict[str, Any]:
+        """
+        Retrieve a specific EOB sample by case number.
+        
+        Args:
+            case_number: The case number (1, 2, or 3). Default is 1.
+            
+        Returns:
+            A dictionary containing the EOB data
+            
+        Raises:
+            ValueError: If case_number is not 1, 2, or 3
+            FileNotFoundError: If the sample file cannot be found
+            
+        Example:
+            >>> sample_data = SampleData.get_eob_sample(1)
+            >>> print(sample_data['resourceType'])
+            'ExplanationOfBenefit'
+        """
+        if case_number not in [1, 2, 3]:
+            raise ValueError("case_number must be 1, 2, or 3")
+        
+        try:
+            with importlib.resources.open_text('hccinfhir.samples', f'sample_eob_{case_number}.json') as f:
+                return json.load(f)
+        except FileNotFoundError:
+            raise FileNotFoundError(f"Sample EOB case {case_number} not found")
+    
+    @staticmethod
+    def get_eob_sample_list(limit: Optional[int] = None) -> List[Dict[str, Any]]:
+        """
+        Retrieve a list of EOB samples from the large sample file.
+        
+        Args:
+            limit: Maximum number of samples to return. If None, returns all 200 samples.
+            
+        Returns:
+            A list of EOB data dictionaries
+            
+        Raises:
+            FileNotFoundError: If the sample file cannot be found
+            
+        Example:
+            >>> # Get first 10 samples
+            >>> samples = SampleData.get_eob_sample_list(limit=10)
+            >>> print(len(samples))
+            10
+            
+            >>> # Get all 200 samples
+            >>> all_samples = SampleData.get_eob_sample_list()
+            >>> print(len(all_samples))
+            200
+        """
+        try:
+            output = []
+            with importlib.resources.open_text('hccinfhir.samples', 'sample_eob_200.ndjson') as f:
+                for i, line in enumerate(f):
+                    if limit is not None and i >= limit:
+                        break
+                    eob_data = json.loads(line)
+                    output.append(eob_data)
+            return output
+        except FileNotFoundError:
+            raise FileNotFoundError("Sample EOB list file not found")
+    
+    @staticmethod
+    def get_837_sample(case_number: int = 0) -> str:
+        """
+        Retrieve a specific 837 claim sample by case number.
+        
+        Args:
+            case_number: The case number (0 through 11). Default is 0.
+            
+        Returns:
+            A string containing the 837 X12 claim data
+            
+        Raises:
+            ValueError: If case_number is not between 0 and 11
+            FileNotFoundError: If the sample file cannot be found
+            
+        Example:
+            >>> sample_837 = SampleData.get_837_sample(0)
+            >>> print("ISA" in sample_837)
+            True
+        """
+        if case_number < 0 or case_number > 11:
+            raise ValueError("case_number must be between 0 and 11")
+        
+        try:
+            with importlib.resources.open_text('hccinfhir.samples', f'sample_837_{case_number}.txt') as f:
+                return f.read()
+        except FileNotFoundError:
+            raise FileNotFoundError(f"Sample 837 case {case_number} not found")
+    
+    @staticmethod
+    def get_837_sample_list(case_numbers: Optional[List[int]] = None) -> List[str]:
+        """
+        Retrieve 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
+            
+        Raises:
+            ValueError: If any case_number is not between 0 and 11
+            FileNotFoundError: If any sample file cannot be found
+            
+        Example:
+            >>> # Get specific cases
+            >>> samples = SampleData.get_837_sample_list([0, 1, 2])
+            >>> print(len(samples))
+            3
+            
+            >>> # Get all samples
+            >>> all_samples = SampleData.get_837_sample_list()
+            >>> print(len(all_samples))
+            12
+        """
+        if case_numbers is None:
+            case_numbers = list(range(12))  # 0 through 11
+        
+        # Validate case numbers
+        for case_num in case_numbers:
+            if case_num < 0 or case_num > 11:
+                raise ValueError(f"case_number {case_num} must be between 0 and 11")
+        
+        output = []
+        for case_num in case_numbers:
+            try:
+                with importlib.resources.open_text('hccinfhir.samples', f'sample_837_{case_num}.txt') as f:
+                    output.append(f.read())
+            except FileNotFoundError:
+                raise FileNotFoundError(f"Sample 837 case {case_num} not found")
+        
+        return output
+    
+    @staticmethod
+    def list_available_samples() -> Dict[str, Any]:
+        """
+        Get information about all available sample data.
+        
+        Returns:
+            A dictionary containing information about available samples
+            
+        Example:
+            >>> info = SampleData.list_available_samples()
+            >>> print(info['eob_samples'])
+            ['sample_eob_1.json', 'sample_eob_2.json', 'sample_eob_3.json', 'sample_eob_200.ndjson']
+        """
+        return {
+            "eob_samples": [
+                "sample_eob_1.json",
+                "sample_eob_2.json", 
+                "sample_eob_3.json",
+                "sample_eob_200.ndjson"
+            ],
+            "eob_case_numbers": [1, 2, 3],
+            "eob_list_size": 200,
+            "837_samples": [f"sample_837_{i}.txt" for i in range(12)],
+            "837_case_numbers": list(range(12)),
+            "description": {
+                "eob": "Explanation of Benefits (FHIR resources) for testing HCC calculations",
+                "837": "X12 837 claim data for testing claim processing"
+            }
+        }
+
+
+# Convenience functions for easy access
+def get_eob_sample(case_number: int = 1) -> Dict[str, Any]:
+    """
+    Convenience function to get an EOB sample.
+    
+    Args:
+        case_number: The case number (1, 2, or 3). Default is 1.
+        
+    Returns:
+        A dictionary containing the EOB data
+    """
+    return SampleData.get_eob_sample(case_number)
+
+
+def get_eob_sample_list(limit: Optional[int] = None) -> List[Dict[str, Any]]:
+    """
+    Convenience function to get a list of EOB samples.
+    
+    Args:
+        limit: Maximum number of samples to return. If None, returns all 200 samples.
+        
+    Returns:
+        A list of EOB data dictionaries
+    """
+    return SampleData.get_eob_sample_list(limit)
+
+
+def get_837_sample(case_number: int = 0) -> str:
+    """
+    Convenience function to get an 837 claim sample.
+    
+    Args:
+        case_number: The case number (0 through 11). Default is 0.
+        
+    Returns:
+        A string containing the 837 X12 claim data
+    """
+    return SampleData.get_837_sample(case_number)
+
+
+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 list_available_samples() -> Dict[str, Any]:
+    """
+    Convenience function to get information about available samples.
+    
+    Returns:
+        A dictionary containing information about available samples
+    """
+    return SampleData.list_available_samples()