hccinfhir 0.1.1__py3-none-any.whl → 0.1.3__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.1.dist-info → hccinfhir-0.1.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: hccinfhir
-Version: 0.1.1
+Version: 0.1.3
 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

{hccinfhir-0.1.1.dist-info → hccinfhir-0.1.3.dist-info}/RECORD

@@ -1,16 +1,18 @@
-hccinfhir/__init__.py,sha256=OCyYCv4jTOlYHZbTw2DTks3e6_YT1N2JXAOuyR03KNE,43
+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.py,sha256=xL9c2VT-e2I7_c8N8j4Og42UEgVuCzyn9WFp3ntM5Ro,1822
+hccinfhir/extractor_837.py,sha256=VWBZdMZpHwDhSAotx7uuYiCIHsRlpsDmOi5E3v8mgBU,10866
 hccinfhir/extractor_fhir.py,sha256=Rg_L0Vg5tz_L2VJ_jvZwWz6RMlPAkHwj4LiK-OWQvrQ,8458
-hccinfhir/filter.py,sha256=8uYThN0-AqwVAKyti29WGiFwQKDiremMhYd_m6QcXhM,2193
-hccinfhir/hccinfhir.py,sha256=gVdQ6e1rJRVwIEcSw2cAUjnXH5WsCqaeDudn1Ol2_0w,6837
+hccinfhir/filter.py,sha256=j_yD2g6RBXVUV9trKkWzsQ35x3fRvfKUPvEXKUefI64,2007
+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
@@ -21,9 +23,9 @@ hccinfhir/data/ra_dx_to_cc_2026.csv,sha256=YT9HwQFUddL_bxuE9nxHWsBtZzojINL0DzABB
 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=1oXFcLJQPF_fbGd1sLZU6IPolKCXOculovqIUAoMgLc,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=Q7xi5PpgJ4LETadup4vKoKud9ZWeu2OZVpwgr4VLpMw,19248
+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
@@ -41,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.1.dist-info/METADATA,sha256=t5eApNi_1F-OCQiB16B2W6AUxS-mPpRTni6swrLqbRg,12881
-hccinfhir-0.1.1.dist-info/WHEEL,sha256=C2FUgwZgiLbznR-k0b_5k3Ai_1aASOXDss3lzCUsUug,87
-hccinfhir-0.1.1.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-hccinfhir-0.1.1.dist-info/RECORD,,
+hccinfhir-0.1.3.dist-info/METADATA,sha256=VuJalbxDC35qPO0YOr-a4DEyKwXo_YlyrKvb5Trh5oY,13535
+hccinfhir-0.1.3.dist-info/WHEEL,sha256=C2FUgwZgiLbznR-k0b_5k3Ai_1aASOXDss3lzCUsUug,87
+hccinfhir-0.1.3.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+hccinfhir-0.1.3.dist-info/RECORD,,