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

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.0.dist-info → hccinfhir-0.1.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: hccinfhir
-Version: 0.1.0
+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
@@ -182,10 +210,12 @@ Each method returns a RAFResult containing:
 - Processed service level data (when applicable)
 
 ## Testing
+
+After installing `hatch`
 ```bash
-$ python3 -m hatch shell
-$ python3 -m pip install -e .
-$ python3 -m pytest tests/*
+$ hatch shell
+$ pip install -e .
+$ pytest tests/*
 ``` 
 
 ## Dependencies
@@ -267,45 +297,93 @@ $ python3 -m pytest tests/*
 
 ## Data Files
 
-`ra_dx_to_cc_mapping_2025.csv`
+`ra_dx_to_cc_mapping_2026.csv`
 ```sql
-SELECT diagnosis_code, cc, model_name 
-FROM ra_dx_to_cc_mapping 
-WHERE year = 2025 and model_type = 'Initial';
+WITH latest_years AS (
+  SELECT 
+    model_name,
+    MAX(year) as latest_year
+  FROM mimi_ws_1.cmspayment.ra_dx_to_cc_mapping 
+  WHERE model_type = 'Initial'
+    AND year <= 2026  -- Don't go beyond 2026
+  GROUP BY model_name
+)
+SELECT 
+  r.diagnosis_code, 
+  r.cc, 
+  r.model_name
+FROM mimi_ws_1.cmspayment.ra_dx_to_cc_mapping r
+INNER JOIN latest_years l 
+  ON r.model_name = l.model_name 
+  AND r.year = l.latest_year
+WHERE r.model_type = 'Initial'
+ORDER BY r.model_name, r.diagnosis_code;
 ```
 
-`ra_hierarchies_2025.csv`
+`ra_hierarchies_2026.csv`
 ```sql
-SELECT cc_parent, 
-  cc_child, 
-  model_domain, 
-  model_version, 
-  model_fullname
-FROM ra_hierarchies
-WHERE eff_last_date > '2025-01-01';
+WITH latest_dates AS (
+  SELECT 
+    model_domain,
+    model_version,
+    model_fullname,
+    MAX(eff_last_date) as latest_eff_last_date
+  FROM mimi_ws_1.cmspayment.ra_hierarchies 
+  GROUP BY model_domain, model_version, model_fullname
+)
+SELECT 
+  r.cc_parent, 
+  r.cc_child, 
+  r.model_domain, 
+  r.model_version, 
+  r.model_fullname
+FROM mimi_ws_1.cmspayment.ra_hierarchies r
+INNER JOIN latest_dates l 
+  ON r.model_domain = l.model_domain 
+  AND r.model_version = l.model_version
+  AND r.model_fullname = l.model_fullname
+  AND r.eff_last_date = l.latest_eff_last_date
+ORDER BY r.model_domain, r.model_version, r.model_fullname, r.cc_parent, r.cc_child;
 ```
 
-`ra_coefficients_2025.csv`
+`ra_coefficients_2026.csv`
 ```sql
-SELECT coefficient, value, model_domain, model_version 
-FROM ra_coefficients 
-WHERE eff_last_date > '2025-01-01';
+WITH preferred_records AS (
+  SELECT 
+    model_domain,
+    model_version,
+    MAX(eff_last_date) as latest_eff_last_date
+  FROM mimi_ws_1.cmspayment.ra_coefficients
+  GROUP BY model_domain, model_version
+)
+SELECT 
+  r.coefficient,
+  r.value, 
+  r.model_domain, 
+  r.model_version
+FROM mimi_ws_1.cmspayment.ra_coefficients r
+INNER JOIN preferred_records p
+  ON r.model_domain = p.model_domain 
+  AND r.model_version = p.model_version
+  AND r.eff_last_date = p.latest_eff_last_date
+ORDER BY r.model_domain, r.model_version, r.coefficient;
 ```   
 
-`ra_eligible_cpt_hcpcs_2025.csv`
+`ra_eligible_cpt_hcpcs_2026.csv`
 ```sql
 SELECT DISTINCT cpt_hcpcs_code
 FROM mimi_ws_1.cmspayment.ra_eligible_cpt_hcpcs
-WHERE is_included = 'yes' AND YEAR(mimi_src_file_date) = 2024;
+WHERE is_included = 'yes' AND YEAR(mimi_src_file_date) = 2025;
 ```
 
 ## Contributing
 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

{hccinfhir-0.1.0.dist-info → hccinfhir-0.1.2.dist-info}/RECORD

@@ -1,25 +1,31 @@
-hccinfhir/__init__.py,sha256=OCyYCv4jTOlYHZbTw2DTks3e6_YT1N2JXAOuyR03KNE,43
-hccinfhir/datamodels.py,sha256=2zdJf7oBF1j281bbi3hzIUWInUrWeU6IsC51EoV14Mo,4972
+hccinfhir/__init__.py,sha256=UBTJCLzkCGNCMpG38vkpu3DeMM_RV_7o5JjOWL7ps9c,1048
+hccinfhir/datamodels.py,sha256=lMLGSuWTlpzoWenKsfhF8qQF3RZJV2NNGyIm_rBkd0o,5038
 hccinfhir/extractor.py,sha256=-jHVCIJqFAqvrI9GxkkXZVDQjKDa-7vF7v3PGMGAMnA,1801
 hccinfhir/extractor_837.py,sha256=vkTBCd0WBaJoTrUd-Z-zCIaoLk7KV2n4AGqIORhONIk,7147
 hccinfhir/extractor_fhir.py,sha256=Rg_L0Vg5tz_L2VJ_jvZwWz6RMlPAkHwj4LiK-OWQvrQ,8458
-hccinfhir/filter.py,sha256=8uYThN0-AqwVAKyti29WGiFwQKDiremMhYd_m6QcXhM,2193
-hccinfhir/hccinfhir.py,sha256=DxTkqbgVXsOsvX1M_UXemb68UMfC8oVCGus2CYIAiTM,6837
-hccinfhir/model_calculate.py,sha256=0IJctgfROAJR_3FU_x3VbX0oS3cyn29hFBzbkbEjoOs,4718
-hccinfhir/model_coefficients.py,sha256=UrDAEWBoqooSC8hy9YSUsLMmmfgIO0YGtVkui6ruOkE,5528
-hccinfhir/model_demographics.py,sha256=CMnD2-Au9Q6HNZrJUZqVVJRDEmSuK8ZpF39I22JkX8M,6564
-hccinfhir/model_dx_to_cc.py,sha256=jCFlnAOBkfI9FrCX6tZIh-Sp_DW0HwpY7QrPXGtwInI,1765
-hccinfhir/model_hierarchies.py,sha256=e8QtSayTrfPv2wh149FjK7ToiEmU1ISYMA1Pi38iVk0,2700
+hccinfhir/filter.py,sha256=YjhOG5jJZZOfBJ1-cDuRs-htrLF07oceoD74PbL8rms,1890
+hccinfhir/hccinfhir.py,sha256=KzEPwZQn5qcG8e44I8EahzhWXP9fYR18U4SHTA1DGcI,6855
+hccinfhir/model_calculate.py,sha256=3lKpNSdTNFn3OREw8yjlOhoNcDhs7LpQj7TIHQ1HvxQ,5519
+hccinfhir/model_coefficients.py,sha256=ZsVY0S_X_BzDvcCmzCEf31v8uixbGmPAsR6nVEyCbIA,5530
+hccinfhir/model_demographics.py,sha256=7W5NLW7aAjpn25BJzqfP8iSouD9uA6epGguJJ6BPuC0,7043
+hccinfhir/model_dx_to_cc.py,sha256=guJny2Mb9z8YRNWCXGSIE3APbE06zwnA2NRkjAeUs60,1765
+hccinfhir/model_hierarchies.py,sha256=0kdBmF_8e_ikMHBDhlw2I7jT3DupHfUn6o5mWj7v3Yo,2910
 hccinfhir/model_interactions.py,sha256=ZLiKJepPjPkYceKDf7dLXoYE0p44I7t9y2sTOlrxojo,20264
+hccinfhir/sample_utils.py,sha256=yXTa0UGLiNxOeHBOGQQwLyTHVMhp52kWqxzTNDUsm8E,8426
+hccinfhir/samples.py,sha256=yXTa0UGLiNxOeHBOGQQwLyTHVMhp52kWqxzTNDUsm8E,8426
 hccinfhir/utils.py,sha256=AAHwzMSW8O9VZp1KLcdlN3OeBbxQtqQRtbTTdrKf7M0,2784
 hccinfhir/data/__init__.py,sha256=SGiSkpGrnxbvtEFMMlk82NFHOE50hFXcgKwKUSuVZUg,45
 hccinfhir/data/hcc_is_chronic.csv,sha256=eVVI4_8mQNkiBiNO3kattfT_zfcV18XgmiltdzZEXSo,17720
 hccinfhir/data/ra_coefficients_2025.csv,sha256=I0S2hoJlfig-D0oSFxy0b3Piv7m9AzOGo2CwR6bcQ9w,215191
+hccinfhir/data/ra_coefficients_2026.csv,sha256=0gfjGgVdIEWkBO01NaAbTLMzHCYINA0rf_zl8ojngCY,288060
 hccinfhir/data/ra_dx_to_cc_2025.csv,sha256=4N7vF6VZndkl7d3Fo0cGsbAPAZdCjAizSH8BOKsZNAo,1618924
+hccinfhir/data/ra_dx_to_cc_2026.csv,sha256=YT9HwQFUddL_bxuE9nxHWsBtZzojINL0DzABBMp6kms,1751007
 hccinfhir/data/ra_eligible_cpt_hcpcs_2023.csv,sha256=VVoA4s0hsFmcRIugyFdbvSoeLcn7M7z0DITT6l4YqL8,39885
 hccinfhir/data/ra_eligible_cpt_hcpcs_2024.csv,sha256=CawKImfCb8fFMDbWwqvNLRyRAda_u9N8Q3ne8QAAe54,40191
 hccinfhir/data/ra_eligible_cpt_hcpcs_2025.csv,sha256=-tMvv2su5tsSbGUh6fZZCMUEkXInBpcTtbUCi2o_UwI,40359
+hccinfhir/data/ra_eligible_cpt_hcpcs_2026.csv,sha256=EYGN7k_rgCpJe59lL_yNInUcCkdETDWGSFTXII3LZ0Y,40497
 hccinfhir/data/ra_hierarchies_2025.csv,sha256=HQSPNloe6mvvwMgv8ZwYAfWKkT2b2eUvm4JQy6S_mVQ,13045
+hccinfhir/data/ra_hierarchies_2026.csv,sha256=A6ZQZb0rpRWrySBB_KA5S4PGtMxWuzB2guU3aBE09v0,19596
 hccinfhir/samples/__init__.py,sha256=SGiSkpGrnxbvtEFMMlk82NFHOE50hFXcgKwKUSuVZUg,45
 hccinfhir/samples/sample_837_0.txt,sha256=eggrD259uHa05z2dfxWBpUDseSDp_AQcLyN_adpHyTw,5295
 hccinfhir/samples/sample_837_1.txt,sha256=E155MdemSDYoXokuTXUZ6Br_RGGedYv5t5dh-eMRmuk,1322
@@ -37,7 +43,7 @@ hccinfhir/samples/sample_eob_1.json,sha256=_NGSVR2ysFpx-DcTvyga6dFCzhQ8Vi9fNzQEM
 hccinfhir/samples/sample_eob_2.json,sha256=FcnJcx0ApOczxjJ_uxVLzCep9THfNf4xs9Yf7hxk8e4,1769
 hccinfhir/samples/sample_eob_200.ndjson,sha256=CxpjeQ1DCMUzZILaM68UEhfxO0p45YGhDDoCZeq8PxU,1917986
 hccinfhir/samples/sample_eob_3.json,sha256=4BW4wOMBEEU9RDfJR15rBEvk0KNHyuMEh3e055y87Hc,2306
-hccinfhir-0.1.0.dist-info/METADATA,sha256=iao0WVikTc_19EBBI3QuSPrO5KSffu_IZFBoiYZkcUs,11567
-hccinfhir-0.1.0.dist-info/WHEEL,sha256=C2FUgwZgiLbznR-k0b_5k3Ai_1aASOXDss3lzCUsUug,87
-hccinfhir-0.1.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-hccinfhir-0.1.0.dist-info/RECORD,,
+hccinfhir-0.1.2.dist-info/METADATA,sha256=AajRjb9nwdxkRwRKIKWVqD9rtwegBZthoMD0pF510Ws,13535
+hccinfhir-0.1.2.dist-info/WHEEL,sha256=C2FUgwZgiLbznR-k0b_5k3Ai_1aASOXDss3lzCUsUug,87
+hccinfhir-0.1.2.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+hccinfhir-0.1.2.dist-info/RECORD,,