hccinfhir 0.1.4__tar.gz → 0.1.6__tar.gz

{hccinfhir-0.1.4 → hccinfhir-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: hccinfhir
-Version: 0.1.4
+Version: 0.1.6
 Summary: HCC Algorithm for FHIR Resources
 Project-URL: Homepage, https://github.com/mimilabs/hccinfhir
 Project-URL: Issues, https://github.com/mimilabs/hccinfhir/issues
@@ -60,12 +60,12 @@ print(f"HCCs: {result.hcc_list}")
 HCCInFHIR supports three primary data sources for HCC risk adjustment calculations:
 
 ### 1. **CMS Encounter Data Records (EDRs)**
-- **Input**: X12 837 envelope files (text format) + demographic data from payers
+- **Input**: X12 837 5010 transaction files (text format) + demographic data from payers
 - **Use Case**: Medicare Advantage plans processing encounter data for CMS submissions
 - **Output**: Risk scores with detailed HCC mappings and interactions
 
 ### 2. **Clearinghouse 837 Claims**
-- **Input**: X12 837 institutional/professional claim files + patient demographics
+- **Input**: X12 837 5010 institutional/professional claim files + patient demographics
 - **Use Case**: Health plans and providers calculating risk scores from claims data
 - **Output**: Service-level analysis with filtering and risk score calculations
 
@@ -535,6 +535,89 @@ export_data = result.model_dump(
 )
 ```
 
+### Overriding Demographic Categorization
+
+**Problem**: Sometimes demographic data has quality issues (e.g., ESRD patients with incorrect `orec`/`crec` codes), leading to wrong risk score calculations.
+
+**Solution**: Use the `prefix_override` parameter to manually specify the coefficient prefix.
+
+#### Common Use Case: ESRD Patients with Incorrect OREC/CREC
+
+```python
+from hccinfhir import HCCInFHIR, Demographics
+
+# ESRD dialysis patient, but source data has wrong orec/crec codes
+processor = HCCInFHIR(model_name="CMS-HCC ESRD Model V24")
+
+demographics = Demographics(
+    age=65,
+    sex="F",
+    orec="0",  # Should be '2' or '3' for ESRD, but data is incorrect
+    crec="0"   # Should be '2' or '3' for ESRD, but data is incorrect
+)
+
+diagnosis_codes = ["N18.6", "E11.22", "I12.0"]  # ESRD + diabetes + hypertensive CKD
+
+# Force ESRD dialysis coefficients despite incorrect orec/crec
+result = processor.calculate_from_diagnosis(
+    diagnosis_codes,
+    demographics,
+    prefix_override='DI_'  # DI_ = ESRD Dialysis
+)
+
+print(f"Risk Score with override: {result.risk_score}")
+```
+
+#### Other Common Scenarios
+
+```python
+# Long-term institutionalized patient not properly flagged
+processor = HCCInFHIR(model_name="CMS-HCC Model V28")
+demographics = Demographics(age=78, sex="M")
+diagnosis_codes = ["F03.90", "I48.91", "N18.4"]
+
+result = processor.calculate_from_diagnosis(
+    diagnosis_codes,
+    demographics,
+    prefix_override='INS_'  # INS_ = Institutionalized
+)
+
+# New enrollee with missing flag
+result = processor.calculate_from_diagnosis(
+    diagnosis_codes,
+    demographics,
+    prefix_override='NE_'  # NE_ = New Enrollee
+)
+```
+
+#### Common Prefix Values
+
+**CMS-HCC Models (V22, V24, V28):**
+- `CNA_` - Community, Non-Dual, Aged (65+)
+- `CND_` - Community, Non-Dual, Disabled (<65)
+- `CFA_` - Community, Full Benefit Dual, Aged
+- `CFD_` - Community, Full Benefit Dual, Disabled
+- `CPA_` - Community, Partial Benefit Dual, Aged
+- `CPD_` - Community, Partial Benefit Dual, Disabled
+- `INS_` - Long-Term Institutionalized
+- `NE_` - New Enrollee
+- `SNPNE_` - Special Needs Plan New Enrollee
+
+**ESRD Models (V21, V24):**
+- `DI_` - Dialysis (standard)
+- `DNE_` - Dialysis New Enrollee
+- `GI_` - Graft, Institutionalized
+- `GNE_` - Graft, New Enrollee
+- `GFPA_`, `GFPN_`, `GNPA_`, `GNPN_` - Graft with various dual/age combinations
+
+**RxHCC Model (V08):**
+- `Rx_CE_LowAged_` - Community, Low Income, Aged
+- `Rx_CE_NoLowAged_` - Community, Not Low Income, Aged
+- `Rx_NE_Lo_` - New Enrollee, Low Income
+- `Rx_CE_LTI_` - Community, Long-Term Institutionalized
+
+See [CLAUDE.md](./CLAUDE.md#coefficient-prefix-reference) for complete prefix reference.
+
 ### Custom Filtering Rules
 
 ```python
@@ -544,7 +627,7 @@ from hccinfhir.filter import apply_filter
 filtered_data = apply_filter(
     service_data,
     include_inpatient=True,
-    include_outpatient=True, 
+    include_outpatient=True,
     eligible_cpt_hcpcs_file="custom_procedures.csv"
 )
 ```
@@ -579,17 +662,105 @@ except ModelNotFoundError as e:
     print(f"Model configuration error: {e}")
 ```
 
-## 🧪 Testing
+### Custom Valuesets
 
-```bash
-# Install development dependencies
-pip install -e ".[dev]"
+Users can generate custom and more specific valuesets using the mimilabs data lakehouse.
+
+For example, the valuesets in the package are created as follows:
+
+`ra_dx_to_cc_mapping_2026.csv`
+```sql
+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;
+```
 
-# Run tests
-pytest tests/
+`ra_hierarchies_2026.csv`
+```sql
+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_2026.csv`
+```sql
+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_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) = 2025;
+```
 
-# Run with coverage
-pytest --cov=hccinfhir tests/
+`hcc_is_chronic.csv`
+```sql
+SELECT hcc, is_chronic, model_version, model_domain
+FROM cmspayment.ra_report_to_congress
+WHERE mimi_src_file_name = '2024riskadjustmentinma-rtc.pdf'
+```
+
+## 🧪 Testing
+
+```bash
+$ hatch shell
+$ pip install -e .
+$ pytest tests/*
 ```
 
 ## 📄 License

{hccinfhir-0.1.4 → hccinfhir-0.1.6}/README.md

@@ -46,12 +46,12 @@ print(f"HCCs: {result.hcc_list}")
 HCCInFHIR supports three primary data sources for HCC risk adjustment calculations:
 
 ### 1. **CMS Encounter Data Records (EDRs)**
-- **Input**: X12 837 envelope files (text format) + demographic data from payers
+- **Input**: X12 837 5010 transaction files (text format) + demographic data from payers
 - **Use Case**: Medicare Advantage plans processing encounter data for CMS submissions
 - **Output**: Risk scores with detailed HCC mappings and interactions
 
 ### 2. **Clearinghouse 837 Claims**
-- **Input**: X12 837 institutional/professional claim files + patient demographics
+- **Input**: X12 837 5010 institutional/professional claim files + patient demographics
 - **Use Case**: Health plans and providers calculating risk scores from claims data
 - **Output**: Service-level analysis with filtering and risk score calculations
 
@@ -521,6 +521,89 @@ export_data = result.model_dump(
 )
 ```
 
+### Overriding Demographic Categorization
+
+**Problem**: Sometimes demographic data has quality issues (e.g., ESRD patients with incorrect `orec`/`crec` codes), leading to wrong risk score calculations.
+
+**Solution**: Use the `prefix_override` parameter to manually specify the coefficient prefix.
+
+#### Common Use Case: ESRD Patients with Incorrect OREC/CREC
+
+```python
+from hccinfhir import HCCInFHIR, Demographics
+
+# ESRD dialysis patient, but source data has wrong orec/crec codes
+processor = HCCInFHIR(model_name="CMS-HCC ESRD Model V24")
+
+demographics = Demographics(
+    age=65,
+    sex="F",
+    orec="0",  # Should be '2' or '3' for ESRD, but data is incorrect
+    crec="0"   # Should be '2' or '3' for ESRD, but data is incorrect
+)
+
+diagnosis_codes = ["N18.6", "E11.22", "I12.0"]  # ESRD + diabetes + hypertensive CKD
+
+# Force ESRD dialysis coefficients despite incorrect orec/crec
+result = processor.calculate_from_diagnosis(
+    diagnosis_codes,
+    demographics,
+    prefix_override='DI_'  # DI_ = ESRD Dialysis
+)
+
+print(f"Risk Score with override: {result.risk_score}")
+```
+
+#### Other Common Scenarios
+
+```python
+# Long-term institutionalized patient not properly flagged
+processor = HCCInFHIR(model_name="CMS-HCC Model V28")
+demographics = Demographics(age=78, sex="M")
+diagnosis_codes = ["F03.90", "I48.91", "N18.4"]
+
+result = processor.calculate_from_diagnosis(
+    diagnosis_codes,
+    demographics,
+    prefix_override='INS_'  # INS_ = Institutionalized
+)
+
+# New enrollee with missing flag
+result = processor.calculate_from_diagnosis(
+    diagnosis_codes,
+    demographics,
+    prefix_override='NE_'  # NE_ = New Enrollee
+)
+```
+
+#### Common Prefix Values
+
+**CMS-HCC Models (V22, V24, V28):**
+- `CNA_` - Community, Non-Dual, Aged (65+)
+- `CND_` - Community, Non-Dual, Disabled (<65)
+- `CFA_` - Community, Full Benefit Dual, Aged
+- `CFD_` - Community, Full Benefit Dual, Disabled
+- `CPA_` - Community, Partial Benefit Dual, Aged
+- `CPD_` - Community, Partial Benefit Dual, Disabled
+- `INS_` - Long-Term Institutionalized
+- `NE_` - New Enrollee
+- `SNPNE_` - Special Needs Plan New Enrollee
+
+**ESRD Models (V21, V24):**
+- `DI_` - Dialysis (standard)
+- `DNE_` - Dialysis New Enrollee
+- `GI_` - Graft, Institutionalized
+- `GNE_` - Graft, New Enrollee
+- `GFPA_`, `GFPN_`, `GNPA_`, `GNPN_` - Graft with various dual/age combinations
+
+**RxHCC Model (V08):**
+- `Rx_CE_LowAged_` - Community, Low Income, Aged
+- `Rx_CE_NoLowAged_` - Community, Not Low Income, Aged
+- `Rx_NE_Lo_` - New Enrollee, Low Income
+- `Rx_CE_LTI_` - Community, Long-Term Institutionalized
+
+See [CLAUDE.md](./CLAUDE.md#coefficient-prefix-reference) for complete prefix reference.
+
 ### Custom Filtering Rules
 
 ```python
@@ -530,7 +613,7 @@ from hccinfhir.filter import apply_filter
 filtered_data = apply_filter(
     service_data,
     include_inpatient=True,
-    include_outpatient=True, 
+    include_outpatient=True,
     eligible_cpt_hcpcs_file="custom_procedures.csv"
 )
 ```
@@ -565,17 +648,105 @@ except ModelNotFoundError as e:
     print(f"Model configuration error: {e}")
 ```
 
-## 🧪 Testing
+### Custom Valuesets
 
-```bash
-# Install development dependencies
-pip install -e ".[dev]"
+Users can generate custom and more specific valuesets using the mimilabs data lakehouse.
+
+For example, the valuesets in the package are created as follows:
+
+`ra_dx_to_cc_mapping_2026.csv`
+```sql
+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;
+```
 
-# Run tests
-pytest tests/
+`ra_hierarchies_2026.csv`
+```sql
+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_2026.csv`
+```sql
+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_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) = 2025;
+```
 
-# Run with coverage
-pytest --cov=hccinfhir tests/
+`hcc_is_chronic.csv`
+```sql
+SELECT hcc, is_chronic, model_version, model_domain
+FROM cmspayment.ra_report_to_congress
+WHERE mimi_src_file_name = '2024riskadjustmentinma-rtc.pdf'
+```
+
+## 🧪 Testing
+
+```bash
+$ hatch shell
+$ pip install -e .
+$ pytest tests/*
 ```
 
 ## 📄 License

{hccinfhir-0.1.4 → hccinfhir-0.1.6}/hccinfhir/__init__.py

@@ -21,7 +21,7 @@ from .samples import (
     list_available_samples
 )
 
-__version__ = "0.1.2"
+__version__ = "0.1.5"
 __author__ = "Yubin Park"
 __email__ = "yubin.park@mimilabs.ai"