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

hccinfhir/hccinfhir.py

@@ -0,0 +1,149 @@
+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, ProcFilteringFilename, DxCCMappingFilename
+from hccinfhir.utils import load_proc_filtering, load_dx_to_cc_mapping
+
+class HCCInFHIR:
+    """
+    Main class for processing FHIR EOB resources into HCC risk scores.
+    
+    This class integrates the extraction, filtering, and calculation components
+    of the hccinfhir library.
+    """
+    
+    def __init__(self, 
+                 filter_claims: bool = True, 
+                 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):
+            return Demographics(**demographics)
+        return demographics
+    
+    def _calculate_raf_from_demographics(self, diagnosis_codes: List[str], 
+                                       demographics: Demographics) -> RAFResult:
+        """Calculate RAF score using demographics data."""
+        return calculate_raf(
+            diagnosis_codes=diagnosis_codes,
+            model_name=self.model_name,
+            age=demographics.age,
+            sex=demographics.sex,
+            dual_elgbl_cd=demographics.dual_elgbl_cd,
+            orec=demographics.orec,
+            crec=demographics.crec,
+            new_enrollee=demographics.new_enrollee,
+            snp=demographics.snp,
+            low_income=demographics.low_income,
+            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."""
+        return list({code for sld in service_data for code in sld.claim_diagnosis_codes})
+
+    def run(self, eob_list: List[Dict[str, Any]], 
+            demographics: Union[Demographics, Dict[str, Any]]) -> RAFResult:
+        """Process EOB resources and calculate RAF scores.
+        
+        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")
+        
+        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, 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)
+        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:
+        demographics = self._ensure_demographics(demographics)
+        
+        if not isinstance(service_data, list):
+            raise ValueError("Service data must be a list of service records")
+        
+        if not service_data:
+            raise ValueError("Service data list cannot be empty")
+        
+        # Standardize service data with better error handling
+        standardized_data = []
+        for idx, item in enumerate(service_data):
+            try:
+                if isinstance(item, dict):
+                    standardized_data.append(ServiceLevelData(**item))
+                elif isinstance(item, ServiceLevelData):
+                    standardized_data.append(item)
+                else:
+                    raise TypeError(f"Service data item must be a dictionary or ServiceLevelData object")
+            except (KeyError, TypeError, ValueError) as e:
+                raise ValueError(
+                    f"Invalid service data at index {idx}: {str(e)}. "
+                    "Required fields: claim_type, claim_diagnosis_codes, procedure_code, service_date"
+                )
+        
+        if self.filter_claims:
+            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)
+        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)
+        return raf_result

hccinfhir/model_calculate.py

@@ -0,0 +1,95 @@
+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",
+                  age: Union[int, float] = 65, 
+                  sex: str = 'F', 
+                  dual_elgbl_cd: str = 'NA',
+                  orec: str = '0', 
+                  crec: str = '0',
+                  new_enrollee: bool = False,   
+                  snp: bool = False,
+                  low_income: bool = False,
+                  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, 
+                                           orec, 
+                                           crec, 
+                                           version, 
+                                           new_enrollee, 
+                                           snp, 
+                                           low_income, 
+                                           graft_months)
+    
+    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)
+    
+    risk_score = sum(coefficients.values())
+
+    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_coefficients.py

@@ -0,0 +1,143 @@
+from typing import Dict, Tuple
+import importlib.resources
+from hccinfhir.datamodels import ModelName, Demographics
+
+# Load default mappings from csv file
+coefficients_file_default = 'ra_coefficients_2025.csv'
+coefficients_default: Dict[Tuple[str, ModelName], float] = {}  # (diagnosis_code, model_name) -> value
+
+try:
+    with importlib.resources.open_text('hccinfhir.data', coefficients_file_default) as f:
+        for line in f.readlines()[1:]:  # Skip header
+            try:
+                coefficient, value, model_domain, model_version = line.strip().split(',')
+                if model_domain == 'ESRD':  
+                    model_name = f"CMS-HCC {model_domain} Model V{model_version[-2:]}"
+                else:
+                    model_name = f"{model_domain} Model V{model_version[-2:]}"
+                
+                key = (coefficient.lower(), model_name)
+                if key not in coefficients_default:
+                    coefficients_default[key] = float(value)
+                else:
+                    coefficients_default[key] = float(value)
+            except ValueError:
+                continue  # Skip malformed lines
+except Exception as e:
+    print(f"Error loading mapping file: {e}")
+    coefficients_default = {}
+
+def get_coefficent_prefix(demographics: Demographics, 
+                          model_name: ModelName = "CMS-HCC Model V28") -> str:
+
+    """
+    Get the coefficient prefix based on beneficiary demographics.
+    
+    Args:
+        demographics: Demographics object containing beneficiary information
+        
+    Returns:
+        String prefix used to look up coefficients for this beneficiary type
+    """
+    # Get base prefix based on model type
+    if 'ESRD' in model_name:
+        if demographics.esrd:
+            if demographics.graft_months is not None:
+                # Functioning graft case
+                if demographics.lti:
+                    return 'GI_'
+                if demographics.new_enrollee:
+                    return 'GNE_'
+                    
+                # Community functioning graft
+                prefix = 'G'
+                prefix += 'F' if demographics.fbd else 'NP'
+                prefix += 'A' if demographics.age >= 65 else 'N'
+                return prefix + '_'
+                
+            # Dialysis case
+            return 'DNE_' if demographics.new_enrollee else 'DI_'
+            
+        # Transplant case
+        if demographics.graft_months in [1, 2, 3]:
+            return f'TRANSPLANT_KIDNEY_ONLY_{demographics.graft_months}M'
+            
+    elif 'RxHCC' in model_name:
+        if demographics.lti:
+            return 'Rx_NE_LTI_' if demographics.new_enrollee else 'Rx_CE_LTI_'
+            
+        if demographics.new_enrollee:
+            return 'Rx_NE_Lo_' if demographics.low_income else 'Rx_NE_NoLo_'
+            
+        # Community case
+        prefix = 'Rx_CE_'
+        prefix += 'Low' if demographics.low_income else 'NoLow'
+        prefix += 'Aged' if demographics.age >= 65 else 'NoAged'
+        return prefix + '_'
+        
+    # Default CMS-HCC Model
+    if demographics.lti:
+        return 'INS_'
+        
+    if demographics.new_enrollee:
+        return 'SNPNE_' if demographics.snp else 'NE_'
+        
+    # Community case
+    prefix = 'C'
+    prefix += 'F' if demographics.fbd else ('P' if demographics.pbd else 'N')
+    prefix += 'A' if demographics.age >= 65 else 'D'
+    return prefix + '_'
+
+
+def apply_coefficients(demographics: Demographics, 
+                      hcc_set: set[str], 
+                      interactions: dict,
+                      model_name: ModelName = "CMS-HCC Model V28",
+                      coefficients: Dict[Tuple[str, ModelName], float] = coefficients_default) -> dict:
+    """Apply risk adjustment coefficients to HCCs and interactions.
+
+    This function takes demographic information, HCC codes, and interaction variables and returns
+    a dictionary mapping each variable to its corresponding coefficient value based on the 
+    specified model.
+
+    Args:
+        demographics: Demographics object containing patient characteristics
+        hcc_set: Set of HCC codes present for the patient
+        interactions: Dictionary of interaction variables and their values (0 or 1)
+        model_name: Name of the risk adjustment model to use (default: "CMS-HCC Model V28")
+        coefficients: Dictionary mapping (variable, model) tuples to coefficient values
+            (default: coefficients_default)
+
+    Returns:
+        Dictionary mapping HCC codes and interaction variables to their coefficient values
+        for variables that are present (HCC in hcc_set or interaction value = 1)
+    """
+    # Get the coefficient prefix
+    prefix = get_coefficent_prefix(demographics, model_name)
+    
+    output = {}
+
+    demographics_key = (f"{prefix}{demographics.category}".lower(), model_name)
+    if demographics_key in coefficients:
+        output[demographics.category] = coefficients[demographics_key]
+
+    # Apply the coefficients
+    for hcc in hcc_set:
+        key = (f"{prefix}HCC{hcc}".lower(), model_name)
+
+        if key in coefficients:
+            value = coefficients[key]
+            output[hcc] = value
+
+    # Add interactions
+    for interaction_key, interaction_value in interactions.items():
+        if interaction_value < 1:
+            continue
+
+        key = (f"{prefix}{interaction_key}".lower(), model_name)
+        if key in coefficients:
+            value = coefficients[key]
+            output[interaction_key] = value
+
+    return output
+

hccinfhir/model_demographics.py

@@ -0,0 +1,191 @@
+from typing import Union
+from hccinfhir.datamodels import Demographics
+    
+def categorize_demographics(age: Union[int, float], 
+                       sex: str, 
+                       dual_elgbl_cd: str = None,
+                       orec: str = None, 
+                       crec: str = None,
+                       version: str = 'V2',
+                       new_enrollee: bool = False,
+                       snp: bool = False,
+                       low_income: bool = False,
+                       graft_months: int = None
+                       ) -> Demographics:
+    """
+    Categorize a beneficiary's demographics into risk adjustment categories.
+
+    This function takes demographic information about a beneficiary and returns a Demographics
+    object containing derived fields used in risk adjustment models.
+
+    Args:
+        age: Beneficiary age (integer or float, will be floored to integer)
+        sex: Beneficiary sex ('M'/'F' or '1'/'2')
+        dual_elgbl_cd: Dual eligibility code ('00'-'10')
+        orec: Original reason for entitlement code ('0'-'3')
+        crec: Current reason for entitlement code ('0'-'3') 
+        version: Version of categorization to use ('V2', 'V4', 'V6')
+        new_enrollee: Whether beneficiary is a new enrollee
+        snp: Whether beneficiary is in a Special Needs Plan
+
+    Returns:
+        Demographics object containing derived fields like age/sex category,
+        disability status, dual status flags, etc.
+
+    Raises:
+        ValueError: If age is negative or non-numeric, or if sex is invalid
+    """
+    
+    if not isinstance(age, (int, float)):
+        raise ValueError("Age must be a number")
+    
+    if age < 0:
+        raise ValueError("Age must be non-negative")
+        
+    # Convert to integer using floor
+    age = int(age)
+    non_aged = age <= 64
+
+    # Standardize sex input
+    if sex in ('M', '1'):
+        std_sex = '1'  # For V2/V4
+        v6_sex = 'M'   # For V6
+    elif sex in ('F', '2'):
+        std_sex = '2'  # For V2/V4
+        v6_sex = 'F'   # For V6
+    else:
+        raise ValueError("Sex must be 'M', 'F', '1', or '2'")
+    
+    # Determine if person is disabled or originally disabled
+    disabled = age < 65 and (orec is not None and orec != "0")
+    orig_disabled = (orec is not None and orec == '1') and not disabled
+
+    # Reference: https://resdac.org/cms-data/variables/medicare-medicaid-dual-eligibility-code-january 
+    # Full benefit dual codes
+    fbd_codes = {'02', '04', '08'}
+    
+    # Partial benefit dual codes
+    pbd_codes = {'01', '03', '05', '06'}
+    
+    is_fbd = dual_elgbl_cd in fbd_codes
+    is_pbd = dual_elgbl_cd in pbd_codes
+
+    esrd_orec = orec in {'2', '3', '6'}
+    esrd_crec = crec in {'2', '3'} if crec else False
+    esrd = esrd_orec or esrd_crec
+
+    result_dict = {
+        'version': version,
+        'non_aged': non_aged,
+        'orig_disabled': orig_disabled,
+        'disabled': disabled,
+        'age': age,
+        'sex': std_sex if version in ('V2', 'V4') else v6_sex,
+        'dual_elgbl_cd': dual_elgbl_cd,
+        'orec': orec,
+        'crec': crec,
+        'new_enrollee': new_enrollee,
+        'snp': snp,
+        'fbd': is_fbd,
+        'pbd': is_pbd,
+        'esrd': esrd,
+        'graft_months': graft_months,
+        'low_income': low_income
+    }
+
+    # V6 Logic (ACA Population)
+    if version == 'V6':
+        age_ranges = [
+            (0, 0, '0_0'),
+            (1, 1, '1_1'),
+            (2, 4, '2_4'),
+            (5, 9, '5_9'),
+            (10, 14, '10_14'),
+            (15, 20, '15_20'),
+            (21, 24, '21_24'),
+            (25, 29, '25_29'),
+            (30, 34, '30_34'),
+            (35, 39, '35_39'),
+            (40, 44, '40_44'),
+            (45, 49, '45_49'),
+            (50, 54, '50_54'),
+            (55, 59, '55_59'),
+            (60, float('inf'), '60_GT')
+        ]
+        
+        for low, high, label in age_ranges:
+            if low <= age <= high:
+                result_dict['category'] = f"{v6_sex}AGE_LAST_{label}"
+                return Demographics(**result_dict)
+    
+    # V2/V4 Logic (Medicare Population)
+    elif version in ('V2', 'V4'):
+        if orec is None:
+            raise ValueError("OREC is required for V2/V4 categorization")
+        
+        # New enrollee logic
+        if new_enrollee:
+            prefix = 'NEF' if std_sex == '2' else 'NEM'
+            
+            if age <= 34:
+                category = f'{prefix}0_34'
+            elif 34 < age <= 44:
+                category = f'{prefix}35_44'
+            elif 44 < age <= 54:
+                category = f'{prefix}45_54'
+            elif 54 < age <= 59:
+                category = f'{prefix}55_59'
+            elif (59 < age <= 63) or (age == 64 and orec != '0'):
+                category = f'{prefix}60_64'
+            elif (age == 64 and orec == '0') or age == 65:
+                category = f'{prefix}65'
+            elif age == 66:
+                category = f'{prefix}66'
+            elif age == 67:
+                category = f'{prefix}67'
+            elif age == 68:
+                category = f'{prefix}68'
+            elif age == 69:
+                category = f'{prefix}69'
+            elif 69 < age <= 74:
+                category = f'{prefix}70_74'
+            elif 74 < age <= 79:
+                category = f'{prefix}75_79'
+            elif 79 < age <= 84:
+                category = f'{prefix}80_84'
+            elif 84 < age <= 89:
+                category = f'{prefix}85_89'
+            elif 89 < age <= 94:
+                category = f'{prefix}90_94'
+            else:
+                category = f'{prefix}95_GT'
+        
+        else:
+            prefix = 'F' if std_sex == '2' else 'M'
+            age_ranges = [
+                (0, 34, '0_34'),
+                (34, 44, '35_44'),
+                (44, 54, '45_54'),
+                (54, 59, '55_59'),
+                (59, 64, '60_64'),
+                (64, 69, '65_69'),
+                (69, 74, '70_74'),
+                (74, 79, '75_79'),
+                (79, 84, '80_84'),
+                (84, 89, '85_89'),
+                (89, 94, '90_94'),
+                (94, float('inf'), '95_GT')
+            ]
+            
+            for low, high, suffix in age_ranges:
+                if low < age <= high:
+                    category = f'{prefix}{suffix}'
+                    break
+            else:
+                raise ValueError(f"Unable to categorize age: {age}")
+        
+        result_dict['category'] = category
+        return Demographics(**result_dict)
+    
+    else:
+        raise ValueError("Version must be 'V2', 'V4', or 'V6'")

hccinfhir/model_dx_to_cc.py

@@ -0,0 +1,54 @@
+from typing import List, Dict, Set, Tuple, Optional
+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 = load_dx_to_cc_mapping(mapping_file_default)
+
+def get_cc(
+    diagnosis_code: str,
+    model_name: ModelName = "CMS-HCC Model V28",
+    dx_to_cc_mapping: Dict[Tuple[str, ModelName], Set[str]] = dx_to_cc_default
+) -> Optional[Set[str]]:
+    """
+    Get CC for a single diagnosis code.
+
+    Args:
+        diagnosis_code: ICD-10 diagnosis code
+        model_name: HCC model name to use for mapping
+        dx_to_cc_mapping: Optional custom mapping dictionary
+
+    Returns:
+        CC code if found, None otherwise
+    """
+    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_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.
+    
+    Args:
+        diagnoses: List of ICD-10 diagnosis codes
+        model_name: HCC model name to use for mapping
+        dx_to_cc_mapping: Optional custom mapping dictionary
+        
+    Returns:
+        Dictionary mapping CCs to lists of diagnosis codes that map to them
+    """
+    cc_to_dx: Dict[str, Set[str]] = {}
+    
+    for dx in set(diagnoses):
+        dx = dx.upper().replace('.', '')
+        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:
+                    cc_to_dx[cc] = set()
+                cc_to_dx[cc].add(dx)
+                
+    return cc_to_dx