hccinfhir 0.1.3__py3-none-any.whl → 0.1.5__py3-none-any.whl

hccinfhir/__init__.py

@@ -12,7 +12,7 @@ from .model_calculate import calculate_raf
 from .datamodels import Demographics, ServiceLevelData, RAFResult, ModelName
 
 # Sample data functions
-from .sample_utils import (
+from .samples import (
     SampleData,
     get_eob_sample,
     get_eob_sample_list,
@@ -21,7 +21,7 @@ from .sample_utils import (
     list_available_samples
 )
 
-__version__ = "0.1.2"
+__version__ = "0.1.5"
 __author__ = "Yubin Park"
 __email__ = "yubin.park@mimilabs.ai"
 

hccinfhir/datamodels.py

@@ -89,18 +89,20 @@ class Demographics(BaseModel):
     pbd: Optional[bool] = Field(False, description="[derived] True if PBD (PBD Model)")
 
 
-class RAFResult(TypedDict):
-    """Type definition for RAF calculation results"""
-    risk_score: float
-    risk_score_demographics: float
-    risk_score_chronic_only: float
-    risk_score_hcc: float
-    hcc_list: List[str]
-    cc_to_dx: Dict[str, Set[str]]
-    coefficients: Dict[str, float]
-    interactions: Dict[str, float]
-    demographics: Demographics
-    model_name: ModelName
-    version: str
-    diagnosis_codes: List[str]
-    service_level_data: Optional[List[ServiceLevelData]]
+class RAFResult(BaseModel):
+    """Risk adjustment calculation results"""
+    risk_score: float = Field(..., description="Final RAF score")
+    risk_score_demographics: float = Field(..., description="Demographics-only risk score")
+    risk_score_chronic_only: float = Field(..., description="Chronic conditions risk score") 
+    risk_score_hcc: float = Field(..., description="HCC conditions risk score")
+    hcc_list: List[str] = Field(default_factory=list, description="List of active HCC categories")
+    cc_to_dx: Dict[str, Set[str]] = Field(default_factory=dict, description="Condition categories mapped to diagnosis codes")
+    coefficients: Dict[str, float] = Field(default_factory=dict, description="Applied model coefficients")
+    interactions: Dict[str, float] = Field(default_factory=dict, description="Disease interaction coefficients")
+    demographics: Demographics = Field(..., description="Patient demographics used in calculation")
+    model_name: ModelName = Field(..., description="HCC model used for calculation")
+    version: str = Field(..., description="Library version")
+    diagnosis_codes: List[str] = Field(default_factory=list, description="Input diagnosis codes")
+    service_level_data: Optional[List[ServiceLevelData]] = Field(default=None, description="Processed service records")
+    
+    model_config = {"extra": "forbid", "validate_assignment": True}

hccinfhir/extractor_837.py

@@ -83,7 +83,58 @@ def process_service_line(segments: List[List[str]], start_index: int) -> tuple[O
             
     return ndc, service_date
 
-def extract_sld_837(content: str) -> List[ServiceLevelData]:
+def split_into_claims(segments: List[List[str]]) -> List[List[List[str]]]:
+    """Split segments into individual claims based on ST/SE boundaries.
+    
+    Each ST...SE block represents one complete claim.
+    Returns a list of claim segment lists.
+    """
+    claims = []
+    current_claim = []
+    in_transaction = False
+    st_control_number = None
+    
+    for segment in segments:
+        if len(segment) < 1:
+            continue
+            
+        seg_id = segment[0]
+        
+        if seg_id == 'ST':
+            # Start new claim transaction
+            if current_claim:  # Save previous claim if exists (shouldn't happen with valid X12)
+                claims.append(current_claim)
+            current_claim = [segment]
+            in_transaction = True
+            st_control_number = segment[2] if len(segment) > 2 else None
+            
+        elif seg_id == 'SE':
+            # End current claim transaction
+            if in_transaction:
+                current_claim.append(segment)
+                
+                # Validate control numbers match (ST02 == SE02)
+                se_control_number = segment[2] if len(segment) > 2 else None
+                if st_control_number != se_control_number:
+                    print(f"Warning: ST/SE control numbers don't match: {st_control_number} != {se_control_number}")
+                
+                claims.append(current_claim)
+                current_claim = []
+                in_transaction = False
+                st_control_number = None
+                
+        elif in_transaction:
+            # Add segment to current claim
+            current_claim.append(segment)
+    
+    # Handle case where file doesn't end with SE (malformed)
+    if current_claim:
+        print("Warning: Unclosed transaction found (missing SE)")
+        claims.append(current_claim)
+    
+    return claims
+
+def parse_837_claim_to_sld(segments: List[List[str]], claim_type: str) -> List[ServiceLevelData]:
     """Extract service level data from 837 Professional or Institutional claims
 
     Structure:
@@ -96,27 +147,12 @@ def extract_sld_837(content: str) -> List[ServiceLevelData]:
                 └── Service Line N (2400)
     
     """
-    if not content:
-        raise ValueError("Input X12 data cannot be empty")
-    
-    # Split content into segments
-    segments = [seg.strip().split('*') for seg in content.split('~') if seg.strip()]
-    
-    # Detect claim type from GS segment
-    claim_type = None
-    for segment in segments:
-        if segment[0] == 'GS' and len(segment) > 8:
-            claim_type = CLAIM_TYPES.get(segment[8])
-            break
-    
-    if not claim_type:
-        raise ValueError("Invalid or unsupported 837 format")
-    
-    encounters = []
+    slds = []
     current_data = ClaimData(claim_type=claim_type)
     in_claim_loop = False
     in_rendering_provider_loop = False
-    
+    claim_control_number = None
+
     for i, segment in enumerate(segments):
         if len(segment) < 2:
             continue
@@ -124,7 +160,10 @@ def extract_sld_837(content: str) -> List[ServiceLevelData]:
         seg_id = segment[0]
         
         # Process NM1 segments (Provider and Patient info)
-        if seg_id == 'NM1' and len(segment) > 1:
+        if seg_id == 'ST':
+            claim_control_number = segment[2] if len(segment) > 2 else None
+
+        elif 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
@@ -236,6 +275,34 @@ def extract_sld_837(content: str) -> List[ServiceLevelData]:
                 ndc=ndc,
                 allowed_amount=None
             )
-            encounters.append(service_data)
+            slds.append(service_data)
+    
+    return slds
+
+
+def extract_sld_837(content: str) -> List[ServiceLevelData]:
+   
+    if not content:
+        raise ValueError("Input X12 data cannot be empty")
+    
+    # Split content into segments
+    segments = [seg.strip().split('*') 
+                for seg in content.split('~') if seg.strip()]
+    
+    # Detect claim type from GS segment
+    claim_type = None
+    for segment in segments:
+        if segment[0] == 'GS' and len(segment) > 8:
+            claim_type = CLAIM_TYPES.get(segment[8])
+            break
+    
+    if not claim_type:
+        raise ValueError("Invalid or unsupported 837 format")
+    
+    split_segments = split_into_claims(segments)
+    slds = []
+    for claim_segments in split_segments:
+        slds.extend(parse_837_claim_to_sld(claim_segments, claim_type))
+    
+    return slds
     
-    return encounters

hccinfhir/hccinfhir.py

@@ -88,8 +88,9 @@ class HCCInFHIR:
         # Calculate RAF score
         unique_dx_codes = self._get_unique_diagnosis_codes(sld_list)
         raf_result = self._calculate_raf_from_demographics(unique_dx_codes, demographics)
-        raf_result['service_level_data'] = sld_list
-        return raf_result
+        
+        # Create new result with service data included
+        return raf_result.model_copy(update={'service_level_data': sld_list})
     
     def run_from_service_data(self, service_data: List[Union[ServiceLevelData, Dict[str, Any]]], 
                              demographics: Union[Demographics, Dict[str, Any]]) -> RAFResult:
@@ -122,9 +123,9 @@ class HCCInFHIR:
         # Calculate RAF score
         unique_dx_codes = self._get_unique_diagnosis_codes(standardized_data)
         raf_result = self._calculate_raf_from_demographics(unique_dx_codes, demographics)
-        raf_result['service_level_data'] = standardized_data
-
-        return raf_result
+        
+        # Create new result with service data included
+        return raf_result.model_copy(update={'service_level_data': standardized_data})
         
     def calculate_from_diagnosis(self, diagnosis_codes: List[str],
                                demographics: Union[Demographics, Dict[str, Any]]) -> RAFResult:

hccinfhir/model_calculate.py

@@ -83,9 +83,11 @@ def calculate_raf(diagnosis_codes: List[str],
     coefficients = apply_coefficients(demographics, hcc_set, interactions, model_name)
 
     hcc_chronic = set()
+    interactions_chronic = {}
     for hcc in hcc_set:
         if is_chronic_mapping.get((hcc, model_name), False):
             hcc_chronic.add(hcc)
+        interactions_chronic = apply_interactions(demographics, hcc_chronic, model_name)
 
     demographic_interactions = {}
     for key, value in interactions.items():
@@ -104,29 +106,31 @@ def calculate_raf(diagnosis_codes: List[str],
                                                    model_name)
     coefficients_chronic_only = apply_coefficients(demographics, 
                                                    hcc_chronic, 
-                                                   demographic_interactions, 
+                                                   interactions_chronic, 
                                                    model_name)
     
     # Calculate risk scores
+    print(f"Coefficients: {coefficients}")
     risk_score = sum(coefficients.values())
+    print(f"Risk Score: {risk_score}")
     risk_score_demographics = sum(coefficients_demographics.values())
     risk_score_chronic_only = sum(coefficients_chronic_only.values()) - risk_score_demographics
     risk_score_hcc = risk_score - risk_score_demographics
 
-    return {
-        'risk_score': risk_score, 
-        'risk_score_demographics': risk_score_demographics,
-        'risk_score_chronic_only': risk_score_chronic_only,
-        'risk_score_hcc': risk_score_hcc,
-        'hcc_list': list(hcc_set),
-        'cc_to_dx': cc_to_dx,
-        'coefficients': coefficients,
-        'interactions': interactions,
-        'demographics': demographics,
-        'model_name': model_name,
-        'version': version,
-        'diagnosis_codes': diagnosis_codes,
-    }
+    return RAFResult(
+        risk_score=risk_score,
+        risk_score_demographics=risk_score_demographics,
+        risk_score_chronic_only=risk_score_chronic_only,
+        risk_score_hcc=risk_score_hcc,
+        hcc_list=list(hcc_set),
+        cc_to_dx=cc_to_dx,
+        coefficients=coefficients,
+        interactions=interactions,
+        demographics=demographics,
+        model_name=model_name,
+        version=version,
+        diagnosis_codes=diagnosis_codes,
+    )
 
 
 

hccinfhir/model_interactions.py

@@ -176,6 +176,7 @@ def create_disease_interactions(model_name: ModelName,
             'HF_CHR_LUNG_V28': diagnostic_cats['HF_V28'] * diagnostic_cats['CHR_LUNG_V28'],
             'HF_KIDNEY_V28': diagnostic_cats['HF_V28'] * diagnostic_cats['KIDNEY_V28'],
             'CHR_LUNG_CARD_RESP_FAIL_V28': diagnostic_cats['CHR_LUNG_V28'] * diagnostic_cats['CARD_RESP_FAIL_V28'],
+            'HF_HCC238_V28': diagnostic_cats['HF_V28'] * int('238' in hcc_set),
             'gSubUseDisorder_gPsych_V28': diagnostic_cats['gSubUseDisorder_V28'] * diagnostic_cats['gPsychiatric_V28'],
             'DISABLED_CANCER_V28': demographics.disabled * diagnostic_cats['CANCER_V28'],
             'DISABLED_NEURO_V28': demographics.disabled * diagnostic_cats['NEURO_V28'],

hccinfhir/sample_files/sample_837_12.txt

@@ -0,0 +1,113 @@
+ISA*00*          *00*          *ZZ*SUBMITTER ID   *ZZ*RECEIVER ID    *230516*1145*^*00501*000000001*0*P*:~
+GS*HC*SUBMITTER ID*RECEIVER ID*20230516*1145*1*X*005010X222A1~
+ST*837*0001*005010X222A1~
+BHT*0019*00*244579*20230516*1145*CH~
+NM1*41*2*SUBMIT CLINIC*****46*12345~
+PER*IC*CONTACT NAME*TE*5555551234~
+NM1*40*2*RECEIVER NAME*****46*67890~
+HL*1**20*1~
+NM1*85*2*BILLING PROVIDER*****XX*1234567893~
+N3*123 BILLING ST~
+N4*CITY*GA*30001~
+REF*EI*123456789~
+HL*2*1*22*0~
+SBR*P*18*******MC~
+NM1*IL*1*DOE*JOHN****MI*12345678901~
+N3*123 PATIENT ST~
+N4*CITY*GA*30001~
+DMG*D8*19800101*M~
+CLM*12345*150.00***11:B:1*Y*A*Y*Y~
+HI*ABK:I109~
+NM1*82*1*PROVIDER*JANE****XX*9876543210~
+PRV*PE*ZZ*207RC0000X~
+SV1*HC:J1745*150.00*UN*2*11***1~
+DTP*472*D8*20230515~
+LIN**N4*50242004001~
+CTP***2*150.00~
+SE*24*0001~
+ST*837*5856*005010X223A2~
+BHT*0019*00*241205204222*20241205*2042*CH~
+NM1*41*2*HSA PORT ARTHUR, LLC*****XX*1194548073~
+PER*IC*AIMEE GILL*TE*8186660602~
+NM1*40*2*OptimaFourSight*****XX*89242VA018~
+PER*IC*Jose Smith*TE*3750822093~
+HL*1**20*1~
+NM1*85*2*HSA PORT ARTHUR, LLC*****XX*1194548073~
+N3*505 N BRAND BLVD STE 1200~
+N4*GLENDALE*CA*91203~
+REF*EI*71-3391736~
+PER*IC*AIMEE GILL*TE*8186660602~
+HL*2*1*22*0~
+SBR*P*18*731323546******CI~
+NM1*IL*1*Brad*Watson*D***MI*341405376684~
+N3*2658 Edwards Lakes~
+N4*Carterchester*AZ*20036~
+CLM*4742333269*128***11:B:1*Y*A*Y*I~
+DTP*434*RD8*20240422-20240430~
+DTP*435*D8*20240809~
+DTP*096*TM*2337~
+HI*ABK:W214XXA~
+HI*ABK:S31813D~
+HI*ABK:V0492XD~
+HI*ABK:T498X6A~
+LX*1~
+SV1*HC:37180*93*UN*1***3:4:1***~
+DTP*472*D8*20180428~
+REF*6R*142671~
+LX*2~
+SV1*HC:24000*4*UN*1***1:3:4***~
+DTP*472*D8*20180428~
+REF*6R*142671~
+LX*3~
+SV1*HC:16035*31*UN*1***3***~
+DTP*472*D8*20180428~
+REF*6R*142671~
+SE*38*5856~
+ST*837*4763033*005010X223A2~
+BHT*0019*00*241205204221*20241205*2042*CH~
+NM1*41*2*HCA HEALTH SERVICES OF TENNESSEE, INC.*****XX*1265487193~
+PER*IC*DAVID SUMMERS*TE*6153421005~
+NM1*40*2*HMOOffExchangeRegion7*****XX*84014CA002~
+PER*IC*Devon Tran*TE*1808509992~
+HL*1**20*1~
+NM1*85*2*HCA HEALTH SERVICES OF TENNESSEE, INC.*****XX*1265487193~
+N3*313 N MAIN ST~
+N4*ASHLAND CITY*TN*37015~
+REF*EI*99-5971744~
+PER*IC*DAVID SUMMERS*TE*6153421005~
+HL*2*1*22*0~
+SBR*P*18*556791994******CI~
+NM1*IL*1*Jessica*Rodriguez*G***MI*151319361359~
+N3*3226 Andrew Point~
+N4*North Brentville*IA*27129~
+CLM*4742333269*839***11:B:1*Y*A*Y*I~
+DTP*434*RD8*20240422-20240430~
+DTP*435*D8*20240809~
+DTP*096*TM*2337~
+HI*ABK:V9421XS~
+HI*ABK:S35292S~
+HI*ABK:S52272S~
+HI*ABK:H68022~
+HI*ABK:T4144XD~
+HI*ABK:H1030~
+HI*ABK:S82832J~
+HI*ABK:B340~
+LX*1~
+SV1*HC:35650*161*UN*1***7:3:4:5:8***~
+DTP*472*D8*20180428~
+REF*6R*142671~
+LX*2~
+SV1*HC:73200*383*UN*1***5:2:7:4:3:6:8:1***~
+DTP*472*D8*20180428~
+REF*6R*142671~
+LX*3~
+SV1*HC:28262*194*UN*1***7:1:8***~
+DTP*472*D8*20180428~
+REF*6R*142671~
+LX*4~
+SV1*HC:84480*101*UN*1***6:3:1:2***~
+DTP*472*D8*20180428~
+REF*6R*142671~
+SE*46*4763033~
+GE*1*1~
+IEA*1*000000001~

hccinfhir/samples.py

@@ -43,7 +43,7 @@ class SampleData:
             raise ValueError("case_number must be 1, 2, or 3")
         
         try:
-            with importlib.resources.open_text('hccinfhir.samples', f'sample_eob_{case_number}.json') as f:
+            with importlib.resources.open_text('hccinfhir.sample_files', f'sample_eob_{case_number}.json') as f:
                 return json.load(f)
         except FileNotFoundError:
             raise FileNotFoundError(f"Sample EOB case {case_number} not found")
@@ -75,7 +75,7 @@ class SampleData:
         """
         try:
             output = []
-            with importlib.resources.open_text('hccinfhir.samples', 'sample_eob_200.ndjson') as f:
+            with importlib.resources.open_text('hccinfhir.sample_files', 'sample_eob_200.ndjson') as f:
                 for i, line in enumerate(f):
                     if limit is not None and i >= limit:
                         break
@@ -91,13 +91,13 @@ class SampleData:
         Retrieve a specific 837 claim sample by case number.
         
         Args:
-            case_number: The case number (0 through 11). Default is 0.
+            case_number: The case number (0 through 12). Default is 0.
             
         Returns:
             A string containing the 837 X12 claim data
             
         Raises:
-            ValueError: If case_number is not between 0 and 11
+            ValueError: If case_number is not between 0 and 12
             FileNotFoundError: If the sample file cannot be found
             
         Example:
@@ -105,11 +105,11 @@ class SampleData:
             >>> print("ISA" in sample_837)
             True
         """
-        if case_number < 0 or case_number > 11:
-            raise ValueError("case_number must be between 0 and 11")
+        if case_number < 0 or case_number > 12:
+            raise ValueError("case_number must be between 0 and 12")
         
         try:
-            with importlib.resources.open_text('hccinfhir.samples', f'sample_837_{case_number}.txt') as f:
+            with importlib.resources.open_text('hccinfhir.sample_files', f'sample_837_{case_number}.txt') as f:
                 return f.read()
         except FileNotFoundError:
             raise FileNotFoundError(f"Sample 837 case {case_number} not found")
@@ -138,20 +138,20 @@ class SampleData:
             >>> # Get all samples
             >>> all_samples = SampleData.get_837_sample_list()
             >>> print(len(all_samples))
-            12
+            13
         """
         if case_numbers is None:
-            case_numbers = list(range(12))  # 0 through 11
+            case_numbers = list(range(13))  # 0 through 12
         
         # Validate case numbers
         for case_num in case_numbers:
-            if case_num < 0 or case_num > 11:
-                raise ValueError(f"case_number {case_num} must be between 0 and 11")
+            if case_num < 0 or case_num > 12:
+                raise ValueError(f"case_number {case_num} must be between 0 and 12")
         
         output = []
         for case_num in case_numbers:
             try:
-                with importlib.resources.open_text('hccinfhir.samples', f'sample_837_{case_num}.txt') as f:
+                with importlib.resources.open_text('hccinfhir.sample_files', f'sample_837_{case_num}.txt') as f:
                     output.append(f.read())
             except FileNotFoundError:
                 raise FileNotFoundError(f"Sample 837 case {case_num} not found")
@@ -180,8 +180,8 @@ class SampleData:
             ],
             "eob_case_numbers": [1, 2, 3],
             "eob_list_size": 200,
-            "837_samples": [f"sample_837_{i}.txt" for i in range(12)],
-            "837_case_numbers": list(range(12)),
+            "837_samples": [f"sample_837_{i}.txt" for i in range(13)],
+            "837_case_numbers": list(range(13)),
             "description": {
                 "eob": "Explanation of Benefits (FHIR resources) for testing HCC calculations",
                 "837": "X12 837 claim data for testing claim processing"
@@ -221,7 +221,7 @@ def get_837_sample(case_number: int = 0) -> str:
     Convenience function to get an 837 claim sample.
     
     Args:
-        case_number: The case number (0 through 11). Default is 0.
+        case_number: The case number (0 through 12). Default is 0.
         
     Returns:
         A string containing the 837 X12 claim data