hccinfhir 0.1.4__py3-none-any.whl → 0.1.6__py3-none-any.whl

hccinfhir/model_interactions.py

@@ -8,8 +8,10 @@ def has_any_hcc(hcc_list: list[str], hcc_set: set[str]) -> int:
 def create_demographic_interactions(demographics: Demographics) -> dict:
     """Creates common demographic-based interactions"""
     interactions = {}
-    is_female = demographics.category.startswith('F')
-    is_male = demographics.category.startswith('M')
+    # Determine sex from demographics.sex instead of category
+    # Category can start with 'NEM'/'NEF' for new enrollees, not just 'M'/'F'
+    is_female = demographics.sex in ('F', '2')
+    is_male = demographics.sex in ('M', '1')
     is_aged = not demographics.non_aged
     
     # Original Disability interactions
@@ -33,21 +35,32 @@ def create_demographic_interactions(demographics: Demographics) -> dict:
         nemcaid = True
     ne_origds = int(demographics.age >= 65 and (demographics.orec is not None and demographics.orec == "1"))
     
+    fbd = demographics.fbd
+
     # Four mutually exclusive groups
     interactions.update({
         f'NMCAID_NORIGDIS_{demographics.category}': int(not nemcaid and not ne_origds),
         f'MCAID_NORIGDIS_{demographics.category}': int(nemcaid and not ne_origds),
         f'NMCAID_ORIGDIS_{demographics.category}': int(not nemcaid and ne_origds),
-        f'MCAID_ORIGDIS_{demographics.category}': int(nemcaid and ne_origds)
+        f'MCAID_ORIGDIS_{demographics.category}': int(nemcaid and ne_origds),
+        f'FBD_NORIGDIS_{demographics.category}': int(fbd and not ne_origds),
+        f'FBD_ORIGDIS_{demographics.category}': int(fbd and ne_origds),
+        f'ND_PBD_NORIGDIS_{demographics.category}': int(not fbd and not ne_origds),
+        f'ND_PBD_ORIGDIS_{demographics.category}': int(not fbd and ne_origds)
     })
 
+    # output only non-zero interactions
+    interactions = {k: v for k, v in interactions.items() if v > 0}
+
     return interactions
 
 def create_dual_interactions(demographics: Demographics) -> dict:
     """Creates dual status interactions"""
     interactions = {}
-    is_female = demographics.category.startswith('F')
-    is_male = demographics.category.startswith('M')
+    # Determine sex from demographics.sex instead of category
+    # Category can start with 'NEM'/'NEF' for new enrollees, not just 'M'/'F'
+    is_female = demographics.sex in ('F', '2')
+    is_male = demographics.sex in ('M', '1')
     is_aged = not demographics.non_aged
     
     if demographics.fbd:
@@ -77,12 +90,17 @@ def create_hcc_counts(hcc_set: set[str]) -> dict:
         counts[f'D{i}'] = int(hcc_count == i)
     counts['D10P'] = int(hcc_count >= 10)
     
+    # output only non-zero counts
+    counts = {k: v for k, v in counts.items() if v > 0}
+
     return counts
 
 def get_diagnostic_categories(model_name: ModelName, hcc_set: set[str]) -> dict:
     """Creates disease categories based on model version"""
+    categories = {}
+    
     if model_name == "CMS-HCC Model V28":
-        return {
+        categories = {
             'CANCER_V28': has_any_hcc(['17', '18', '19', '20', '21', '22', '23'], hcc_set),
             'DIABETES_V28': has_any_hcc(['35', '36', '37', '38'], hcc_set),
             'CARD_RESP_FAIL_V28': has_any_hcc(['211', '212', '213'], hcc_set),
@@ -96,7 +114,7 @@ def get_diagnostic_categories(model_name: ModelName, hcc_set: set[str]) -> dict:
             'ULCER_V28': has_any_hcc(['379', '380', '381', '382'], hcc_set)
         }
     elif model_name == "CMS-HCC Model V24":
-        return {
+        categories = {
             'CANCER': has_any_hcc(['8', '9', '10', '11', '12'], hcc_set),
             'DIABETES': has_any_hcc(['17', '18', '19'], hcc_set),
             'CARD_RESP_FAIL': has_any_hcc(['82', '83', '84'], hcc_set),
@@ -109,7 +127,7 @@ def get_diagnostic_categories(model_name: ModelName, hcc_set: set[str]) -> dict:
             'PRESSURE_ULCER': has_any_hcc(['157', '158', '159'],  hcc_set) # added in 2018-11-20
         }
     elif model_name == "CMS-HCC Model V22":
-        return {
+        categories = {
             'CANCER': has_any_hcc(['8', '9', '10', '11', '12'], hcc_set),
             'DIABETES': has_any_hcc(['17', '18', '19'], hcc_set),
             'CARD_RESP_FAIL': has_any_hcc(['82', '83', '84'], hcc_set),
@@ -122,7 +140,7 @@ def get_diagnostic_categories(model_name: ModelName, hcc_set: set[str]) -> dict:
             'PRESSURE_ULCER': has_any_hcc(['157', '158'],  hcc_set) # added in 2012-10-19
         }
     elif model_name == "CMS-HCC ESRD Model V24":
-        return {
+        categories = {
             'CANCER': has_any_hcc(['8', '9', '10', '11', '12'], hcc_set),
             'DIABETES': has_any_hcc(['17', '18', '19'], hcc_set),
             'CARD_RESP_FAIL': has_any_hcc(['82', '83', '84'], hcc_set),
@@ -135,7 +153,7 @@ def get_diagnostic_categories(model_name: ModelName, hcc_set: set[str]) -> dict:
             'gPsychiatric_V24': has_any_hcc(['57', '58', '59', '60'], hcc_set)
         }
     elif model_name == "CMS-HCC ESRD Model V21":
-        return {
+        categories = {
             'CANCER': has_any_hcc(['8', '9', '10', '11', '12'], hcc_set),
             'DIABETES': has_any_hcc(['17', '18', '19'], hcc_set),
             'IMMUNE': int('47' in hcc_set),
@@ -150,7 +168,9 @@ def get_diagnostic_categories(model_name: ModelName, hcc_set: set[str]) -> dict:
     elif model_name == "RxHCC Model V08":
         # RxModel doesn't seem to have any diagnostic category interactions
         return {}
-    return {}
+    
+    # keep the zero-valued categories. Will be filtered out later
+    return categories
 
 def create_disease_interactions(model_name: ModelName, 
                               diagnostic_cats: dict, 
@@ -317,6 +337,9 @@ def create_disease_interactions(model_name: ModelName,
             'NonAged_RXHCC159': demographics.non_aged * int('159' in hcc_set),
             'NonAged_RXHCC163': demographics.non_aged * int('163' in hcc_set)
         })
+
+    # output only non-zero interactions
+    interactions = {k: v for k, v in interactions.items() if v > 0}
     
     return interactions
 

{hccinfhir-0.1.4.dist-info → hccinfhir-0.1.6.dist-info}/METADATA

@@ -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.dist-info → hccinfhir-0.1.6.dist-info}/RECORD

@@ -1,20 +1,21 @@
-hccinfhir/__init__.py,sha256=nO2iJmzXCpLuY3FB8YVZP3KENGZiba7DORlnlMjPgYo,1043
-hccinfhir/datamodels.py,sha256=Vp64Blwq8qWe-q1slCK8jMO9SIErUgkXusGZ0laXiWo,5936
+hccinfhir/__init__.py,sha256=G_5m6jm3_BK5NdcZWoi0NEKJEsE_LjAU1RaLaL9xNPU,1043
+hccinfhir/datamodels.py,sha256=EHkuWMhmHBt8GfVP3lrxfSogu-qZQzeforFzp0Bn_bM,7714
 hccinfhir/extractor.py,sha256=xL9c2VT-e2I7_c8N8j4Og42UEgVuCzyn9WFp3ntM5Ro,1822
 hccinfhir/extractor_837.py,sha256=Jhxb5glRA8Yi8lbRwdltggXCvr_84nlsZEMRIgxyy4A,13169
-hccinfhir/extractor_fhir.py,sha256=Rg_L0Vg5tz_L2VJ_jvZwWz6RMlPAkHwj4LiK-OWQvrQ,8458
+hccinfhir/extractor_fhir.py,sha256=wUN3vTm1oTZ-KvfcDebnpQMxAC-7YlRKv12Wrv3p85A,8490
 hccinfhir/filter.py,sha256=j_yD2g6RBXVUV9trKkWzsQ35x3fRvfKUPvEXKUefI64,2007
-hccinfhir/hccinfhir.py,sha256=6jvLoJF1TcqTGXbDA-_l3os6-xO68SKRr2l26LjzlgM,6982
-hccinfhir/model_calculate.py,sha256=a9W5Lp3KK5ZwZcudOJcEzcuk7SuQfmJaS8eNpqDzbOc,5491
-hccinfhir/model_coefficients.py,sha256=ZsVY0S_X_BzDvcCmzCEf31v8uixbGmPAsR6nVEyCbIA,5530
-hccinfhir/model_demographics.py,sha256=7W5NLW7aAjpn25BJzqfP8iSouD9uA6epGguJJ6BPuC0,7043
+hccinfhir/hccinfhir.py,sha256=tgNWGYvsQWOlmcnP-3yH3KfXgZtQ3IdxYfGP9SNSJb0,9879
+hccinfhir/model_calculate.py,sha256=vM0b4BkLafebk7A3yFxsEONRW4GkVbUl4GxNlLz5N8Q,6742
+hccinfhir/model_coefficients.py,sha256=2Y_xCjX4__B1_xkX3pp-XTOW4KEAWo6RCVOOJ7ZZajM,5931
+hccinfhir/model_demographics.py,sha256=CR4WC8XVq-CI1nYJoVFc5-KXTw-pKoVlHkHqfnXlnj0,9121
 hccinfhir/model_dx_to_cc.py,sha256=guJny2Mb9z8YRNWCXGSIE3APbE06zwnA2NRkjAeUs60,1765
 hccinfhir/model_hierarchies.py,sha256=0kdBmF_8e_ikMHBDhlw2I7jT3DupHfUn6o5mWj7v3Yo,2910
-hccinfhir/model_interactions.py,sha256=Ev1m6d7cHpmlJ3xk6l0EHYCTIyPynbOMR9HnLPrtj_A,20344
+hccinfhir/model_interactions.py,sha256=xdsTuc3ii8U_MaPpYv0SnR4eR_w72eHKUJn1mwmZHm4,21379
 hccinfhir/samples.py,sha256=cqytZ-N08cPGqnUXJfzrEhhHW2qL7SDPYLD9-CHXZIU,8446
 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/hcc_is_chronic.csv,sha256=Bwd-RND6SdEsKP-assoBaXnjUJAuDXhSkwWlymux72Y,19701
+hccinfhir/data/hcc_is_chronic_without_esrd_model.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
@@ -43,7 +44,7 @@ hccinfhir/sample_files/sample_eob_1.json,sha256=_NGSVR2ysFpx-DcTvyga6dFCzhQ8Vi9f
 hccinfhir/sample_files/sample_eob_2.json,sha256=FcnJcx0ApOczxjJ_uxVLzCep9THfNf4xs9Yf7hxk8e4,1769
 hccinfhir/sample_files/sample_eob_200.ndjson,sha256=CxpjeQ1DCMUzZILaM68UEhfxO0p45YGhDDoCZeq8PxU,1917986
 hccinfhir/sample_files/sample_eob_3.json,sha256=4BW4wOMBEEU9RDfJR15rBEvk0KNHyuMEh3e055y87Hc,2306
-hccinfhir-0.1.4.dist-info/METADATA,sha256=zi36h0T3rmj2fpWG_GTr2DpvuV1z7WltvR5euUQrclQ,19876
-hccinfhir-0.1.4.dist-info/WHEEL,sha256=C2FUgwZgiLbznR-k0b_5k3Ai_1aASOXDss3lzCUsUug,87
-hccinfhir-0.1.4.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-hccinfhir-0.1.4.dist-info/RECORD,,
+hccinfhir-0.1.6.dist-info/METADATA,sha256=biMD3n0KhW7JZ7phDj40yJYxcAryIWdA6S08ffvCMak,24819
+hccinfhir-0.1.6.dist-info/WHEEL,sha256=C2FUgwZgiLbznR-k0b_5k3Ai_1aASOXDss3lzCUsUug,87
+hccinfhir-0.1.6.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+hccinfhir-0.1.6.dist-info/RECORD,,