hccinfhir 0.1.2__tar.gz → 0.1.3__tar.gz

{hccinfhir-0.1.2 → hccinfhir-0.1.3}/PKG-INFO

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

{hccinfhir-0.1.2 → hccinfhir-0.1.3}/hccinfhir/extractor.py

@@ -36,11 +36,11 @@ def extract_sld(
         raise ValueError(f'Format must be either "837" or "fhir", got {format}')
 
 
-def extract_sld_list(data: Union[List[str], List[dict]], format: Literal["837", "fhir"] = "fhir") -> List[ServiceLevelData]:
+def extract_sld_list(data: Union[List[str], List[dict]], 
+                     format: Literal["837", "fhir"] = "fhir") -> List[ServiceLevelData]:
     """Extract SLDs from a list of FHIR EOBs"""
     output = []
     for item in data:
-
         try:
             output.extend(extract_sld(item, format))
         except TypeError as e:

{hccinfhir-0.1.2 → hccinfhir-0.1.3}/hccinfhir/extractor_837.py

@@ -38,9 +38,11 @@ def parse_amount(amount_str: str) -> Optional[float]:
     except (ValueError, TypeError):
         return None
 
-def get_segment_value(segment: List[str], index: int) -> Optional[str]:
+def get_segment_value(segment: List[str], 
+                      index: int, 
+                      default: Optional[str] = None) -> Optional[str]:
     """Safely get value from segment at given index"""
-    return segment[index] if len(segment) > index else None
+    return segment[index] if len(segment) > index else default
 
 def parse_diagnosis_codes(segment: List[str]) -> Dict[str, str]:
     """Extract diagnosis codes from HI segment"""
@@ -49,7 +51,11 @@ def parse_diagnosis_codes(segment: List[str]) -> Dict[str, str]:
         if ':' not in element:
             continue
         qualifier, code = element.split(':')[:2]
-        if qualifier in ['ABK', 'ABF']:  # ICD-10 qualifiers
+        if qualifier in {'ABK', 'ABF', 'ABJ'}:  # ICD-10 qualifiers
+            # ABK: Primary Diagnosis
+            # ABF: Secondary Diagnosis
+            # ABJ: Admitting Diagnosis
+            # NOTE: In Risk Adjustment, we do not differentiate between primary and secondary diagnoses
             dx_lookup[str(pos)] = code
     return dx_lookup
 
@@ -61,17 +67,35 @@ def process_service_line(segments: List[List[str]], start_index: int) -> tuple[O
     for seg in segments[start_index:]:
         if seg[0] in ['LX', 'CLM', 'SE']:
             break
-        if seg[0] == 'LIN' and len(seg) > 3 and seg[2] == 'N4':
-            ndc = seg[3]
-        elif seg[0] == 'DTP' and seg[1] == '472':
-            service_date = parse_date(seg[3])
+        if len(seg) > 3:
+            if seg[0] == 'LIN' and seg[2] == 'N4':
+                ndc = seg[3]
+            elif (seg[0] == 'DTP' and 
+                  seg[1] in {'472', '434'} and
+                  seg[2].endswith('D8')):
+                # 472: Service Date
+                # 434: From Date in 837I
+                # These are not included currently: 435: To Date in 837I, 096 Discharge Date            
+                if seg[3]:
+                    service_date = parse_date(seg[3][:8] if len(seg[3]) >= 8 else seg[3])
         if ndc and service_date:
             break
             
     return ndc, service_date
 
 def extract_sld_837(content: str) -> List[ServiceLevelData]:
-    """Extract service level data from 837 Professional or Institutional claims"""
+    """Extract service level data from 837 Professional or Institutional claims
+
+    Structure:
+    Billing Provider (2000A)
+    └── Subscriber (2000B)
+        └── Patient (2000C) [if needed]
+            └── Claim (2300)
+                ├── Service Line 1 (2400)
+                ├── Service Line 2 (2400)
+                └── Service Line N (2400)
+    
+    """
     if not content:
         raise ValueError("Input X12 data cannot be empty")
     
@@ -100,7 +124,7 @@ def extract_sld_837(content: str) -> List[ServiceLevelData]:
         seg_id = segment[0]
         
         # Process NM1 segments (Provider and Patient info)
-        if seg_id == 'NM1':
+        if seg_id == 'NM1' and len(segment) > 1:
             if segment[1] == 'IL':  # Subscriber/Patient
                 current_data.patient_id = get_segment_value(segment, 9)
                 in_claim_loop = False
@@ -112,7 +136,7 @@ def extract_sld_837(content: str) -> List[ServiceLevelData]:
                 current_data.billing_provider_npi = get_segment_value(segment, 9)
                 
         # Process Provider Specialty
-        elif seg_id == 'PRV' and segment[1] == 'PE' and in_rendering_provider_loop:
+        elif seg_id == 'PRV' and len(segment) > 1 and segment[1] == 'PE' and in_rendering_provider_loop:
             current_data.provider_specialty = get_segment_value(segment, 3)
             
         # Process Claim Information
@@ -122,29 +146,72 @@ def extract_sld_837(content: str) -> List[ServiceLevelData]:
             current_data.claim_id = segment[1] if len(segment) > 1 else None
             
             # Parse facility and service type for institutional claims
-            if claim_type == "837I" and len(segment) > 5 and ':' in segment[5]:
-                current_data.facility_type = segment[5][0]
+            if claim_type == "837I" and len(segment) > 5 and segment[5] and ':' in segment[5]:
+                current_data.facility_type = segment[5][0] if segment[5] else None
                 current_data.service_type = segment[5][1] if len(segment[5]) > 1 else None
 
         # Process Diagnosis Codes
         elif seg_id == 'HI' and in_claim_loop:
-            current_data.dx_lookup = parse_diagnosis_codes(segment)
+            # In 837I, there can be multiple HI segments in the claim
+            # Also, in 837I, diagnosis position does not matter
+            # We will use continuous numbering for diagnosis codes
+            # use the last dx_lookup position as the starting position, and update
+            hi_segment = parse_diagnosis_codes(segment)
+            hi_segment_realigned = {
+                str(int(pos) + len(current_data.dx_lookup)): code
+                for pos, code in hi_segment.items()
+            }
+            current_data.dx_lookup.update(hi_segment_realigned)
             
         # Process Service Lines
+        # 
+        # SV1 (Professional Services):
+        #   SV101 (Required) - Procedure Code Composite: HC qualifier + 5-digit HCPCS code, supports up to 4 HCPCS modifiers
+        #   SV102 (Required) - Charge Amount: Format 99999999.99
+        #   SV103 (Required) - Unit Type: F2 (International Unit) or UN (Units)
+        #   SV104 (Required) - Unit Count: Format 9999.99 (decimals allowed)
+        #   SV105 (Situational) - Place of Service Code: Required for First Steps claims
+        #   SV107 (Situational) - Diagnosis Code Pointer: Links to HI segment in 2300 loop, valid values 1-8
+        #
+        # SV2 (Institutional Services):
+        #   SV201 (Required) - Revenue Code: Facility-specific revenue code for service rendered
+        #   SV202 (Required) - Procedure Code Composite: HC qualifier + 5-digit HCPCS code, supports up to 4 HCPCS modifiers
+        #   SV203 (Required) - Charge Amount: Format 99999999.99
+        #   SV204 (Required) - Unit Type: DA (Days) or UN (Units)
+        #   SV205 (Required) - Unit Count: Format 9999999.999 (whole numbers only - fractional quantities not recognized)
+        #   NOTE: Diagnosis Code Pointer is not supported for SV2
+        #
         elif seg_id in ['SV1', 'SV2'] and in_claim_loop:
-            # Parse procedure info
-            proc_info = segment[1].split(':')
-            procedure_code = proc_info[1] if len(proc_info) > 1 else None
-            modifiers = proc_info[2:] if len(proc_info) > 2 else []
             
-            # Get diagnosis pointers and linked diagnoses
-            dx_pointer_pos = 7 if seg_id == 'SV1' else 11
-            dx_pointers = get_segment_value(segment, dx_pointer_pos)
-            linked_diagnoses = [
-                current_data.dx_lookup[pointer]
-                for pointer in (dx_pointers.split(',') if dx_pointers else [])
-                if pointer in current_data.dx_lookup
-            ]
+            linked_diagnoses = []
+            
+            if seg_id == 'SV1':
+                # SV1 Professional Service: SV101=procedure, SV104=quantity, SV106=place_of_service
+                proc_info = get_segment_value(segment, 1, '').split(':')
+                procedure_code = proc_info[1] if len(proc_info) > 1 else None
+                modifiers = proc_info[2:] if len(proc_info) > 2 else []
+                quantity = parse_amount(get_segment_value(segment, 4))
+                place_of_service = get_segment_value(segment, 5)
+                # Get diagnosis pointers and linked diagnoses
+                dx_pointers = get_segment_value(segment, 7, '')
+                linked_diagnoses = [
+                    current_data.dx_lookup[pointer]
+                    for pointer in (dx_pointers.split(':') if dx_pointers else [])
+                    if pointer in current_data.dx_lookup
+                ]
+            else:
+                # SV2 Institutional Service: SV201=revenue, SV202=procedure, SV205=quantity
+                # Revenue code in SV201
+                revenue_code = get_segment_value(segment, 1)
+                # Procedure code in SV202
+                proc_info = get_segment_value(segment, 2, '').split(':')
+                procedure_code = proc_info[1] if len(proc_info) > 1 else None
+                modifiers = proc_info[2:] if len(proc_info) > 2 else []
+                # Quantity in SV205
+                quantity = parse_amount(get_segment_value(segment, 5))
+                place_of_service = None  # Not applicable for institutional
+                # linked diagnoses are not supported for SV2
+                
             
             # Get service line details
             ndc, service_date = process_service_line(segments, i)
@@ -154,7 +221,7 @@ def extract_sld_837(content: str) -> List[ServiceLevelData]:
                 claim_id=current_data.claim_id,
                 procedure_code=procedure_code,
                 linked_diagnosis_codes=linked_diagnoses,
-                claim_diagnosis_codes=list(current_data.dx_lookup.values()),
+                claim_diagnosis_codes=list(current_data.dx_lookup.values()), # this is used for risk adjustment
                 claim_type=current_data.claim_type,
                 provider_specialty=current_data.provider_specialty,
                 performing_provider_npi=current_data.performing_provider_npi,
@@ -163,8 +230,8 @@ def extract_sld_837(content: str) -> List[ServiceLevelData]:
                 facility_type=current_data.facility_type,
                 service_type=current_data.service_type,
                 service_date=service_date,
-                place_of_service=get_segment_value(segment, 6) if seg_id == 'SV1' else None,
-                quantity=parse_amount(get_segment_value(segment, 4)),
+                place_of_service=place_of_service,
+                quantity=quantity,
                 modifiers=modifiers,
                 ndc=ndc,
                 allowed_amount=None

{hccinfhir-0.1.2 → hccinfhir-0.1.3}/hccinfhir/filter.py

@@ -9,13 +9,13 @@ professional_cpt_default = load_proc_filtering(professional_cpt_default_fn)
 def apply_filter(
     data: List[ServiceLevelData], 
     inpatient_tob: Set[str] = {'11X', '41X'},
-    outpatient_tob: Set[str] = {'12X', '13X', '43X', '71X', '73X', '76X', '77X', '85X'},
+    outpatient_tob: Set[str] = {'12X', '13X', '43X', '71X', '73X', '76X', '77X', '85X', '87X'},
     professional_cpt: Set[str] = professional_cpt_default
 ) -> List[ServiceLevelData]:
     # tob (Type of Bill) Filter is based on:
     # https://www.hhs.gov/guidance/sites/default/files/hhs-guidance-documents/2012181486-wq-092916_ra_webinar_slides_5cr_092816.pdf
     # https://www.hhs.gov/guidance/sites/default/files/hhs-guidance-documents/FinalEncounterDataDiagnosisFilteringLogic.pdf
-
+    # https://www.cms.gov/files/document/encounterdatasystemedit20495andedit01415andtob87x07162021.pdf for 87X
     # NOTE: If no facility_type or service_type, then the claim is professional, in our implementation.
     # NOTE: The original CMS logic is for the "record" level, not the service level.
     #  Thus, when preparing the service level data, put all diagnosis codes into the diagnosis field.

{hccinfhir-0.1.2 → hccinfhir-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hccinfhir"
-version = "0.1.2"
+version = "0.1.3"
 authors = [
   { name="Yubin Park", email="yubin.park@mimilabs.ai" },
 ]