hccinfhir 0.0.4__py3-none-any.whl → 0.0.6__py3-none-any.whl

hccinfhir/datamodels.py

@@ -1,5 +1,5 @@
 from pydantic import BaseModel, Field
-from typing import List, Optional, Literal, Dict, Any, TypedDict
+from typing import List, Optional, Literal, Dict, Set, TypedDict
 
 # Define Model Name literal type
 ModelName = Literal[
@@ -10,6 +10,17 @@ ModelName = Literal[
     "CMS-HCC ESRD Model V24",
     "RxHCC Model V08"
 ]
+
+ProcFilteringFilename = Literal[
+    "ra_eligible_cpt_hcpcs_2023.csv",
+    "ra_eligible_cpt_hcpcs_2024.csv",
+    "ra_eligible_cpt_hcpcs_2025.csv"
+]
+
+DxCCMappingFilename = Literal[
+    "ra_dx_to_cc_2025.csv"
+]
+
 class ServiceLevelData(BaseModel):
     """
     Represents standardized service-level data extracted from healthcare claims.
@@ -56,29 +67,35 @@ class Demographics(BaseModel):
     """
     Response model for demographic categorization
     """
-    age: int = Field(..., description="Beneficiary age")
-    sex: Literal['M', 'F', '1', '2'] = Field(..., description="Beneficiary sex")
-    dual_elgbl_cd: Literal[None, 'NA', '99', '00', '01', '02', '03', '04', '05', '06', '07', '08', '09', '10'] = Field('NA', description="Dual status code")
-    orec: Literal[None, '0', '1', '2', '3'] = Field('0', description="Original reason for entitlement")
-    crec: Literal[None, '0', '1', '2', '3'] = Field('0', description="Current reason for entitlement")
-    new_enrollee: bool = Field(False, description="True if beneficiary is a new enrollee")
-    snp: bool = Field(False, description="True if beneficiary is in SNP")
-    version: str = Field("V2", description="Version of categorization used (V2, V4, V6)")
-    low_income: bool = Field(False, description="True if beneficiary is in low income; RxHCC only")
+    age: int = Field(..., description="[required] Beneficiary age")
+    sex: Literal['M', 'F', '1', '2'] = Field(..., description="[required] Beneficiary sex")
+    dual_elgbl_cd: Optional[Literal[None, 'NA', '99', '00', '01', '02', '03', '04', '05', '06', '07', '08', '09', '10']] = Field('NA', description="Dual status code")
+    orec: Optional[Literal[None, '0', '1', '2', '3']] = Field('0', description="Original reason for entitlement")
+    crec: Optional[Literal[None, '0', '1', '2', '3']] = Field('0', description="Current reason for entitlement")
+    new_enrollee: Optional[bool] = Field(False, description="True if beneficiary is a new enrollee")
+    snp: Optional[bool] = Field(False, description="True if beneficiary is in SNP")
+    version: Optional[str] = Field("V2", description="Version of categorization used (V2, V4, V6)")
+    low_income: Optional[bool] = Field(False, description="True if beneficiary is in low income; RxHCC only")
     graft_months: Optional[int] = Field(None, description="Number of months since transplant; ESRD Model only")
-    category: str = Field(..., description="[derived] Age-sex category code")
-    non_aged: bool = Field(False, description="[derived] True if age <= 64")
-    orig_disabled: bool = Field(False, description="[derived] True if originally disabled (OREC='1' and not currently disabled)")
-    disabled: bool = Field(False, description="[derived] True if currently disabled (age < 65 and OREC != '0')")
-    esrd: bool = Field(False, description="[derived] True if ESRD (ESRD Model)")
-    lti: bool = Field(False, description="[derived] True if LTI (LTI Model)") 
-    fbd: bool = Field(False, description="[derived] True if FBD (FBD Model)") 
-    pbd: bool = Field(False, description="[derived] True if PBD (PBD Model)")
+    category: Optional[str] = Field(None, description="[derived] Age-sex category code")
+    non_aged: Optional[bool] = Field(False, description="[derived] True if age <= 64")
+    orig_disabled: Optional[bool] = Field(False, description="[derived] True if originally disabled (OREC='1' and not currently disabled)")
+    disabled: Optional[bool] = Field(False, description="[derived] True if currently disabled (age < 65 and OREC != '0')")
+    esrd: Optional[bool] = Field(False, description="[derived] True if ESRD (ESRD Model)")
+    lti: Optional[bool] = Field(False, description="[derived] True if LTI (LTI Model)") 
+    fbd: Optional[bool] = Field(False, description="[derived] True if FBD (FBD Model)") 
+    pbd: Optional[bool] = Field(False, description="[derived] True if PBD (PBD Model)")
 
 
 class RAFResult(TypedDict):
     """Type definition for RAF calculation results"""
     risk_score: float
     hcc_list: List[str]
-    details: Dict[str, Any]
-    service_level_data: List[ServiceLevelData]
+    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]]

hccinfhir/filter.py

@@ -1,12 +1,10 @@
 from typing import List, Set
 from hccinfhir.datamodels import ServiceLevelData
-import importlib.resources
+from hccinfhir.utils import load_proc_filtering
 
 # use import importlib.resources to load the professional_cpt_fn file as a list of strings
 professional_cpt_default_fn = 'ra_eligible_cpt_hcpcs_2023.csv'
-professional_cpt_default = []
-with importlib.resources.open_text('hccinfhir.data', professional_cpt_default_fn) as f:
-    professional_cpt_default = set(f.read().splitlines())
+professional_cpt_default = load_proc_filtering(professional_cpt_default_fn)
 
 def apply_filter(
     data: List[ServiceLevelData], 

hccinfhir/hccinfhir.py

@@ -2,8 +2,8 @@ from typing import List, Dict, Any, Union
 from hccinfhir.extractor import extract_sld_list
 from hccinfhir.filter import apply_filter
 from hccinfhir.model_calculate import calculate_raf
-from hccinfhir.datamodels import Demographics, ServiceLevelData, RAFResult, ModelName
-
+from hccinfhir.datamodels import Demographics, ServiceLevelData, RAFResult, ModelName, ProcFilteringFilename, DxCCMappingFilename
+from hccinfhir.utils import load_proc_filtering, load_dx_to_cc_mapping
 
 class HCCInFHIR:
     """
@@ -15,17 +15,26 @@ class HCCInFHIR:
     
     def __init__(self, 
                  filter_claims: bool = True, 
-                 model_name: ModelName = "CMS-HCC Model V28"):
+                 model_name: ModelName = "CMS-HCC Model V28",
+                 proc_filtering_filename: ProcFilteringFilename = "ra_eligible_cpt_hcpcs_2025.csv",
+                 dx_cc_mapping_filename: DxCCMappingFilename = "ra_dx_to_cc_2025.csv"):
         """
         Initialize the HCCInFHIR processor.
         
         Args:
             filter_claims: Whether to apply filtering rules to claims. Default is True.
             model_name: The name of the model to use for the calculation. Default is "CMS-HCC Model V28".
+            proc_filtering_filename: The filename of the professional cpt filtering file. Default is "ra_eligible_cpt_hcpcs_2025.csv".
+            dx_cc_mapping_filename: The filename of the dx to cc mapping file. Default is "ra_dx_to_cc_2025.csv".
         """
         self.filter_claims = filter_claims
         self.model_name = model_name
-        
+        self.proc_filtering_filename = proc_filtering_filename
+        self.dx_cc_mapping_filename = dx_cc_mapping_filename
+        self.professional_cpt = load_proc_filtering(proc_filtering_filename)
+        self.dx_to_cc_mapping = load_dx_to_cc_mapping(dx_cc_mapping_filename)
+
+
     def _ensure_demographics(self, demographics: Union[Demographics, Dict[str, Any]]) -> Demographics:
         """Convert demographics dict to Demographics object if needed."""
         if not isinstance(demographics, Demographics):
@@ -33,7 +42,7 @@ class HCCInFHIR:
         return demographics
     
     def _calculate_raf_from_demographics(self, diagnosis_codes: List[str], 
-                                       demographics: Demographics) -> Dict[str, Any]:
+                                       demographics: Demographics) -> RAFResult:
         """Calculate RAF score using demographics data."""
         return calculate_raf(
             diagnosis_codes=diagnosis_codes,
@@ -46,58 +55,40 @@ class HCCInFHIR:
             new_enrollee=demographics.new_enrollee,
             snp=demographics.snp,
             low_income=demographics.low_income,
-            graft_months=demographics.graft_months
+            graft_months=demographics.graft_months,
+            dx_to_cc_mapping=self.dx_to_cc_mapping
         )
 
     def _get_unique_diagnosis_codes(self, service_data: List[ServiceLevelData]) -> List[str]:
         """Extract unique diagnosis codes from service level data."""
-        all_dx_codes = []
-        for sld in service_data:
-            all_dx_codes.extend(sld.claim_diagnosis_codes)
-        return list(set(all_dx_codes))
+        return list({code for sld in service_data for code in sld.claim_diagnosis_codes})
 
-    def _format_result(self, 
-                  raf_result: Union[Dict[str, Any], RAFResult], 
-                  service_data: List[ServiceLevelData]) -> RAFResult:
-        """
-        Format RAF calculation results into a standardized RAFResult format.
+    def run(self, eob_list: List[Dict[str, Any]], 
+            demographics: Union[Demographics, Dict[str, Any]]) -> RAFResult:
+        """Process EOB resources and calculate RAF scores.
         
-        Returns a dictionary conforming to the RAFResult TypedDict structure.
+        Args:
+            eob_list: List of EOB resources
+            demographics: Demographics information
+            
+        Returns:
+            RAFResult object containing calculated scores and processed data
         """
+        if not isinstance(eob_list, list):
+            raise ValueError("eob_list must be a list; if no eob, pass empty list")
         
-        # Check if raf_result already has the expected RAFResult structure
-        if all(key in raf_result for key in ['risk_score', 'hcc_list', 'details']):
-            # Already in RAFResult format, just ensure service data is set
-            result = dict(raf_result)  # Create a copy to avoid modifying the original
-            result['service_level_data'] = service_data
-            return result
-        
-        # Handle result from calculate_raf function
-        if 'raf' in raf_result and 'coefficients' in raf_result:
-            return {
-                'risk_score': raf_result['raf'],
-                'hcc_list': list(raf_result['coefficients'].keys()),
-                'details': raf_result['coefficients'],
-                'service_level_data': service_data
-            }
-        
-        # Unrecognized format
-        raise ValueError(f"Unrecognized RAF result format: {list(raf_result.keys())}")
-
-    def run(self, eob_list: List[Dict[str, Any]], 
-            demographics: Union[Demographics, Dict[str, Any]]) -> RAFResult:
         demographics = self._ensure_demographics(demographics)
         
         # Extract and filter service level data
         sld_list = extract_sld_list(eob_list)
         if self.filter_claims:
-            sld_list = apply_filter(sld_list)
+            sld_list = apply_filter(sld_list, self.professional_cpt)
             
         # Calculate RAF score
         unique_dx_codes = self._get_unique_diagnosis_codes(sld_list)
         raf_result = self._calculate_raf_from_demographics(unique_dx_codes, demographics)
-        
-        return self._format_result(raf_result, sld_list)
+        raf_result['service_level_data'] = sld_list
+        return raf_result
     
     def run_from_service_data(self, service_data: List[Union[ServiceLevelData, Dict[str, Any]]], 
                              demographics: Union[Demographics, Dict[str, Any]]) -> RAFResult:
@@ -126,17 +117,33 @@ class HCCInFHIR:
                 )
         
         if self.filter_claims:
-            standardized_data = apply_filter(standardized_data)
+            standardized_data = apply_filter(standardized_data, 
+                                             professional_cpt=self.professional_cpt)
+
         
         # Calculate RAF score
         unique_dx_codes = self._get_unique_diagnosis_codes(standardized_data)
         raf_result = self._calculate_raf_from_demographics(unique_dx_codes, demographics)
-        
-        return self._format_result(raf_result, standardized_data)
+        raf_result['service_level_data'] = standardized_data
+
+        return raf_result
         
     def calculate_from_diagnosis(self, diagnosis_codes: List[str],
                                demographics: Union[Demographics, Dict[str, Any]]) -> RAFResult:
+        """Calculate RAF scores from a list of diagnosis codes.
+        
+        Args:
+            diagnosis_codes: List of diagnosis codes
+            demographics: Demographics information
+            
+        Raises:
+            ValueError: If diagnosis_codes is empty or not a list
+        """
+        if not isinstance(diagnosis_codes, list):
+            raise ValueError("diagnosis_codes must be a list")
+        if not diagnosis_codes:
+            raise ValueError("diagnosis_codes list cannot be empty")
+        
         demographics = self._ensure_demographics(demographics)
         raf_result = self._calculate_raf_from_demographics(diagnosis_codes, demographics)
-        # Create an empty service level data list since we're calculating directly from diagnosis codes
-        return self._format_result(raf_result, []) 
+        return raf_result

hccinfhir/model_calculate.py

@@ -1,10 +1,15 @@
-from typing import List, Union
-from hccinfhir.datamodels import ModelName
+from typing import List, Union, Dict, Tuple, Set
+from hccinfhir.datamodels import ModelName, RAFResult
 from hccinfhir.model_demographics import categorize_demographics
 from hccinfhir.model_dx_to_cc import apply_mapping
 from hccinfhir.model_hierarchies import apply_hierarchies
 from hccinfhir.model_coefficients import apply_coefficients
 from hccinfhir.model_interactions import apply_interactions
+from hccinfhir.utils import load_dx_to_cc_mapping
+
+# Load default mappings from csv file
+mapping_file_default = 'ra_dx_to_cc_2025.csv'
+dx_to_cc_default = load_dx_to_cc_mapping(mapping_file_default)
 
 def calculate_raf(diagnosis_codes: List[str],
                   model_name: ModelName = "CMS-HCC Model V28",
@@ -16,14 +21,43 @@ def calculate_raf(diagnosis_codes: List[str],
                   new_enrollee: bool = False,   
                   snp: bool = False,
                   low_income: bool = False,
-                  graft_months: int = None):
+                  graft_months: int =  None,
+                  dx_to_cc_mapping: Dict[Tuple[str, ModelName], Set[str]] = dx_to_cc_default) -> RAFResult:
+    """
+    Calculate Risk Adjustment Factor (RAF) based on diagnosis codes and demographic information.
+
+    Args:
+        diagnosis_codes: List of ICD-10 diagnosis codes
+        model_name: Name of the HCC model to use
+        age: Patient's age
+        sex: Patient's sex ('M' or 'F')
+        dual_elgbl_cd: Dual eligibility code
+        orec: Original reason for entitlement code
+        crec: Current reason for entitlement code
+        new_enrollee: Whether the patient is a new enrollee
+        snp: Special Needs Plan indicator
+        low_income: Low income subsidy indicator
+        graft_months: Number of months since transplant
+
+    Returns:
+        Dictionary containing RAF score and coefficients used in calculation
+
+    Raises:
+        ValueError: If input parameters are invalid
+    """
+    # Input validation
+    if not isinstance(age, (int, float)) or age < 0:
+        raise ValueError("Age must be a non-negative number")
+    
+    if sex not in ['M', 'F', '1', '2']:
+        raise ValueError("Sex must be 'M' or 'F' or '1' or '2'")
 
     version = 'V2'
     if 'RxHCC' in model_name:
         version = 'V4'
     elif 'HHS-HCC' in model_name: # not implemented yet
         version = 'V6'
-
+    
     demographics = categorize_demographics(age, 
                                            sex, 
                                            dual_elgbl_cd, 
@@ -35,16 +69,27 @@ def calculate_raf(diagnosis_codes: List[str],
                                            low_income, 
                                            graft_months)
     
-    cc_to_dx = apply_mapping(diagnosis_codes, model_name)
+    cc_to_dx = apply_mapping(diagnosis_codes, 
+                             model_name, 
+                             dx_to_cc_mapping=dx_to_cc_mapping)
     hcc_set = set(cc_to_dx.keys())
     hcc_set = apply_hierarchies(hcc_set, model_name)
     interactions = apply_interactions(demographics, hcc_set, model_name)
     coefficients = apply_coefficients(demographics, hcc_set, interactions, model_name)
     
-    raf = sum(coefficients.values())
-
+    risk_score = sum(coefficients.values())
 
-    return {'raf': raf, 'coefficients': coefficients}
+    return {
+        'risk_score': risk_score, 
+        '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_dx_to_cc.py

@@ -1,31 +1,15 @@
 from typing import List, Dict, Set, Tuple, Optional
-import importlib.resources
 from hccinfhir.datamodels import ModelName
+from hccinfhir.utils import load_dx_to_cc_mapping
 
 # Load default mappings from csv file
 mapping_file_default = 'ra_dx_to_cc_2025.csv'
-dx_to_cc_default: Dict[Tuple[str, ModelName], Set[str]] = {}  # (diagnosis_code, model_name) -> cc
-
-try:
-    with importlib.resources.open_text('hccinfhir.data', mapping_file_default) as f:
-        for line in f.readlines()[1:]:  # Skip header
-            try:
-                diagnosis_code, cc, model_name = line.strip().split(',')
-                key = (diagnosis_code, model_name)
-                if key not in dx_to_cc_default:
-                    dx_to_cc_default[key] = {cc}
-                else:
-                    dx_to_cc_default[key].add(cc)
-            except ValueError:
-                continue  # Skip malformed lines
-except Exception as e:
-    print(f"Error loading mapping file: {e}")
-    dx_to_cc_default = {}
+dx_to_cc_default = load_dx_to_cc_mapping(mapping_file_default)
 
 def get_cc(
     diagnosis_code: str,
     model_name: ModelName = "CMS-HCC Model V28",
-    dx_to_cc: Dict[Tuple[str, str], Set[str]] = dx_to_cc_default
+    dx_to_cc_mapping: Dict[Tuple[str, ModelName], Set[str]] = dx_to_cc_default
 ) -> Optional[Set[str]]:
     """
     Get CC for a single diagnosis code.
@@ -33,17 +17,17 @@ def get_cc(
     Args:
         diagnosis_code: ICD-10 diagnosis code
         model_name: HCC model name to use for mapping
-        dx_to_cc: Optional custom mapping dictionary
+        dx_to_cc_mapping: Optional custom mapping dictionary
 
     Returns:
         CC code if found, None otherwise
     """
-    return dx_to_cc.get((diagnosis_code, model_name))
+    return dx_to_cc_mapping.get((diagnosis_code, model_name))
 
 def apply_mapping(
     diagnoses: List[str],
     model_name: ModelName = "CMS-HCC Model V28", 
-    dx_to_cc: Dict[Tuple[str, str], Set[str]] = dx_to_cc_default
+    dx_to_cc_mapping: Dict[Tuple[str, ModelName], Set[str]] = dx_to_cc_default
 ) -> Dict[str, Set[str]]:
     """
     Apply ICD-10 to CC mapping for a list of diagnosis codes.
@@ -51,7 +35,7 @@ def apply_mapping(
     Args:
         diagnoses: List of ICD-10 diagnosis codes
         model_name: HCC model name to use for mapping
-        dx_to_cc: Optional custom mapping dictionary
+        dx_to_cc_mapping: Optional custom mapping dictionary
         
     Returns:
         Dictionary mapping CCs to lists of diagnosis codes that map to them
@@ -60,7 +44,7 @@ def apply_mapping(
     
     for dx in set(diagnoses):
         dx = dx.upper().replace('.', '')
-        ccs = get_cc(dx, model_name, dx_to_cc)
+        ccs = get_cc(dx, model_name, dx_to_cc_mapping)
         if ccs is not None:
             for cc in ccs:
                 if cc not in cc_to_dx:

hccinfhir/utils.py

@@ -0,0 +1,51 @@
+from typing import Set, Dict, Tuple
+import importlib.resources
+from hccinfhir.datamodels import ModelName, ProcFilteringFilename, DxCCMappingFilename
+
+def load_proc_filtering(filename: ProcFilteringFilename) -> Set[str]:
+    """
+    Load a single-column CSV file into a set of strings.
+    
+    Args:
+        filename: Name of the CSV file in the hccinfhir.data package
+        
+    Returns:
+        Set of strings from the CSV file
+    """
+    try:
+        with importlib.resources.open_text('hccinfhir.data', filename) as f:
+            return set(f.read().splitlines())
+    except Exception as e:
+        print(f"Error loading {filename}: {e}")
+        return set()
+
+def load_dx_to_cc_mapping(filename: DxCCMappingFilename) -> Dict[Tuple[str, ModelName], Set[str]]:
+    """
+    Load diagnosis to CC mapping from a CSV file.
+    Expected format: diagnosis_code,cc,model_name
+    
+    Args:
+        filename: Name of the CSV file in the hccinfhir.data package
+        
+    Returns:
+        Dictionary mapping (diagnosis_code, model_name) to a set of CC codes
+    """
+    mapping: Dict[Tuple[str, ModelName], Set[str]] = {}
+    
+    try:
+        with importlib.resources.open_text('hccinfhir.data', filename) as f:
+            for line in f.readlines()[1:]:  # Skip header
+                try:
+                    diagnosis_code, cc, model_name = line.strip().split(',')
+                    key = (diagnosis_code, model_name)
+                    if key not in mapping:
+                        mapping[key] = {cc}
+                    else:
+                        mapping[key].add(cc)
+                except ValueError:
+                    continue  # Skip malformed lines
+    except Exception as e:
+        print(f"Error loading mapping file: {e}")
+        return {}
+    
+    return mapping 

{hccinfhir-0.0.4.dist-info → hccinfhir-0.0.6.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: hccinfhir
-Version: 0.0.4
+Version: 0.0.6
 Summary: HCC Algorithm for FHIR Resources
 Project-URL: Homepage, https://github.com/mimilabs/hccinfhir
 Project-URL: Issues, https://github.com/mimilabs/hccinfhir/issues
@@ -20,6 +20,9 @@ A Python library for extracting standardized service-level data from FHIR Explan
 - 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
+- Multiple HCC model support (V22, V24, V28, ESRD V21, ESRD V24, RxHCC V08)
+- Flexible input options: FHIR EOBs, service data, or direct diagnosis codes
+
 
 ## Installation
 ```bash
@@ -109,16 +112,75 @@ result = calculate_raf(
 )
 ```
 
-### 4. Running HCC on FHIR data
+### 4. HCCInFHIR Class
+The main processor class that integrates extraction, filtering, and calculation components:
 
 ```python
-from hccinfhir import HCCInFHIR
+from hccinfhir.hccinfhir import HCCInFHIR
+from hccinfhir.datamodels import Demographics
+
+# Initialize with custom configuration
+hcc_processor = HCCInFHIR(
+    filter_claims=True,                                    # Enable claim filtering
+    model_name="CMS-HCC Model V28",                       # Choose HCC model version
+    proc_filtering_filename="ra_eligible_cpt_hcpcs_2025.csv",  # CPT/HCPCS filtering rules
+    dx_cc_mapping_filename="ra_dx_to_cc_2025.csv"         # Diagnosis to CC mapping
+)
+
+# Define beneficiary demographics
+demographics = {
+    age=67,
+    sex='F'
+}
 
-hcc_processor = HCCInFHIR()
+# Method 1: Process FHIR EOB resources
+raf_result = hcc_processor.run(eob_list, demographics)
 
-result = hcc_processor.run(eob_list, demographic_data)
+# Method 2: Process service level data
+service_data = [{
+    "procedure_code": "99214",
+    "claim_diagnosis_codes": ["E11.9", "I10"],
+    "claim_type": "71",
+    "service_date": "2024-01-15"
+}]
+raf_result = hcc_processor.run_from_service_data(service_data, demographics)
+
+# Method 3: Direct diagnosis processing
+diagnosis_codes = ['E119', 'I509']
+raf_result = hcc_processor.calculate_from_diagnosis(diagnosis_codes, demographics)
+
+# RAF Result contains:
+print(f"Risk Score: {raf_result['risk_score']}")
+print(f"HCC List: {raf_result['hcc_list']}")
+print(f"CC to Diagnosis Mapping: {raf_result['cc_to_dx']}")
+print(f"Applied Coefficients: {raf_result['coefficients']}")
+print(f"Applied Interactions: {raf_result['interactions']}")
 ```
 
+The HCCInFHIR class provides three main processing methods:
+
+1. `run(eob_list, demographics)`: Process FHIR ExplanationOfBenefit resources
+   - Extracts service data from FHIR resources
+   - Applies filtering rules if enabled
+   - Calculates RAF scores using the specified model
+
+2. `run_from_service_data(service_data, demographics)`: Process standardized service data
+   - Accepts pre-formatted service level data
+   - Validates data structure using Pydantic models
+   - Applies filtering and calculates RAF scores
+
+3. `calculate_from_diagnosis(diagnosis_codes, demographics)`: Direct diagnosis processing
+   - Processes raw diagnosis codes without service context
+   - Useful for quick RAF calculations or validation
+   - Bypasses service-level filtering
+
+Each method returns a RAFResult containing:
+- Final risk score
+- List of HCCs
+- Mapping of condition categories to diagnosis codes
+- Applied coefficients and interactions
+- Processed service level data (when applicable)
+
 ## Testing
 ```bash
 $ python3 -m hatch shell
@@ -230,8 +292,21 @@ FROM ra_coefficients
 WHERE eff_last_date > '2025-01-01';
 ```   
 
+`ra_eligible_cpt_hcpcs_2025.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) = 2024;
+```
+
 ## Contributing
 Join us at [mimilabs](https://mimilabs.ai/signup). Reference data available in MIMILabs data lakehouse.
 
+## Publishing (only for those maintainers...)
+```bash
+$ python3 -m hatch build
+$ python3 -m hatch publish
+```
+
 ## License
 Apache License 2.0

{hccinfhir-0.0.4.dist-info → hccinfhir-0.0.6.dist-info}/RECORD

@@ -1,20 +1,23 @@
 hccinfhir/__init__.py,sha256=OCyYCv4jTOlYHZbTw2DTks3e6_YT1N2JXAOuyR03KNE,43
-hccinfhir/datamodels.py,sha256=S-wQQXEyya_RbrMLmHCPWouaFvEflV8762mciwhrtSk,4270
+hccinfhir/datamodels.py,sha256=ZohKX_LqtcEkGW3-tvtj9AWMepMooNtWpchSv9bOXuQ,4845
 hccinfhir/extractor.py,sha256=-jHVCIJqFAqvrI9GxkkXZVDQjKDa-7vF7v3PGMGAMnA,1801
 hccinfhir/extractor_837.py,sha256=vkTBCd0WBaJoTrUd-Z-zCIaoLk7KV2n4AGqIORhONIk,7147
 hccinfhir/extractor_fhir.py,sha256=Rg_L0Vg5tz_L2VJ_jvZwWz6RMlPAkHwj4LiK-OWQvrQ,8458
-hccinfhir/filter.py,sha256=tyaK0Ss0rafkDfcCJWUZOAzzFOIYiuf_SuJ4BBiHJ38,2272
-hccinfhir/hccinfhir.py,sha256=IS3Hvm8wnFL785XkANva6qB9kkc54OCFn-KkwuW5BX0,6450
-hccinfhir/model_calculate.py,sha256=EA5JvbB36wrFAt6kD79E8rn9NKntVMJqXHAq_p7duEE,1947
+hccinfhir/filter.py,sha256=8uYThN0-AqwVAKyti29WGiFwQKDiremMhYd_m6QcXhM,2193
+hccinfhir/hccinfhir.py,sha256=YdooDAezKPF1VXoAeW8tsvQwm9SZ6u2SO-a0rhoX0iY,6933
+hccinfhir/model_calculate.py,sha256=6cjWMtayC9fBxhTCnbqSJSlctblYz4Mn9vQYDXx-Iu8,3725
 hccinfhir/model_coefficients.py,sha256=UrDAEWBoqooSC8hy9YSUsLMmmfgIO0YGtVkui6ruOkE,5528
 hccinfhir/model_demographics.py,sha256=LZLlPQOtxPh3Md6q9xwztQ9PwrUo_gloNCYSa2bDirY,6578
-hccinfhir/model_dx_to_cc.py,sha256=foKn2A0ly2TOVKq5qA92CuZSxHPX00cqt5D-DjBm9x4,2348
+hccinfhir/model_dx_to_cc.py,sha256=jCFlnAOBkfI9FrCX6tZIh-Sp_DW0HwpY7QrPXGtwInI,1765
 hccinfhir/model_hierarchies.py,sha256=e8QtSayTrfPv2wh149FjK7ToiEmU1ISYMA1Pi38iVk0,2700
 hccinfhir/model_interactions.py,sha256=ZLiKJepPjPkYceKDf7dLXoYE0p44I7t9y2sTOlrxojo,20264
+hccinfhir/utils.py,sha256=5tPwf_neqSJXlerhHbrPPihC0nMKsU40HOBoNCEkGco,1791
 hccinfhir/data/__init__.py,sha256=SGiSkpGrnxbvtEFMMlk82NFHOE50hFXcgKwKUSuVZUg,45
 hccinfhir/data/ra_coefficients_2025.csv,sha256=I0S2hoJlfig-D0oSFxy0b3Piv7m9AzOGo2CwR6bcQ9w,215191
 hccinfhir/data/ra_dx_to_cc_2025.csv,sha256=4N7vF6VZndkl7d3Fo0cGsbAPAZdCjAizSH8BOKsZNAo,1618924
 hccinfhir/data/ra_eligible_cpt_hcpcs_2023.csv,sha256=VVoA4s0hsFmcRIugyFdbvSoeLcn7M7z0DITT6l4YqL8,39885
+hccinfhir/data/ra_eligible_cpt_hcpcs_2024.csv,sha256=CawKImfCb8fFMDbWwqvNLRyRAda_u9N8Q3ne8QAAe54,40191
+hccinfhir/data/ra_eligible_cpt_hcpcs_2025.csv,sha256=-tMvv2su5tsSbGUh6fZZCMUEkXInBpcTtbUCi2o_UwI,40359
 hccinfhir/data/ra_hierarchies_2025.csv,sha256=HQSPNloe6mvvwMgv8ZwYAfWKkT2b2eUvm4JQy6S_mVQ,13045
 hccinfhir/samples/__init__.py,sha256=SGiSkpGrnxbvtEFMMlk82NFHOE50hFXcgKwKUSuVZUg,45
 hccinfhir/samples/sample_837_0.txt,sha256=eggrD259uHa05z2dfxWBpUDseSDp_AQcLyN_adpHyTw,5295
@@ -33,7 +36,7 @@ hccinfhir/samples/sample_eob_1.json,sha256=_NGSVR2ysFpx-DcTvyga6dFCzhQ8Vi9fNzQEM
 hccinfhir/samples/sample_eob_2.json,sha256=FcnJcx0ApOczxjJ_uxVLzCep9THfNf4xs9Yf7hxk8e4,1769
 hccinfhir/samples/sample_eob_200.ndjson,sha256=CxpjeQ1DCMUzZILaM68UEhfxO0p45YGhDDoCZeq8PxU,1917986
 hccinfhir/samples/sample_eob_3.json,sha256=4BW4wOMBEEU9RDfJR15rBEvk0KNHyuMEh3e055y87Hc,2306
-hccinfhir-0.0.4.dist-info/METADATA,sha256=_A0qRJoRtyxs2NHjypr8DP-DSIK_bg_sRgBoOMrtSig,8763
-hccinfhir-0.0.4.dist-info/WHEEL,sha256=C2FUgwZgiLbznR-k0b_5k3Ai_1aASOXDss3lzCUsUug,87
-hccinfhir-0.0.4.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-hccinfhir-0.0.4.dist-info/RECORD,,
+hccinfhir-0.0.6.dist-info/METADATA,sha256=ZrsvQOjZWL2E5LMv4-H6VIBr0OiTTFL7SVsmq8ivfdk,11567
+hccinfhir-0.0.6.dist-info/WHEEL,sha256=C2FUgwZgiLbznR-k0b_5k3Ai_1aASOXDss3lzCUsUug,87
+hccinfhir-0.0.6.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+hccinfhir-0.0.6.dist-info/RECORD,,