hccinfhir 0.2.0__tar.gz → 0.2.2__tar.gz

{hccinfhir-0.2.0 → hccinfhir-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: hccinfhir
-Version: 0.2.0
+Version: 0.2.2
 Summary: HCC Algorithm for FHIR Resources
 Project-URL: Homepage, https://github.com/mimilabs/hccinfhir
 Project-URL: Issues, https://github.com/mimilabs/hccinfhir/issues
@@ -10,6 +10,7 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Requires-Python: >=3.8
 Requires-Dist: pydantic>=2.10.3
+Requires-Dist: typing-extensions>=4.6.0
 Description-Content-Type: text/markdown
 
 # HCCInFHIR
@@ -62,6 +63,7 @@ print(f"HCCs: {result.hcc_list}")
   - [Demographic Prefix Override](#demographic-prefix-override)
   - [Custom File Path Resolution](#custom-file-path-resolution)
   - [Batch Processing](#batch-processing)
+  - [Large-Scale Processing with Databricks](#large-scale-processing-with-databricks)
   - [Converting to Dictionaries](#converting-to-dictionaries)
 - [Sample Data](#sample-data)
 - [Testing](#testing)
@@ -78,7 +80,7 @@ print(f"HCCs: {result.hcc_list}")
 - **Custom Data Files**: Full support for custom coefficients, mappings, and hierarchies
 - **Flexible File Resolution**: Absolute paths, relative paths, or bundled data files
 - **Type-Safe**: Built on Pydantic with full type hints
-- **Well-Tested**: 155 comprehensive tests covering all features
+- **Well-Tested**: 181 comprehensive tests covering all features
 
 ## 📊 Data Sources & Use Cases
 
@@ -834,6 +836,146 @@ with open("risk_scores.json", "w") as f:
     json.dump(results, f, indent=2)
 ```
 
+### Large-Scale Processing with Databricks
+
+For processing millions of beneficiaries, use PySpark's `pandas_udf` for distributed computation. The hccinfhir logic is well-suited for batch operations with clear, simple transformations.
+
+**Performance Benchmark**:
+
+![Databricks Performance Chart](hccinfhir_pandas_udf_performance_chart.png)
+
+*Tested with ACO data on Databricks Runtime 17.3 LTS, Worker: i3.4xlarge (122GB, 16 cores)*
+
+The chart shows execution time varies based on condition complexity - members with more diagnoses require additional internal processing loops. While the relationship isn't perfectly linear, **1 million members can be processed in under 2 minutes** with this configuration.
+
+```python
+from pyspark.sql import SparkSession
+from pyspark.sql.types import StructType, StructField, FloatType, ArrayType, StringType
+from pyspark.sql import functions as F
+from pyspark.sql.functions import pandas_udf
+import pandas as pd
+
+from hccinfhir import HCCInFHIR, Demographics
+
+# Define the return schema
+hcc_schema = StructType([
+    StructField("risk_score", FloatType(), True),
+    StructField("risk_score_demographics", FloatType(), True),
+    StructField("risk_score_chronic_only", FloatType(), True),
+    StructField("risk_score_hcc", FloatType(), True),
+    StructField("hcc_list", ArrayType(StringType()), True)
+])
+
+# Initialize processor (will be serialized to each executor)
+hcc_processor = HCCInFHIR(model_name="CMS-HCC Model V28")
+
+# Create the pandas UDF
+@pandas_udf(hcc_schema)
+def calculate_hcc(
+    age_series: pd.Series,
+    sex_series: pd.Series,
+    diagnosis_series: pd.Series
+) -> pd.DataFrame:
+    results = []
+
+    for age, sex, diagnosis_codes in zip(age_series, sex_series, diagnosis_series):
+        try:
+            demographics = Demographics(age=int(age), sex=sex)
+
+            # diagnosis_codes can be passed directly - accepts any iterable including numpy arrays
+            result = hcc_processor.calculate_from_diagnosis(diagnosis_codes, demographics)
+
+            results.append({
+                'risk_score': float(result.risk_score),
+                'risk_score_demographics': float(result.risk_score_demographics),
+                'risk_score_chronic_only': float(result.risk_score_chronic_only),
+                'risk_score_hcc': float(result.risk_score_hcc),
+                'hcc_list': result.hcc_list
+            })
+        except Exception as e:
+            # Log error and return nulls for failed rows
+            print(f"ERROR processing row: {e}")
+            results.append({
+                'risk_score': None,
+                'risk_score_demographics': None,
+                'risk_score_chronic_only': None,
+                'risk_score_hcc': None,
+                'hcc_list': None
+            })
+
+    return pd.DataFrame(results)
+
+# Apply the UDF to your DataFrame
+# Assumes df has columns: age, patient_gender, diagnosis_codes (array of strings)
+df = df.withColumn(
+    "hcc_results",
+    calculate_hcc(
+        F.col("age"),
+        F.col("patient_gender"),
+        F.col("diagnosis_codes")
+    )
+)
+
+# Expand the struct into separate columns
+df = df.select(
+    "*",
+    F.col("hcc_results.risk_score").alias("risk_score"),
+    F.col("hcc_results.risk_score_demographics").alias("risk_score_demographics"),
+    F.col("hcc_results.risk_score_chronic_only").alias("risk_score_chronic_only"),
+    F.col("hcc_results.risk_score_hcc").alias("risk_score_hcc"),
+    F.col("hcc_results.hcc_list").alias("hcc_list")
+).drop("hcc_results")
+```
+
+**Performance Tips**:
+- **Repartition** your DataFrame before applying the UDF to balance workload across executors
+- **Cache** the processor initialization by defining it at module level
+- **Batch size**: pandas_udf processes data in batches; Spark handles optimal batch sizing automatically
+- **Install hccinfhir** on all cluster nodes: `%pip install hccinfhir` in a notebook cell or add to cluster init script
+
+**Extended Schema with Demographics**:
+
+```python
+# Include additional demographic parameters
+@pandas_udf(hcc_schema)
+def calculate_hcc_full(
+    age_series: pd.Series,
+    sex_series: pd.Series,
+    dual_status_series: pd.Series,
+    diagnosis_series: pd.Series
+) -> pd.DataFrame:
+    results = []
+
+    for age, sex, dual_status, diagnosis_codes in zip(
+        age_series, sex_series, dual_status_series, diagnosis_series
+    ):
+        try:
+            demographics = Demographics(
+                age=int(age),
+                sex=sex,
+                dual_elgbl_cd=dual_status if dual_status else "00"
+            )
+            result = hcc_processor.calculate_from_diagnosis(diagnosis_codes, demographics)
+
+            results.append({
+                'risk_score': float(result.risk_score),
+                'risk_score_demographics': float(result.risk_score_demographics),
+                'risk_score_chronic_only': float(result.risk_score_chronic_only),
+                'risk_score_hcc': float(result.risk_score_hcc),
+                'hcc_list': result.hcc_list
+            })
+        except Exception as e:
+            results.append({
+                'risk_score': None,
+                'risk_score_demographics': None,
+                'risk_score_chronic_only': None,
+                'risk_score_hcc': None,
+                'hcc_list': None
+            })
+
+    return pd.DataFrame(results)
+```
+
 ### Converting to Dictionaries
 
 All Pydantic models support dictionary conversion for JSON serialization, database storage, or legacy code:
@@ -914,7 +1056,7 @@ hatch shell
 # Install in development mode
 pip install -e .
 
-# Run all tests (155 tests)
+# Run all tests (181 tests)
 pytest tests/
 
 # Run specific test file

{hccinfhir-0.2.0 → hccinfhir-0.2.2}/README.md

@@ -48,6 +48,7 @@ print(f"HCCs: {result.hcc_list}")
   - [Demographic Prefix Override](#demographic-prefix-override)
   - [Custom File Path Resolution](#custom-file-path-resolution)
   - [Batch Processing](#batch-processing)
+  - [Large-Scale Processing with Databricks](#large-scale-processing-with-databricks)
   - [Converting to Dictionaries](#converting-to-dictionaries)
 - [Sample Data](#sample-data)
 - [Testing](#testing)
@@ -64,7 +65,7 @@ print(f"HCCs: {result.hcc_list}")
 - **Custom Data Files**: Full support for custom coefficients, mappings, and hierarchies
 - **Flexible File Resolution**: Absolute paths, relative paths, or bundled data files
 - **Type-Safe**: Built on Pydantic with full type hints
-- **Well-Tested**: 155 comprehensive tests covering all features
+- **Well-Tested**: 181 comprehensive tests covering all features
 
 ## 📊 Data Sources & Use Cases
 
@@ -820,6 +821,146 @@ with open("risk_scores.json", "w") as f:
     json.dump(results, f, indent=2)
 ```
 
+### Large-Scale Processing with Databricks
+
+For processing millions of beneficiaries, use PySpark's `pandas_udf` for distributed computation. The hccinfhir logic is well-suited for batch operations with clear, simple transformations.
+
+**Performance Benchmark**:
+
+![Databricks Performance Chart](hccinfhir_pandas_udf_performance_chart.png)
+
+*Tested with ACO data on Databricks Runtime 17.3 LTS, Worker: i3.4xlarge (122GB, 16 cores)*
+
+The chart shows execution time varies based on condition complexity - members with more diagnoses require additional internal processing loops. While the relationship isn't perfectly linear, **1 million members can be processed in under 2 minutes** with this configuration.
+
+```python
+from pyspark.sql import SparkSession
+from pyspark.sql.types import StructType, StructField, FloatType, ArrayType, StringType
+from pyspark.sql import functions as F
+from pyspark.sql.functions import pandas_udf
+import pandas as pd
+
+from hccinfhir import HCCInFHIR, Demographics
+
+# Define the return schema
+hcc_schema = StructType([
+    StructField("risk_score", FloatType(), True),
+    StructField("risk_score_demographics", FloatType(), True),
+    StructField("risk_score_chronic_only", FloatType(), True),
+    StructField("risk_score_hcc", FloatType(), True),
+    StructField("hcc_list", ArrayType(StringType()), True)
+])
+
+# Initialize processor (will be serialized to each executor)
+hcc_processor = HCCInFHIR(model_name="CMS-HCC Model V28")
+
+# Create the pandas UDF
+@pandas_udf(hcc_schema)
+def calculate_hcc(
+    age_series: pd.Series,
+    sex_series: pd.Series,
+    diagnosis_series: pd.Series
+) -> pd.DataFrame:
+    results = []
+
+    for age, sex, diagnosis_codes in zip(age_series, sex_series, diagnosis_series):
+        try:
+            demographics = Demographics(age=int(age), sex=sex)
+
+            # diagnosis_codes can be passed directly - accepts any iterable including numpy arrays
+            result = hcc_processor.calculate_from_diagnosis(diagnosis_codes, demographics)
+
+            results.append({
+                'risk_score': float(result.risk_score),
+                'risk_score_demographics': float(result.risk_score_demographics),
+                'risk_score_chronic_only': float(result.risk_score_chronic_only),
+                'risk_score_hcc': float(result.risk_score_hcc),
+                'hcc_list': result.hcc_list
+            })
+        except Exception as e:
+            # Log error and return nulls for failed rows
+            print(f"ERROR processing row: {e}")
+            results.append({
+                'risk_score': None,
+                'risk_score_demographics': None,
+                'risk_score_chronic_only': None,
+                'risk_score_hcc': None,
+                'hcc_list': None
+            })
+
+    return pd.DataFrame(results)
+
+# Apply the UDF to your DataFrame
+# Assumes df has columns: age, patient_gender, diagnosis_codes (array of strings)
+df = df.withColumn(
+    "hcc_results",
+    calculate_hcc(
+        F.col("age"),
+        F.col("patient_gender"),
+        F.col("diagnosis_codes")
+    )
+)
+
+# Expand the struct into separate columns
+df = df.select(
+    "*",
+    F.col("hcc_results.risk_score").alias("risk_score"),
+    F.col("hcc_results.risk_score_demographics").alias("risk_score_demographics"),
+    F.col("hcc_results.risk_score_chronic_only").alias("risk_score_chronic_only"),
+    F.col("hcc_results.risk_score_hcc").alias("risk_score_hcc"),
+    F.col("hcc_results.hcc_list").alias("hcc_list")
+).drop("hcc_results")
+```
+
+**Performance Tips**:
+- **Repartition** your DataFrame before applying the UDF to balance workload across executors
+- **Cache** the processor initialization by defining it at module level
+- **Batch size**: pandas_udf processes data in batches; Spark handles optimal batch sizing automatically
+- **Install hccinfhir** on all cluster nodes: `%pip install hccinfhir` in a notebook cell or add to cluster init script
+
+**Extended Schema with Demographics**:
+
+```python
+# Include additional demographic parameters
+@pandas_udf(hcc_schema)
+def calculate_hcc_full(
+    age_series: pd.Series,
+    sex_series: pd.Series,
+    dual_status_series: pd.Series,
+    diagnosis_series: pd.Series
+) -> pd.DataFrame:
+    results = []
+
+    for age, sex, dual_status, diagnosis_codes in zip(
+        age_series, sex_series, dual_status_series, diagnosis_series
+    ):
+        try:
+            demographics = Demographics(
+                age=int(age),
+                sex=sex,
+                dual_elgbl_cd=dual_status if dual_status else "00"
+            )
+            result = hcc_processor.calculate_from_diagnosis(diagnosis_codes, demographics)
+
+            results.append({
+                'risk_score': float(result.risk_score),
+                'risk_score_demographics': float(result.risk_score_demographics),
+                'risk_score_chronic_only': float(result.risk_score_chronic_only),
+                'risk_score_hcc': float(result.risk_score_hcc),
+                'hcc_list': result.hcc_list
+            })
+        except Exception as e:
+            results.append({
+                'risk_score': None,
+                'risk_score_demographics': None,
+                'risk_score_chronic_only': None,
+                'risk_score_hcc': None,
+                'hcc_list': None
+            })
+
+    return pd.DataFrame(results)
+```
+
 ### Converting to Dictionaries
 
 All Pydantic models support dictionary conversion for JSON serialization, database storage, or legacy code:
@@ -900,7 +1041,7 @@ hatch shell
 # Install in development mode
 pip install -e .
 
-# Run all tests (155 tests)
+# Run all tests (181 tests)
 pytest tests/
 
 # Run specific test file

{hccinfhir-0.2.0 → hccinfhir-0.2.2}/hccinfhir/__init__.py

@@ -9,7 +9,7 @@ from .hccinfhir import HCCInFHIR
 from .extractor import extract_sld, extract_sld_list
 from .filter import apply_filter
 from .model_calculate import calculate_raf
-from .datamodels import Demographics, ServiceLevelData, RAFResult, ModelName
+from .datamodels import Demographics, ServiceLevelData, RAFResult, ModelName, HCCDetail
 
 # Sample data functions
 from .samples import (
@@ -37,6 +37,7 @@ __all__ = [
     "ServiceLevelData",
     "RAFResult",
     "ModelName",
+    "HCCDetail",
     
     # Sample data
     "SampleData",

hccinfhir-0.2.2/hccinfhir/constants.py

@@ -0,0 +1,240 @@
+"""
+CMS Risk Adjustment Domain Constants
+
+This module contains constants used across the HCC risk adjustment system,
+including dual eligibility codes, OREC/CREC values, and state-specific mappings.
+
+References:
+- CMS Rate Announcement and Call Letter
+- Medicare Advantage Enrollment and Disenrollment Guidance
+- X12 834 Implementation Guides
+"""
+
+from typing import Set, Dict
+
+# =============================================================================
+# DUAL ELIGIBILITY CODES
+# =============================================================================
+# CMS Dual Eligibility Status Codes (Medicare + Medicaid)
+# Used in coefficient prefix selection (CNA_, CFA_, CPA_, etc.)
+
+VALID_DUAL_CODES: Set[str] = {'00', '01', '02', '03', '04', '05', '06', '08'}
+
+# Non-Dual Eligible
+NON_DUAL_CODE: str = '00'
+
+# Full Benefit Dual Eligible (receive both Medicare and full Medicaid benefits)
+# Uses CFA_ (Community, Full Benefit Dual, Aged) or CFD_ (Disabled) prefixes
+FULL_BENEFIT_DUAL_CODES: Set[str] = {
+    '02',  # QMB Plus (Qualified Medicare Beneficiary Plus)
+    '04',  # SLMB Plus (Specified Low-Income Medicare Beneficiary Plus)
+    '08',  # Other Full Benefit Dual Eligible
+}
+
+# Partial Benefit Dual Eligible (Medicare + limited Medicaid)
+# Uses CPA_ (Community, Partial Benefit Dual, Aged) or CPD_ (Disabled) prefixes
+PARTIAL_BENEFIT_DUAL_CODES: Set[str] = {
+    '01',  # QMB Only
+    '03',  # SLMB Only
+    '05',  # QDWI (Qualified Disabled and Working Individual)
+    '06',  # QI (Qualifying Individual)
+}
+
+# =============================================================================
+# OREC - Original Reason for Entitlement Code
+# =============================================================================
+# Determines if beneficiary has ESRD and affects coefficient prefix selection
+
+VALID_OREC_VALUES: Set[str] = {'0', '1', '2', '3'}
+
+OREC_DESCRIPTIONS: Dict[str, str] = {
+    '0': 'Old Age and Survivors Insurance (OASI)',
+    '1': 'Disability Insurance Benefits (DIB)',
+    '2': 'ESRD - End-Stage Renal Disease',
+    '3': 'DIB and ESRD',
+}
+
+# OREC codes indicating ESRD status (per CMS documentation)
+OREC_ESRD_CODES: Set[str] = {'2', '3'}
+
+# =============================================================================
+# CREC - Current Reason for Entitlement Code
+# =============================================================================
+# Current entitlement status (may differ from OREC)
+
+VALID_CREC_VALUES: Set[str] = {'0', '1', '2', '3'}
+
+CREC_DESCRIPTIONS: Dict[str, str] = {
+    '0': 'Old Age and Survivors Insurance (OASI)',
+    '1': 'Disability Insurance Benefits (DIB)',
+    '2': 'ESRD - End-Stage Renal Disease',
+    '3': 'DIB and ESRD',
+}
+
+# CREC codes indicating ESRD status
+CREC_ESRD_CODES: Set[str] = {'2', '3'}
+
+# =============================================================================
+# COEFFICIENT PREFIX GROUPS
+# =============================================================================
+# Used for prefix_override logic in model_demographics.py
+
+# ESRD model prefixes
+ESRD_PREFIXES: Set[str] = {'DI_', 'DNE_', 'GI_', 'GNE_', 'GFPA_', 'GFPN_', 'GNPA_', 'GNPN_'}
+
+# CMS-HCC new enrollee prefixes
+NEW_ENROLLEE_PREFIXES: Set[str] = {'NE_', 'SNPNE_', 'DNE_', 'GNE_'}
+
+# CMS-HCC community prefixes
+COMMUNITY_PREFIXES: Set[str] = {'CNA_', 'CND_', 'CFA_', 'CFD_', 'CPA_', 'CPD_'}
+
+# Institutionalized prefixes
+INSTITUTIONAL_PREFIXES: Set[str] = {'INS_', 'GI_'}
+
+# Full Benefit Dual prefixes
+FULL_BENEFIT_DUAL_PREFIXES: Set[str] = {'CFA_', 'CFD_', 'GFPA_', 'GFPN_'}
+
+# Partial Benefit Dual prefixes
+PARTIAL_BENEFIT_DUAL_PREFIXES: Set[str] = {'CPA_', 'CPD_'}
+
+# Non-Dual prefixes
+NON_DUAL_PREFIXES: Set[str] = {'CNA_', 'CND_', 'GNPA_', 'GNPN_'}
+
+# =============================================================================
+# DEMOGRAPHIC CODES
+# =============================================================================
+
+VALID_SEX_CODES: Set[str] = {'M', 'F'}
+
+# X12 834 Gender Code mappings
+X12_SEX_CODE_MAPPING: Dict[str, str] = {
+    'M': 'M',
+    'F': 'F',
+    '1': 'M',  # X12 numeric code
+    '2': 'F',  # X12 numeric code
+}
+
+# =============================================================================
+# X12 834 MAINTENANCE TYPE CODES
+# =============================================================================
+# INS03 - Maintenance Type Code
+
+MAINTENANCE_TYPE_CHANGE: str = '001'
+MAINTENANCE_TYPE_ADD: str = '021'
+MAINTENANCE_TYPE_CANCEL: str = '024'
+MAINTENANCE_TYPE_REINSTATE: str = '025'
+
+MAINTENANCE_TYPE_DESCRIPTIONS: Dict[str, str] = {
+    '001': 'Change',
+    '021': 'Addition',
+    '024': 'Cancellation/Termination',
+    '025': 'Reinstatement',
+}
+
+# =============================================================================
+# STATE-SPECIFIC MAPPINGS
+# =============================================================================
+
+# -----------------------------------------------------------------------------
+# California DHCS Medi-Cal Aid Codes
+# -----------------------------------------------------------------------------
+# Maps California-specific aid codes to CMS dual eligibility codes
+# Source: California DHCS 834 Implementation Guide
+
+MEDI_CAL_AID_CODES: Dict[str, str] = {
+    # Full Benefit Dual (QMB Plus, SLMB Plus)
+    '4N': '02',  # QMB Plus - Aged
+    '4P': '02',  # QMB Plus - Disabled
+    '5B': '04',  # SLMB Plus - Aged
+    '5D': '04',  # SLMB Plus - Disabled
+
+    # Partial Benefit Dual (QMB Only, SLMB Only, QI)
+    '4M': '01',  # QMB Only - Aged
+    '4O': '01',  # QMB Only - Disabled
+    '5A': '03',  # SLMB Only - Aged
+    '5C': '03',  # SLMB Only - Disabled
+    '5E': '06',  # QI - Aged
+    '5F': '06',  # QI - Disabled
+}
+
+# -----------------------------------------------------------------------------
+# Medicare Status Code Mappings
+# -----------------------------------------------------------------------------
+# Maps Medicare status codes (from various sources) to CMS dual eligibility codes
+# Used in X12 834 REF*ABB segment and other payer files
+
+MEDICARE_STATUS_CODE_MAPPING: Dict[str, str] = {
+    # QMB - Qualified Medicare Beneficiary
+    'QMB': '01',         # QMB Only (Partial)
+    'QMBONLY': '01',
+    'QMBPLUS': '02',     # QMB Plus (Full Benefit)
+    'QMB+': '02',
+
+    # SLMB - Specified Low-Income Medicare Beneficiary
+    'SLMB': '03',        # SLMB Only (Partial)
+    'SLMBONLY': '03',
+    'SLMBPLUS': '04',    # SLMB Plus (Full Benefit)
+    'SLMB+': '04',
+
+    # Other dual eligibility programs
+    'QDWI': '05',        # Qualified Disabled and Working Individual
+    'QI': '06',          # Qualifying Individual
+    'QI1': '06',
+    'FBDE': '08',        # Full Benefit Dual Eligible (Other)
+    'OTHERFULL': '08',
+}
+
+# =============================================================================
+# HELPER FUNCTIONS
+# =============================================================================
+
+def is_full_benefit_dual(dual_code: str) -> bool:
+    """Check if dual eligibility code is Full Benefit Dual"""
+    return dual_code in FULL_BENEFIT_DUAL_CODES
+
+def is_partial_benefit_dual(dual_code: str) -> bool:
+    """Check if dual eligibility code is Partial Benefit Dual"""
+    return dual_code in PARTIAL_BENEFIT_DUAL_CODES
+
+def is_esrd_by_orec(orec: str) -> bool:
+    """Check if OREC indicates ESRD status"""
+    return orec in OREC_ESRD_CODES
+
+def is_esrd_by_crec(crec: str) -> bool:
+    """Check if CREC indicates ESRD status"""
+    return crec in CREC_ESRD_CODES
+
+def normalize_medicare_status_code(status: str) -> str:
+    """Normalize Medicare status code (uppercase, no spaces/hyphens)"""
+    if not status:
+        return ''
+    return status.upper().replace(' ', '').replace('-', '')
+
+def map_medicare_status_to_dual_code(status: str) -> str:
+    """Map Medicare status code to dual eligibility code
+
+    Args:
+        status: Medicare status code (e.g., 'QMB Plus', 'SLMB', 'QI')
+
+    Returns:
+        Dual eligibility code ('01'-'08') or '00' if not found
+    """
+    if not status:
+        return NON_DUAL_CODE
+
+    normalized = normalize_medicare_status_code(status)
+    return MEDICARE_STATUS_CODE_MAPPING.get(normalized, NON_DUAL_CODE)
+
+def map_aid_code_to_dual_status(aid_code: str) -> str:
+    """Map California Medi-Cal aid code to dual eligibility code
+
+    Args:
+        aid_code: California aid code (e.g., '4N', '5B')
+
+    Returns:
+        Dual eligibility code ('01'-'08') or '00' if not found
+    """
+    if not aid_code:
+        return NON_DUAL_CODE
+
+    return MEDI_CAL_AID_CODES.get(aid_code, NON_DUAL_CODE)