hccinfhir 0.0.3__tar.gz → 0.0.5__tar.gz

{hccinfhir-0.0.3 → hccinfhir-0.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: hccinfhir
-Version: 0.0.3
+Version: 0.0.5
 Summary: HCC Algorithm for FHIR Resources
 Project-URL: Homepage, https://github.com/mimilabs/hccinfhir
 Project-URL: Issues, https://github.com/mimilabs/hccinfhir/issues
@@ -20,6 +20,9 @@ A Python library for extracting standardized service-level data from FHIR Explan
 - Support for both BCDA (Blue Button 2.0) and standard FHIR R4 formats
 - Pydantic models for type safety and data validation
 - Standardized Service Level Data (SLD) output format
+- Multiple HCC model support (V22, V24, V28, ESRD V21, ESRD V24, RxHCC V08)
+- Flexible input options: FHIR EOBs, service data, or direct diagnosis codes
+
 
 ## Installation
 ```bash
@@ -45,7 +48,26 @@ sld = [{
 }, ...]
 ```
 
-For more details on the SLD format, see the `models.py` file.
+Or, for direct risk score calculation from a list of diagnosis codes, you only need the model name, diagnosis codes, and basic demographic factors:
+
+```python
+from hccinfhir.model_calculate import calculate_raf
+
+diagnosis_codes = ['E119', 'I509']  # Diabetes without complications, Heart failure
+age = 67
+sex = 'F'
+model_name = "CMS-HCC Model V24"
+
+result = calculate_raf(
+   diagnosis_codes=diagnosis_codes,
+   model_name=model_name,
+   age=age,
+   sex=sex
+)
+```
+
+
+For more details on the SLD format, see the `datamodels.py` file.
 
 ## Core Components
 
@@ -71,23 +93,99 @@ filtered_sld = apply_filter(sld_list)
 ```
 
 
-### 3. Logic Module (In Development)
+### 3. Logic Module 
 Implements core HCC calculation logic:
 - Maps diagnosis codes to HCC categories
 - Applies hierarchical rules and interactions
 - Calculates final RAF scores
 - Integrates with standard CMS data files
 
-## Usage
 ```python
-from hccinfhir import HCCInFHIR
+from hccinfhir.model_calculate import calculate_raf
+
+diagnosis_codes = ['E119', 'I509']  # Diabetes without complications, Heart failure
+result = calculate_raf(
+   diagnosis_codes=diagnosis_codes,
+   model_name="CMS-HCC Model V24",
+   age=67,
+   sex='F'
+)
+```
 
-hcc_processor = HCCInFHIR()
-sld_list = hcc_processor.extract_sld_list(eob_list)
-filtered_sld = hcc_processor.apply_filters(sld_list)  # future
-raf_details = hcc_processor.calculate_raf(filtered_sld, demographic_data)  # future
+### 4. HCCInFHIR Class
+The main processor class that integrates extraction, filtering, and calculation components:
+
+```python
+from hccinfhir.hccinfhir import HCCInFHIR
+from hccinfhir.datamodels import Demographics
+
+# Initialize with custom configuration
+hcc_processor = HCCInFHIR(
+    filter_claims=True,                                    # Enable claim filtering
+    model_name="CMS-HCC Model V28",                       # Choose HCC model version
+    proc_filtering_filename="ra_eligible_cpt_hcpcs_2025.csv",  # CPT/HCPCS filtering rules
+    dx_cc_mapping_filename="ra_dx_to_cc_2025.csv"         # Diagnosis to CC mapping
+)
+
+# Define beneficiary demographics
+demographics = Demographics(
+    age=67,
+    sex='F',
+    dual_elgbl_cd='00',    # Not dual eligible
+    orec='0',              # Old age
+    crec='0',              # Current old age
+    new_enrollee=False,
+    snp=False
+)
+
+# Method 1: Process FHIR EOB resources
+raf_result = hcc_processor.run(eob_list, demographics)
+
+# Method 2: Process service level data
+service_data = [{
+    "procedure_code": "99214",
+    "claim_diagnosis_codes": ["E11.9", "I10"],
+    "claim_type": "71",
+    "service_date": "2024-01-15"
+}]
+raf_result = hcc_processor.run_from_service_data(service_data, demographics)
+
+# Method 3: Direct diagnosis processing
+diagnosis_codes = ['E119', 'I509']
+raf_result = hcc_processor.calculate_from_diagnosis(diagnosis_codes, demographics)
+
+# RAF Result contains:
+print(f"Risk Score: {raf_result['risk_score']}")
+print(f"HCC List: {raf_result['hcc_list']}")
+print(f"CC to Diagnosis Mapping: {raf_result['cc_to_dx']}")
+print(f"Applied Coefficients: {raf_result['coefficients']}")
+print(f"Applied Interactions: {raf_result['interactions']}")
 ```
 
+The HCCInFHIR class provides three main processing methods:
+
+1. `run(eob_list, demographics)`: Process FHIR ExplanationOfBenefit resources
+   - Extracts service data from FHIR resources
+   - Applies filtering rules if enabled
+   - Calculates RAF scores using the specified model
+
+2. `run_from_service_data(service_data, demographics)`: Process standardized service data
+   - Accepts pre-formatted service level data
+   - Validates data structure using Pydantic models
+   - Applies filtering and calculates RAF scores
+
+3. `calculate_from_diagnosis(diagnosis_codes, demographics)`: Direct diagnosis processing
+   - Processes raw diagnosis codes without service context
+   - Useful for quick RAF calculations or validation
+   - Bypasses service-level filtering
+
+Each method returns a RAFResult containing:
+- Final risk score
+- List of HCCs
+- Mapping of condition categories to diagnosis codes
+- Applied coefficients and interactions
+- Processed service level data (when applicable)
+
 ## Testing
 ```bash
 $ python3 -m hatch shell
@@ -172,8 +270,48 @@ $ python3 -m pytest tests/*
 3. Add support for allowed_amount in 837 if available in different segments
 4. Consider adding more robust error handling in both implementations
 
+## Data Files
+
+`ra_dx_to_cc_mapping_2025.csv`
+```sql
+SELECT diagnosis_code, cc, model_name 
+FROM ra_dx_to_cc_mapping 
+WHERE year = 2025 and model_type = 'Initial';
+```
+
+`ra_hierarchies_2025.csv`
+```sql
+SELECT cc_parent, 
+  cc_child, 
+  model_domain, 
+  model_version, 
+  model_fullname
+FROM ra_hierarchies
+WHERE eff_last_date > '2025-01-01';
+```
+
+`ra_coefficients_2025.csv`
+```sql
+SELECT coefficient, value, model_domain, model_version 
+FROM ra_coefficients 
+WHERE eff_last_date > '2025-01-01';
+```   
+
+`ra_eligible_cpt_hcpcs_2025.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;
+```
+
 ## Contributing
 Join us at [mimilabs](https://mimilabs.ai/signup). Reference data available in MIMILabs data lakehouse.
 
+## Publishing (only for those maintainers...)
+```bash
+$ hatch build
+$ hatch publish
+```
+
 ## License
 Apache License 2.0

{hccinfhir-0.0.3 → hccinfhir-0.0.5}/README.md

@@ -6,6 +6,9 @@ A Python library for extracting standardized service-level data from FHIR Explan
 - Support for both BCDA (Blue Button 2.0) and standard FHIR R4 formats
 - Pydantic models for type safety and data validation
 - Standardized Service Level Data (SLD) output format
+- Multiple HCC model support (V22, V24, V28, ESRD V21, ESRD V24, RxHCC V08)
+- Flexible input options: FHIR EOBs, service data, or direct diagnosis codes
+
 
 ## Installation
 ```bash
@@ -31,7 +34,26 @@ sld = [{
 }, ...]
 ```
 
-For more details on the SLD format, see the `models.py` file.
+Or, for direct risk score calculation from a list of diagnosis codes, you only need the model name, diagnosis codes, and basic demographic factors:
+
+```python
+from hccinfhir.model_calculate import calculate_raf
+
+diagnosis_codes = ['E119', 'I509']  # Diabetes without complications, Heart failure
+age = 67
+sex = 'F'
+model_name = "CMS-HCC Model V24"
+
+result = calculate_raf(
+   diagnosis_codes=diagnosis_codes,
+   model_name=model_name,
+   age=age,
+   sex=sex
+)
+```
+
+
+For more details on the SLD format, see the `datamodels.py` file.
 
 ## Core Components
 
@@ -57,23 +79,99 @@ filtered_sld = apply_filter(sld_list)
 ```
 
 
-### 3. Logic Module (In Development)
+### 3. Logic Module 
 Implements core HCC calculation logic:
 - Maps diagnosis codes to HCC categories
 - Applies hierarchical rules and interactions
 - Calculates final RAF scores
 - Integrates with standard CMS data files
 
-## Usage
 ```python
-from hccinfhir import HCCInFHIR
+from hccinfhir.model_calculate import calculate_raf
+
+diagnosis_codes = ['E119', 'I509']  # Diabetes without complications, Heart failure
+result = calculate_raf(
+   diagnosis_codes=diagnosis_codes,
+   model_name="CMS-HCC Model V24",
+   age=67,
+   sex='F'
+)
+```
 
-hcc_processor = HCCInFHIR()
-sld_list = hcc_processor.extract_sld_list(eob_list)
-filtered_sld = hcc_processor.apply_filters(sld_list)  # future
-raf_details = hcc_processor.calculate_raf(filtered_sld, demographic_data)  # future
+### 4. HCCInFHIR Class
+The main processor class that integrates extraction, filtering, and calculation components:
+
+```python
+from hccinfhir.hccinfhir import HCCInFHIR
+from hccinfhir.datamodels import Demographics
+
+# Initialize with custom configuration
+hcc_processor = HCCInFHIR(
+    filter_claims=True,                                    # Enable claim filtering
+    model_name="CMS-HCC Model V28",                       # Choose HCC model version
+    proc_filtering_filename="ra_eligible_cpt_hcpcs_2025.csv",  # CPT/HCPCS filtering rules
+    dx_cc_mapping_filename="ra_dx_to_cc_2025.csv"         # Diagnosis to CC mapping
+)
+
+# Define beneficiary demographics
+demographics = Demographics(
+    age=67,
+    sex='F',
+    dual_elgbl_cd='00',    # Not dual eligible
+    orec='0',              # Old age
+    crec='0',              # Current old age
+    new_enrollee=False,
+    snp=False
+)
+
+# Method 1: Process FHIR EOB resources
+raf_result = hcc_processor.run(eob_list, demographics)
+
+# Method 2: Process service level data
+service_data = [{
+    "procedure_code": "99214",
+    "claim_diagnosis_codes": ["E11.9", "I10"],
+    "claim_type": "71",
+    "service_date": "2024-01-15"
+}]
+raf_result = hcc_processor.run_from_service_data(service_data, demographics)
+
+# Method 3: Direct diagnosis processing
+diagnosis_codes = ['E119', 'I509']
+raf_result = hcc_processor.calculate_from_diagnosis(diagnosis_codes, demographics)
+
+# RAF Result contains:
+print(f"Risk Score: {raf_result['risk_score']}")
+print(f"HCC List: {raf_result['hcc_list']}")
+print(f"CC to Diagnosis Mapping: {raf_result['cc_to_dx']}")
+print(f"Applied Coefficients: {raf_result['coefficients']}")
+print(f"Applied Interactions: {raf_result['interactions']}")
 ```
 
+The HCCInFHIR class provides three main processing methods:
+
+1. `run(eob_list, demographics)`: Process FHIR ExplanationOfBenefit resources
+   - Extracts service data from FHIR resources
+   - Applies filtering rules if enabled
+   - Calculates RAF scores using the specified model
+
+2. `run_from_service_data(service_data, demographics)`: Process standardized service data
+   - Accepts pre-formatted service level data
+   - Validates data structure using Pydantic models
+   - Applies filtering and calculates RAF scores
+
+3. `calculate_from_diagnosis(diagnosis_codes, demographics)`: Direct diagnosis processing
+   - Processes raw diagnosis codes without service context
+   - Useful for quick RAF calculations or validation
+   - Bypasses service-level filtering
+
+Each method returns a RAFResult containing:
+- Final risk score
+- List of HCCs
+- Mapping of condition categories to diagnosis codes
+- Applied coefficients and interactions
+- Processed service level data (when applicable)
+
 ## Testing
 ```bash
 $ python3 -m hatch shell
@@ -158,8 +256,48 @@ $ python3 -m pytest tests/*
 3. Add support for allowed_amount in 837 if available in different segments
 4. Consider adding more robust error handling in both implementations
 
+## Data Files
+
+`ra_dx_to_cc_mapping_2025.csv`
+```sql
+SELECT diagnosis_code, cc, model_name 
+FROM ra_dx_to_cc_mapping 
+WHERE year = 2025 and model_type = 'Initial';
+```
+
+`ra_hierarchies_2025.csv`
+```sql
+SELECT cc_parent, 
+  cc_child, 
+  model_domain, 
+  model_version, 
+  model_fullname
+FROM ra_hierarchies
+WHERE eff_last_date > '2025-01-01';
+```
+
+`ra_coefficients_2025.csv`
+```sql
+SELECT coefficient, value, model_domain, model_version 
+FROM ra_coefficients 
+WHERE eff_last_date > '2025-01-01';
+```   
+
+`ra_eligible_cpt_hcpcs_2025.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;
+```
+
 ## Contributing
 Join us at [mimilabs](https://mimilabs.ai/signup). Reference data available in MIMILabs data lakehouse.
 
+## Publishing (only for those maintainers...)
+```bash
+$ hatch build
+$ hatch publish
+```
+
 ## License
 Apache License 2.0