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

hccinfhir/data/ra_hierarchies_2026.csv

@@ -330,6 +330,12 @@ cc_parent,cc_child,model_domain,model_version,model_fullname
 19,21,CMS-HCC,V28,V28115H1
 19,22,CMS-HCC,V28,V28115H1
 19,23,CMS-HCC,V28,V28115H1
+191,180,CMS-HCC,V28,V28115H1
+191,181,CMS-HCC,V28,V28115H1
+191,182,CMS-HCC,V28,V28115H1
+191,192,CMS-HCC,V28,V28115H1
+191,253,CMS-HCC,V28,V28115H1
+191,254,CMS-HCC,V28,V28115H1
 195,196,CMS-HCC,V28,V28115H1
 20,21,CMS-HCC,V28,V28115H1
 20,22,CMS-HCC,V28,V28115H1
@@ -340,6 +346,12 @@ cc_parent,cc_child,model_domain,model_version,model_fullname
 211,213,CMS-HCC,V28,V28115H1
 212,213,CMS-HCC,V28,V28115H1
 22,23,CMS-HCC,V28,V28115H1
+221,222,CMS-HCC,V28,V28115H1
+221,223,CMS-HCC,V28,V28115H1
+221,224,CMS-HCC,V28,V28115H1
+221,225,CMS-HCC,V28,V28115H1
+221,226,CMS-HCC,V28,V28115H1
+221,227,CMS-HCC,V28,V28115H1
 223,224,CMS-HCC,V28,V28115H1
 223,225,CMS-HCC,V28,V28115H1
 223,226,CMS-HCC,V28,V28115H1

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

@@ -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/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()

hccinfhir/samples.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()

{hccinfhir-0.1.1.dist-info → hccinfhir-0.1.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: hccinfhir
-Version: 0.1.1
+Version: 0.1.2
 Summary: HCC Algorithm for FHIR Resources
 Project-URL: Homepage, https://github.com/mimilabs/hccinfhir
 Project-URL: Issues, https://github.com/mimilabs/hccinfhir/issues
@@ -69,6 +69,34 @@ result = calculate_raf(
 
 For more details on the SLD format, see the `datamodels.py` file.
 
+## Sample Data
+
+The package includes comprehensive sample data for testing and demonstration purposes:
+
+```python
+from hccinfhir import (
+    get_eob_sample,
+    get_eob_sample_list,
+    get_837_sample,
+    get_837_sample_list,
+    list_available_samples
+)
+
+# Get individual EOB samples (cases 1, 2, or 3)
+eob_data = get_eob_sample(1)
+
+# Get multiple EOB samples (up to 200 available)
+eob_list = get_eob_sample_list(limit=10)
+
+# Get 837 claim samples (cases 0 through 11)
+claim_data = get_837_sample(0)
+
+# Get information about available samples
+info = list_available_samples()
+```
+
+For detailed usage examples, see the `examples/sample_data_usage.py` file.
+
 ## Core Components
 
 ### 1. Extractor Module
@@ -352,9 +380,10 @@ WHERE is_included = 'yes' AND YEAR(mimi_src_file_date) = 2025;
 Join us at [mimilabs](https://mimilabs.ai/signup). Reference data available in MIMILabs data lakehouse.
 
 ## Publishing (only for those maintainers...)
+Inside the hatch
 ```bash
-$ python3 -m hatch build
-$ python3 -m hatch publish
+$ hatch build
+$ hatch publish
 ```
 
 ## License