hccinfhir 0.0.1__py3-none-any.whl → 0.0.3__py3-none-any.whl

hccinfhir-0.0.3.dist-info/METADATA

@@ -0,0 +1,179 @@
+Metadata-Version: 2.3
+Name: hccinfhir
+Version: 0.0.3
+Summary: HCC Algorithm for FHIR Resources
+Project-URL: Homepage, https://github.com/mimilabs/hccinfhir
+Project-URL: Issues, https://github.com/mimilabs/hccinfhir/issues
+Author-email: Yubin Park <yubin.park@mimilabs.ai>
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Requires-Dist: pydantic>=2.10.3
+Description-Content-Type: text/markdown
+
+# `hccinfhir` (HCC in FHIR)
+A Python library for extracting standardized service-level data from FHIR ExplanationOfBenefit resources, with a focus on supporting HCC (Hierarchical Condition Category) risk adjustment calculations.
+
+## Features
+- Extract diagnosis codes, procedures, providers, and other key data elements from FHIR EOBs
+- 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
+
+## Installation
+```bash
+pip install hccinfhir
+```
+
+## Why FHIR-Based HCC Processing?
+Risk Adjustment calculations traditionally rely on processed claims data, leading to information loss and reconciliation challenges. `hccinfhir` processes FHIR resources directly because:
+- FHIR represents the source of truth with complete clinical and administrative data
+- Risk Adjustment requires multiple data elements beyond diagnosis codes
+- Direct processing eliminates data transformation errors and simplifies reconciliation
+
+## Data Model & Flexibility
+While built for native FHIR processing, `hccinfhir` works with any data source that can be transformed into the SLD (Service Level Data) format:
+
+```python
+sld = [{
+    "procedure_code": "99214",
+    "diagnosis_codes": ["E11.9", "I10"],
+    "claim_type": "71",
+    "provider_specialty": "01", 
+    "service_date": "2024-01-15"
+}, ...]
+```
+
+For more details on the SLD format, see the `models.py` file.
+
+## Core Components
+
+### 1. Extractor Module
+Processes FHIR ExplanationOfBenefit resources to extract Minimum Data Elements (MDE):
+```python
+from hccinfhir.extractor import extract_sld, extract_sld_list
+
+sld = extract_sld(eob_data)  # Process single EOB
+
+sld_list = extract_sld_list([eob1, eob2])  # Process multiple EOBs
+```
+
+### 2. Filter Module
+Implements claim filtering rules:
+- Inpatient/outpatient criteria - Type of Bill + Eligible CPT/HCPCS
+- Professional service requirements - Eligible CPT/HCPCS
+- Provider validation (Not in scope for this release, applicable to RAPS)
+```python
+from hccinfhir.filter import apply_filter
+
+filtered_sld = apply_filter(sld_list)
+```
+
+
+### 3. Logic Module (In Development)
+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
+
+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
+```
+
+## Testing
+```bash
+$ python3 -m hatch shell
+$ python3 -m pip install -e .
+$ python3 -m pytest tests/*
+``` 
+
+## Dependencies
+- Pydantic >= 2.10.3
+- Standard Python libraries
+
+## Research: FHIR BCDA and 837 Field Mapping Analysis
+
+### Core Identifiers
+| Field | 837 Source | FHIR BCDA Source | Alignment Analysis |
+|-------|------------|------------------|-------------------|
+| claim_id | CLM01 segment | eob.id | ✓ Direct mapping |
+| patient_id | NM109 when NM101='IL' | eob.patient.reference (last part after '/') | ✓ Aligned but different formats |
+
+### Provider Information
+| Field | 837 Source | FHIR BCDA Source | Alignment Analysis |
+|-------|------------|-------------------|-------------------|
+| performing_provider_npi | NM109 when NM101='82' and NM108='XX' | careTeam member with role 'performing'/'rendering' | ✓ Aligned |
+| billing_provider_npi | NM109 when NM101='85' and NM108='XX' | contained resources with NPI system identifier | ✓ Conceptually aligned |
+| provider_specialty | PRV03 when PRV01='PE' | careTeam member qualification with specialty system | ✓ Aligned but different code systems |
+
+### Claim Type Information
+| Field | 837 Source | FHIR BCDA Source | Alignment Analysis |
+|-------|------------|-------------------|-------------------|
+| claim_type | GS08 (mapped via CLAIM_TYPES) | eob.type with claim_type system | ✓ Aligned but different coding |
+| facility_type | CLM05-1 (837I only) | facility.extension with facility_type system | ✓ Aligned for institutional claims |
+| service_type | CLM05-2 (837I only) | extension or eob.type with service_type system | ✓ Aligned for institutional claims |
+
+### Service Line Information
+| Field | 837 Source | FHIR BCDA Source | Alignment Analysis |
+|-------|------------|-------------------|-------------------|
+| procedure_code | SV1/SV2 segment, element 2 | item.productOrService with pr system | ✓ Aligned |
+| ndc | LIN segment after service line | item.productOrService with ndc system or extension | ✓ Aligned but different locations |
+| quantity | SV1/SV2 element 4 | item.quantity.value | ✓ Direct mapping |
+| quantity_unit | SV1/SV2 element 5 | item.quantity.unit | ✓ Direct mapping |
+| service_date | DTP segment with qualifier 472 | item.servicedPeriod or eob.billablePeriod | ✓ Aligned |
+| place_of_service | SV1 element 6 | item.locationCodeableConcept with place_of_service system | ✓ Aligned |
+| modifiers | SV1/SV2 segment, additional qualifiers | item.modifier with pr system | ✓ Aligned |
+
+### Diagnosis Information
+| Field | 837 Source | FHIR BCDA Source | Alignment Analysis |
+|-------|------------|-------------------|-------------------|
+| linked_diagnosis_codes | SV1/SV2 diagnosis pointers + HI segment codes | item.diagnosisSequence + diagnosis lookup | ✓ Aligned but different structure |
+| claim_diagnosis_codes | HI segment codes | diagnosis array with icd10cm/icd10 systems | ✓ Aligned |
+
+### Additional Fields
+| Field | 837 Source | FHIR BCDA Source | Alignment Analysis |
+|-------|------------|-------------------|-------------------|
+| allowed_amount | Not available in 837 | item.adjudication with 'eligible' category | ⚠️ Only in FHIR |
+
+### Key Differences and Notes
+
+1. **Structural Differences**:
+   - 837 uses a segment-based approach with positional elements
+   - FHIR uses a nested object structure with explicit systems and codes
+
+2. **Code Systems**:
+   - FHIR explicitly defines systems for each code (via SYSTEMS constant)
+   - 837 uses implicit coding based on segment position and qualifiers
+
+3. **Data Validation**:
+   - FHIR implementation uses Pydantic models for validation
+   - 837 implements manual validation and parsing
+
+4. **Diagnosis Handling**:
+   - 837: Direct parsing from HI segment with position-based lookup
+   - FHIR: Uses sequence numbers and separate diagnosis array
+
+5. **Provider Information**:
+   - 837: Direct from NM1 segments with role qualifiers
+   - FHIR: Through careTeam structure with role coding
+
+### TODO: Enhancement Suggestions
+
+1. Consider adding validation for code systems in 837 parser to match FHIR's explicitness
+2. Standardize date handling between both implementations
+3. Add support for allowed_amount in 837 if available in different segments
+4. Consider adding more robust error handling in both implementations
+
+## Contributing
+Join us at [mimilabs](https://mimilabs.ai/signup). Reference data available in MIMILabs data lakehouse.
+
+## License
+Apache License 2.0

hccinfhir-0.0.3.dist-info/RECORD

@@ -0,0 +1,28 @@
+hccinfhir/__init__.py,sha256=OCyYCv4jTOlYHZbTw2DTks3e6_YT1N2JXAOuyR03KNE,43
+hccinfhir/extractor.py,sha256=IHKxHEsuU5JIPnScv8x9v_L28aG5F6edZZ0VeYpBF6Y,1770
+hccinfhir/extractor_837.py,sha256=84OeYB1nXl329osWagkkuX0q4MVATnHGk7VZa9p6zoI,7160
+hccinfhir/extractor_fhir.py,sha256=Yu6Ce-2iKvn0j21t_EJUeXjwjZYbTh5HgqChMz8KkjI,8445
+hccinfhir/filter.py,sha256=C05uFhqSVb0J7BpKPGt4hwQrCd0_HbGSmrxKHIZLg4w,2259
+hccinfhir/models.py,sha256=dH0qICn8yjsqc35INYSG4HbvYyegRCPtQOPTJf5Qozw,2033
+hccinfhir/data/__init__.py,sha256=SGiSkpGrnxbvtEFMMlk82NFHOE50hFXcgKwKUSuVZUg,45
+hccinfhir/data/ra_eligible_cpt_hcpcs_2023.csv,sha256=VVoA4s0hsFmcRIugyFdbvSoeLcn7M7z0DITT6l4YqL8,39885
+hccinfhir/data/sample_837_0.txt,sha256=eggrD259uHa05z2dfxWBpUDseSDp_AQcLyN_adpHyTw,5295
+hccinfhir/data/sample_837_1.txt,sha256=E155MdemSDYoXokuTXUZ6Br_RGGedYv5t5dh-eMRmuk,1322
+hccinfhir/data/sample_837_10.txt,sha256=zSJXI78vHAksA7FFQEVLvepefdpMM2_AexLyoDimV3Q,1129
+hccinfhir/data/sample_837_11.txt,sha256=suVxlZEllEOy6dYgbzGIphKW6hDAKdYQTZFM3Ob84q4,817
+hccinfhir/data/sample_837_2.txt,sha256=2bvXzaiopr7pO3D3pL7nLxcpgqKXrhu3lbulveJDJ-I,1125
+hccinfhir/data/sample_837_3.txt,sha256=_B1Ktpsg7bOnA5BwZ7AUB0o7MME5AmLGuxzHq42FWok,1113
+hccinfhir/data/sample_837_4.txt,sha256=jpzyiHKmRGMqN1ij9s1X4zRj0a2PXwtee4mjn4BRF3g,1077
+hccinfhir/data/sample_837_5.txt,sha256=eYG4URk3zAr5UsnBKO5Wezo8dnL_HXGCMmXWJu0nxPA,1300
+hccinfhir/data/sample_837_6.txt,sha256=pnKQf2cVcZpUl8PGeYzZxRxjKOMcISN2dBObIMtLx7E,1331
+hccinfhir/data/sample_837_7.txt,sha256=5Y-x7ZA9d_qGaIrpVGfXKQBXqbxKiQ5CWOwEW1XGlds,1253
+hccinfhir/data/sample_837_8.txt,sha256=J-zm0fzp6F19r2SWfHcCtab9ezd3c4YaSRO-RatJ-c4,1250
+hccinfhir/data/sample_837_9.txt,sha256=nIIurZ0tLHw6ZfDM__U-WqV8Q0u4K3WP56-r3BnAEv8,1341
+hccinfhir/data/sample_eob_1.json,sha256=_NGSVR2ysFpx-DcTvyga6dFCzhQ8Vi9fNzQEMPz5awU,3124
+hccinfhir/data/sample_eob_2.json,sha256=FcnJcx0ApOczxjJ_uxVLzCep9THfNf4xs9Yf7hxk8e4,1769
+hccinfhir/data/sample_eob_200.ndjson,sha256=CxpjeQ1DCMUzZILaM68UEhfxO0p45YGhDDoCZeq8PxU,1917986
+hccinfhir/data/sample_eob_3.json,sha256=4BW4wOMBEEU9RDfJR15rBEvk0KNHyuMEh3e055y87Hc,2306
+hccinfhir-0.0.3.dist-info/METADATA,sha256=Ekro5D_Wg4htDTmM1NDJOE03Z9BSggoQEdHKSsv1DY8,7654
+hccinfhir-0.0.3.dist-info/WHEEL,sha256=C2FUgwZgiLbznR-k0b_5k3Ai_1aASOXDss3lzCUsUug,87
+hccinfhir-0.0.3.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+hccinfhir-0.0.3.dist-info/RECORD,,

hccinfhir-0.0.1.dist-info/METADATA

@@ -1,89 +0,0 @@
-Metadata-Version: 2.3
-Name: hccinfhir
-Version: 0.0.1
-Summary: HCC Algorithm for FHIR Resources
-Project-URL: Homepage, https://github.com/mimilabs/hccinfhir
-Project-URL: Issues, https://github.com/mimilabs/hccinfhir/issues
-Author-email: Yubin Park <yubin.park@mimilabs.ai>
-Classifier: License :: OSI Approved :: Apache Software License
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Requires-Python: >=3.8
-Requires-Dist: pydantic>=2.10.3
-Description-Content-Type: text/markdown
-
-# `hccinfhir` (HCC in FHIR)
-HCC (Hierarchical Condition Category) Algorithm Implementation for FHIR Resources
-
-## Overview
-`hccinfhir` implements the CMS-HCC Risk Adjustment model using FHIR (Fast Healthcare Interoperability Resources) data. It processes Blue Button 2.0 API (BCDA) data to calculate Hierarchical Condition Category (HCC) Risk Adjustment Factors (RAF).
-
-## Why FHIR-Based HCC Processing?
-Risk Adjustment calculations traditionally rely on processed claims data, leading to information loss and reconciliation challenges. `hccinfhir` processes FHIR resources directly because:
-- FHIR represents the source of truth with complete clinical and administrative data
-- Risk Adjustment requires multiple data elements beyond diagnosis codes
-- Direct processing eliminates data transformation errors and simplifies reconciliation
-
-## Data Flexibility
-While built for native FHIR processing, `hccinfhir` works with any data source that can be transformed into the MDE format:
-
-```python
-mde = [{
-    "procedure_code": "99214",
-    "diagnosis_codes": ["E11.9", "I10"],
-    "claim_type": "71",
-    "provider_specialty": "01", 
-    "service_date": "2024-01-15"
-}, ...]
-```
-
-## Components
-
-### 1. Extractor Module
-Processes FHIR ExplanationOfBenefit resources to extract Minimum Data Elements (MDE):
-```python
-from hccinfhir.extractor import extract_mde, extract_mde_list
-
-mde = extract_mde(eob_data)  # Process single EOB
-
-mde_list = extract_mde_list([eob1, eob2])  # Process multiple EOBs
-```
-
-### 2. Logic Module (In Development)
-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
-
-### 3. Filter Module (In Development)
-Implements claim filtering rules:
-- Inpatient/outpatient criteria
-- Professional service requirements
-- Provider validation
-- Date range filtering
-
-## Installation
-```bash
-pip install hccinfhir
-```
-
-## Usage
-```python
-from hccinfhir import HCCInFHIR
-
-hcc_processor = HCCInFHIR()
-mde_list = hcc_processor.extract_mde_list(eob_list)
-filtered_mde = hcc_processor.apply_filters(mde_list)  # future
-raf_details = hcc_processor.calculate_raf(filtered_mde, demographic_data)  # future
-```
-
-## Dependencies
-- Pydantic >= 2.10.3
-- Standard Python libraries
-
-## Contributing
-Join us at [mimilabs](https://mimilabs.ai/signup). Reference data available in MIMILabs data lakehouse.
-
-## License
-Apache License 2.0

hccinfhir-0.0.1.dist-info/RECORD

@@ -1,10 +0,0 @@
-hccinfhir/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-hccinfhir/extractor.py,sha256=XRoWxmXAvqqmXkNjmr-yWmkKhKuFcVO5W3RyV9oCEQc,4288
-hccinfhir/data/__init__.py,sha256=daEdpEyAJIa8b2VkCqSKcw8PaExcB6Qro80XNes_sHA,2
-hccinfhir/data/sample_eob_1.json,sha256=_NGSVR2ysFpx-DcTvyga6dFCzhQ8Vi9fNzQEMPz5awU,3124
-hccinfhir/data/sample_eob_2.json,sha256=FcnJcx0ApOczxjJ_uxVLzCep9THfNf4xs9Yf7hxk8e4,1769
-hccinfhir/data/sample_eob_3.json,sha256=4BW4wOMBEEU9RDfJR15rBEvk0KNHyuMEh3e055y87Hc,2306
-hccinfhir-0.0.1.dist-info/METADATA,sha256=nFVxOtMDW1xRb_Ff_58Pc3x6FQkucve7yCGLpG7TKgI,2998
-hccinfhir-0.0.1.dist-info/WHEEL,sha256=C2FUgwZgiLbznR-k0b_5k3Ai_1aASOXDss3lzCUsUug,87
-hccinfhir-0.0.1.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-hccinfhir-0.0.1.dist-info/RECORD,,