### Development Installation

Source: https://pypi.org/project/hccinfhir/0.3.2

Clone the repository and install the library in editable mode for development.

```bash
git clone https://github.com/yourusername/hccinfhir.git
cd hccinfhir
pip install -e .

```

--------------------------------

### Basic Installation

Source: https://pypi.org/project/hccinfhir/0.3.2

Install the hccinfhir library using pip.

```bash
pip install hccinfhir

```

--------------------------------

### Install hccinfhir

Source: https://pypi.org/project/hccinfhir/0.3.2

Install the hccinfhir library using pip. This command installs version 0.3.2.

```bash
pip install hccinfhir==0.3.2
```

--------------------------------

### Setting up and Running Tests with pytest

Source: https://pypi.org/project/hccinfhir/0.3.2

Commands to activate a virtual environment, install the package in development mode, and run tests using pytest. Includes options for running specific files or with code coverage.

```bash
# Activate virtual environment
hatch shell

# Install in development mode
pip install -e .

# Run all tests (238 tests)
pytest tests/

# Run specific test file
pytest tests/test_model_calculate.py -v

# Run with coverage
pytest tests/ --cov=hccinfhir --cov-report=html

```

--------------------------------

### Install hccinfhir

Source: https://pypi.org/project/hccinfhir

Use pip to install the hccinfhir library. This is the first step before using the library in your Python project.

```bash
pip install hccinfhir
```

--------------------------------

### Run Tests for hccinfhir Project

Source: https://pypi.org/project/hccinfhir

Commands to set up the development environment, install the library in editable mode, and execute tests using pytest. Includes options for running all tests, specific files, or with code coverage.

```bash
# Activate virtual environment
hatch shell

# Install in development mode
pip install -e .

# Run all tests (238 tests)
pytest tests/

# Run specific test file
pytest tests/test_model_calculate.py -v

# Run with coverage
pytest tests/ --cov=hccinfhir --cov-report=html
```

--------------------------------

### Initialize HCCInFHIR with Mixed File Paths

Source: https://pypi.org/project/hccinfhir/0.3.2

Configure the processor to use a mix of bundled default files and custom files specified by relative or absolute paths.

```python
# Option 4: Mix bundled and custom files
processor = HCCInFHIR(
    model_name="CMS-HCC Model V28",
    dx_cc_mapping_filename="ra_dx_to_cc_2026.csv",  # Bundled default
    coefficients_filename="custom_coefficients.csv"  # Custom from current dir
)
```

--------------------------------

### Initialize HCCInFHIR with Bundled Data

Source: https://pypi.org/project/hccinfhir/0.3.2

Use this when you want to leverage the default CMS reference files included with the package. No additional file configuration is needed.

```python
from hccinfhir import HCCInFHIR

# Option 1: Use bundled data (default - no setup needed)
processor = HCCInFHIR(
    model_name="CMS-HCC Model V28",
    dx_cc_mapping_filename="ra_dx_to_cc_2026.csv"  # ✅ Loads from package
)
```

--------------------------------

### API Endpoint for Risk Calculation with FastAPI

Source: https://pypi.org/project/hccinfhir

An example FastAPI endpoint that accepts diagnosis codes and demographics, calculates the risk score using HCCInFHIR, and returns the result in JSON format.

```python
from fastapi import FastAPI
from hccinfhir import HCCInFHIR, Demographics

processor = HCCInFHIR(model_name="CMS-HCC Model V28")
app = FastAPI()

@app.post("/calculate")
def calculate_risk(diagnosis_codes: list, demographics: dict):
    demo = Demographics(**demographics)
    result = processor.calculate_from_diagnosis(diagnosis_codes, demo)
    return result.model_dump(mode='json')  # Automatic JSON serialization

```

--------------------------------

### Calculate HCC Risk Scores with Pandas UDF

Source: https://pypi.org/project/hccinfhir/0.3.2

Defines a pandas UDF to calculate HCC risk scores for large datasets using PySpark. Ensure 'hccinfhir' is installed on all cluster nodes.

```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")

```

--------------------------------

### Initialize HCCInFHIR for Production with Centralized Data

Source: https://pypi.org/project/hccinfhir/0.3.2

Configure the processor for production by specifying absolute paths to all necessary data files located in a centralized network location.

```python
# All custom files in shared network location
data_path = "/mnt/shared/cms_data/2026"
processor = HCCInFHIR(
    model_name="CMS-HCC Model V28",
    proc_filtering_filename=f"{data_path}/cpt_hcpcs.csv",
    dx_cc_mapping_filename=f"{data_path}/dx_to_cc.csv",
    hierarchies_filename=f"{data_path}/hierarchies.csv",
    is_chronic_filename=f"{data_path}/chronic_flags.csv",
    coefficients_filename=f"{data_path}/coefficients.csv"
)
```

--------------------------------

### Initialize HCCInFHIR for Development

Source: https://pypi.org/project/hccinfhir/0.3.2

A simplified initialization for development environments, relying on bundled data files for testing purposes.

```python
# Use bundled files for testing
processor = HCCInFHIR(model_name="CMS-HCC Model V28")
```

--------------------------------

### FastAPI Endpoint for Risk Calculation

Source: https://pypi.org/project/hccinfhir/0.3.2

An example of a FastAPI endpoint that accepts diagnosis codes and demographics, calculates the HCC risk score using the HCCInFHIR processor, and returns the result in a JSON-safe format. Ensures automatic JSON serialization for API responses.

```python
from fastapi import FastAPI
from hccinfhir import HCCInFHIR, Demographics

processor = HCCInFHIR(model_name="CMS-HCC Model V28")
app = FastAPI()

@app.post("/calculate")
def calculate_risk(diagnosis_codes: list, demographics: dict):
    demo = Demographics(**demographics)
    result = processor.calculate_from_diagnosis(diagnosis_codes, demo)
    return result.model_dump(mode='json')
```

--------------------------------

### Handle FileNotFoundError during Initialization

Source: https://pypi.org/project/hccinfhir/0.3.2

Demonstrates how to catch a `FileNotFoundError` if a specified data file does not exist, and shows the locations checked by the library.

```python
from hccinfhir import HCCInFHIR

try:
    processor = HCCInFHIR(
        model_name="CMS-HCC Model V28",
        dx_cc_mapping_filename="nonexistent.csv"
    )
except FileNotFoundError as e:
    print(f"File not found: {e}")
    # Error shows all locations checked:
    # - Current directory: /path/to/cwd
    # - Package data: hccinfhir.data
```

--------------------------------

### Initialize HCCInFHIR Processor

Source: https://pypi.org/project/hccinfhir/0.3.2

Instantiate the main HCCInFHIR processor class. Configure with various filenames for data mappings and model parameters.

```python
HCCInFHIR(
    filter_claims=True,
    model_name="CMS-HCC Model V28",
    proc_filtering_filename="ra_eligible_cpt_hcpcs_2026.csv",
    dx_cc_mapping_filename="ra_dx_to_cc_2026.csv",
    hierarchies_filename="ra_hierarchies_2026.csv",
    is_chronic_filename="hcc_is_chronic.csv",
    coefficients_filename="ra_coefficients_2026.csv"
)
```

--------------------------------

### Initialize HCCInFHIR Processor

Source: https://pypi.org/project/hccinfhir

Instantiate the main HCCInFHIR processor class. Customize with various filenames for data mappings and coefficients.

```python
HCCInFHIR(
    filter_claims: bool = True,
    model_name: ModelName = "CMS-HCC Model V28",
    proc_filtering_filename: str = "ra_eligible_cpt_hcpcs_2026.csv",
    dx_cc_mapping_filename: str = "ra_dx_to_cc_2026.csv",
    hierarchies_filename: str = "ra_hierarchies_2026.csv",
    is_chronic_filename: str = "hcc_is_chronic.csv",
    coefficients_filename: str = "ra_coefficients_2026.csv"
)

```

--------------------------------

### Initialize HCCInFHIR with Relative Path

Source: https://pypi.org/project/hccinfhir/0.3.2

Specify a data file using a path relative to the current working directory. Ensure the file exists at the specified location.

```python
# Option 2: Relative path from current directory
# Assumes: ./custom_data/my_dx_mapping.csv exists
processor = HCCInFHIR(
    model_name="CMS-HCC Model V28",
    dx_cc_mapping_filename="custom_data/my_dx_mapping.csv"  # ✅ ./custom_data/
)
```

--------------------------------

### Initialize HCCInFHIR with Absolute Path

Source: https://pypi.org/project/hccinfhir/0.3.2

Provide an absolute path for data files, suitable for production environments where files are stored in a fixed, known location.

```python
# Option 3: Absolute path (production deployments)
processor = HCCInFHIR(
    model_name="CMS-HCC Model V28",
    dx_cc_mapping_filename="/var/data/cms/dx_mapping_2026.csv"  # ✅ Absolute
)
```

--------------------------------

### Initialize HCCInFHIR with Custom Data Files

Source: https://pypi.org/project/hccinfhir/0.3.2

Instantiate the HCCInFHIR processor, overriding default data files with custom CSV files for procedure filtering, diagnosis mapping, hierarchies, chronic condition flags, and RAF coefficients. Supports absolute, relative, or bundled filenames.

```python
processor = HCCInFHIR(
    model_name="CMS-HCC Model V28",
    filter_claims=True,

    # All files support absolute paths, relative paths, or bundled filenames
    # See "Custom File Path Resolution" in Advanced Features for details

    # 1. CPT/HCPCS Procedure Codes (for CMS filtering)
    proc_filtering_filename="ra_eligible_cpt_hcpcs_2026.csv",

    # 2. Diagnosis to HCC Mapping (ICD-10 → HCC)
    dx_cc_mapping_filename="ra_dx_to_cc_2026.csv",

    # 3. HCC Hierarchies (parent HCCs suppress child HCCs)
    hierarchies_filename="ra_hierarchies_2026.csv",

    # 4. Chronic Condition Flags
    is_chronic_filename="hcc_is_chronic.csv",

    # 5. RAF Coefficients (demographic + HCC + interaction coefficients)
    coefficients_filename="ra_coefficients_2026.csv"
)

```

--------------------------------

### HCCInFHIR Class Initialization

Source: https://pypi.org/project/hccinfhir/0.3.2

Initializes the HCCInFHIR processor with various configuration options.

```APIDOC
## HCCInFHIR Initialization

### Description
Initializes the main processor class for HCC risk adjustment calculations. Allows configuration of filtering, model name, and various data file paths.

### Parameters
- **filter_claims** (bool) - Optional - Whether to filter claims.
- **model_name** (ModelName) - Optional - The HCC model to use (default: "CMS-HCC Model V28").
- **proc_filtering_filename** (str) - Optional - Filename for procedure filtering.
- **dx_cc_mapping_filename** (str) - Optional - Filename for diagnosis to condition category mapping.
- **hierarchies_filename** (str) - Optional - Filename for hierarchy data.
- **is_chronic_filename** (str) - Optional - Filename for chronic condition data.
- **coefficients_filename** (str) - Optional - Filename for coefficient data.
```

--------------------------------

### HCCEngine Initialization and Risk Score Calculation (hccpy)

Source: https://pypi.org/project/hccinfhir/0.3.2

Demonstrates how to initialize HCCEngine and calculate risk scores and HCC lists using diagnosis codes in hccpy.

```python
from hccpy.hcc import HCCEngine

he = HCCEngine("28")
rp = he.profile(["E1169", "I5030", "I509", "I211", "I209", "R05"], age=70, sex="M")
print(rp["risk_score"])
print(rp["hcc_lst"])

```

--------------------------------

### HCCInFHIR Initialization

Source: https://pypi.org/project/hccinfhir

Initializes the HCCInFHIR processor with various configuration options. Users can specify filtering behavior, model names, and filenames for mapping and coefficient data.

```APIDOC
## HCCInFHIR Initialization

### Description
Initializes the HCCInFHIR processor with various configuration options. Users can specify filtering behavior, model names, and filenames for mapping and coefficient data.

### Parameters
* **filter_claims** (bool) - Optional - Whether to filter claims.
* **model_name** (ModelName) - Optional - The HCC model to use (default: "CMS-HCC Model V28").
* **proc_filtering_filename** (str) - Optional - Filename for procedure filtering data.
* **dx_cc_mapping_filename** (str) - Optional - Filename for diagnosis to CC mapping data.
* **hierarchies_filename** (str) - Optional - Filename for hierarchy data.
* **is_chronic_filename** (str) - Optional - Filename for chronic condition data.
* **coefficients_filename** (str) - Optional - Filename for coefficient data.
```

--------------------------------

### Initialize HCCInFHIR with Custom Coefficients

Source: https://pypi.org/project/hccinfhir/0.3.2

Customize the risk score calculation by providing your own coefficients file, while using standard mappings from the package.

```python
# Keep standard mappings, customize coefficients
# File: ./research/adjusted_coefficients.csv
processor = HCCInFHIR(
    model_name="CMS-HCC Model V28",
    coefficients_filename="research/adjusted_coefficients.csv"
)
```

--------------------------------

### Initialize HCCInFHIR in Docker with Mounted Volume

Source: https://pypi.org/project/hccinfhir/0.3.2

Configure the processor when running in a Docker container, specifying data file paths that correspond to a mounted volume.

```python
# Files mounted at /app/data
processor = HCCInFHIR(
    model_name="CMS-HCC Model V28",
    dx_cc_mapping_filename="/app/data/dx_to_cc_custom.csv",
    coefficients_filename="/app/data/coefficients_custom.csv"
    # Other files use bundled defaults
)
```

--------------------------------

### Import Utility Functions for Samples and Extraction

Source: https://pypi.org/project/hccinfhir/0.3.2

Import functions for retrieving sample FHIR EOBs, 837 claims, 834 enrollments, and for extracting service-level data.

```python
from hccinfhir import (
    get_eob_sample,
    get_837_sample,
    get_834_sample,
    get_eob_sample_list,
    get_837_sample_list,
    list_available_samples,
)

from hccinfhir.extractor import (
    extract_sld,
    extract_sld_list,
)
```

--------------------------------

### HCCInFHIR Initialization and Risk Score Calculation

Source: https://pypi.org/project/hccinfhir/0.3.2

Shows how to initialize HCCInFHIR and calculate risk scores and HCC lists using diagnosis codes.

```python
from hccinfhir import HCCInFHIR

processor = HCCInFHIR(model_name="CMS-HCC Model V28")
result = processor.calculate_from_diagnosis(["E1169", "I5030", "I509", "I211", "I209", "R05"], age=70, sex="M")
print(result.risk_score)
print(result.hcc_list)

```

--------------------------------

### Passing Demographics to calculate_from_diagnosis

Source: https://pypi.org/project/hccinfhir/0.3.2

Demonstrates equivalent ways to pass beneficiary demographics to the `calculate_from_diagnosis` method. This includes using keyword arguments, a dictionary, or a Demographics object.

```python
from hccinfhir import Demographics

# Keyword arguments (simplest)
result = processor.calculate_from_diagnosis(["E11.9"], age=75, sex="F")

# Dictionary
result = processor.calculate_from_diagnosis(["E11.9"], {"age": 75, "sex": "F"})

# Demographics object (full control)
result = processor.calculate_from_diagnosis(["E11.9"], Demographics(age=75, sex="F"))

```

--------------------------------

### Batch Process Beneficiaries and Calculate Risk Scores

Source: https://pypi.org/project/hccinfhir/0.3.2

Process a list of beneficiaries, calculating their risk scores and HCCs using the `calculate_from_diagnosis` method. Results are then exported to a JSON file.

```python
from hccinfhir import HCCInFHIR, Demographics

processor = HCCInFHIR(model_name="CMS-HCC Model V28")

# Process multiple beneficiaries
beneficiaries = [
    {"id": "001", "age": 67, "sex": "F", "dual": "00", "dx": ["E11.9", "I10"]},
    {"id": "002", "age": 45, "sex": "M", "dual": "02", "dx": ["N18.4", "F32.9"]},
    {"id": "003", "age": 78, "sex": "F", "dual": "01", "dx": ["F03.90", "I48.91"]},
]

results = []
for ben in beneficiaries:
    demographics = Demographics(
        age=ben["age"],
        sex=ben["sex"],
        dual_elgbl_cd=ben["dual"]
    )
    result = processor.calculate_from_diagnosis(ben["dx"], demographics)
    results.append({
        "beneficiary_id": ben["id"],
        "risk_score": result.risk_score,
        "risk_score_payment": result.risk_score_payment,
        "hcc_list": result.hcc_list
    })

# Export results
import json
with open("risk_scores.json", "w") as f:
    json.dump(results, f, indent=2)
```

--------------------------------

### Import Utility Functions for Data Handling

Source: https://pypi.org/project/hccinfhir

Import various utility functions for retrieving sample data, listing available samples, and extracting data from FHIR resources.

```python
from hccinfhir import (
    get_eob_sample,
    get_837_sample,
    get_834_sample,
    get_eob_sample_list,
    get_837_sample_list,
    list_available_samples,
)

from hccinfhir.extractor import (
    extract_sld,
    extract_sld_list,
)

from hccinfhir.extractor_834 import (
    extract_enrollment_834,
    enrollment_to_demographics,
    is_losing_medicaid,
    medicaid_status_summary,
)

from hccinfhir.filter import apply_filter
from hccinfhir.model_calculate import calculate_raf

```

--------------------------------

### Import Filtering and Direct Calculation Functions

Source: https://pypi.org/project/hccinfhir/0.3.2

Import the apply_filter function for CMS filtering and calculate_raf for direct risk adjustment score calculation.

```python
from hccinfhir.filter import apply_filter
from hccinfhir.model_calculate import calculate_raf
```

--------------------------------

### Initialize Demographics Object

Source: https://pypi.org/project/hccinfhir/0.3.2

Create a Demographics object with required and optional fields for beneficiary information. Fields like 'esrd' and 'fbd' can be auto-calculated or overridden.

```python
from hccinfhir import Demographics

demographics = Demographics(
    # Required fields
    age=67,                    # Age in years
    sex="F",                   # "M" or "F" (also accepts "1" or "2")

    # Dual eligibility (critical for payment accuracy)
    dual_elgbl_cd="00",        # "00"=Non-dual, "01"=Partial, "02"=Full
                               # "03"=Partial, "04"=Full, "05"=QDWI
                               # "06"=QI, "08"=Other full benefit dual

    # Medicare entitlement
    orec="0",                  # Original reason for entitlement
                               # "0"=Old age, "1"=Disability, "2"=ESRD, "3"=Both
    crec="0",                  # Current reason for entitlement

    # Status flags
    orig_disabled=False,       # Original disability (affects category)
    new_enrollee=False,        # New to Medicare (<12 months)
    esrd=False,                # End-Stage Renal Disease (auto-detected from orec/crec)

    # Optional fields
    snp=False,                 # Special Needs Plan
    low_income=False,          # Low-income subsidy (Part D)
    lti=False,                 # Long-term institutionalized
    graft_months=None,         # Months since kidney transplant (ESRD models)
    fbd=False,                 # Full benefit dual (auto-set from dual_elgbl_cd)
    pbd=False,                 # Partial benefit dual (auto-set)

    # Auto-calculated (can override)
    category="CNA"             # Beneficiary category (auto-calculated if omitted)
)

```

--------------------------------

### HCCInFHIR.run

Source: https://pypi.org/project/hccinfhir

Processes a list of FHIR ExplanationOfBenefit resources to calculate risk adjustment scores. Allows for optional overrides and adjustments.

```APIDOC
## HCCInFHIR.run

### Description
Processes a list of FHIR ExplanationOfBenefit resources to calculate risk adjustment scores. Allows for optional overrides and adjustments.

### Parameters
* **eob_list** (List[ExplanationOfBenefit]) - Required - A list of FHIR ExplanationOfBenefit resources.
* **demographics** (Demographics) - Required - Patient demographic information.
* **prefix_override** (Optional[str]) - Optional - Override for resource prefixes.
* **maci** (float) - Optional - MACI adjustment factor.
* **norm_factor** (float) - Optional - Normalization factor.
* **frailty_score** (float) - Optional - Frailty score adjustment.
```

--------------------------------

### Generate Sample Healthcare Data with hccinfhir

Source: https://pypi.org/project/hccinfhir

Use hccinfhir functions to retrieve sample data for EOB, 837 claims, 834 enrollment, and 820 remittance. The `list_available_samples` function can provide information on available cases.

```python
from hccinfhir import (
    get_eob_sample, get_eob_sample_list,
    get_837_sample, get_837_sample_list,
    get_834_sample,
    get_820_sample,
    list_available_samples
)

# FHIR EOB samples (3 individual + 200 batch)
eob = get_eob_sample(1)           # cases 1-3
eob_list = get_eob_sample_list(limit=50)
result = processor.run([eob], demographics)  # processor.run() expects a list

# X12 837 samples (13 scenarios)
claim = get_837_sample(0)          # cases 0-12
claims = get_837_sample_list([0, 1, 2])

# X12 834 enrollment samples (CA DHCS dual eligibility)
enrollment_834 = get_834_sample(1)  # case 1

# X12 820 payment remittance samples (5 CA DHCS PACE scenarios, PHI masked)
remittance = get_820_sample(1)     # cases 1-5; case 2 has ADX adjustments

# List all available samples
info = list_available_samples()
print(info['820_case_numbers'])    # [1, 2, 3, 4, 5]
```

--------------------------------

### Verify Dual Eligibility Rates in 820 vs 834 Data

Source: https://pypi.org/project/hccinfhir

Cross-references the `aid_code` from an 820 remittance with the `dual_elgbl_cd` from an 834 enrollment file to detect mismatches in dual eligibility payment rates. Requires prior extraction of 834 data.

```python
from hccinfhir.extractor_834 import extract_enrollment_834
from hccinfhir import get_834_sample

dual_map = {e.member_id: e.dual_elgbl_cd
            for e in extract_enrollment_834(get_834_sample(1))}
DUAL_AID_CODES = {"1H", "60", "10", "16", "17", "6H", "20"}

for member in payment.members:
    dual_cd = dual_map.get(member.member_id)
    if dual_cd is None:
        continue
    for entry in member.remittance_entries:
        paid_as_dual = entry.aid_code in DUAL_AID_CODES
        enrolled_as_dual = dual_cd not in ("00", "NA", None)
        if paid_as_dual != enrolled_as_dual:
            print(f"Rate mismatch {member.member_id}: "
                  f"paid as {'dual' if paid_as_dual else 'non-dual'} "
                  f"but enrolled dual_elgbl_cd={dual_cd}")
```

--------------------------------

### Convert Pydantic Models to Dictionaries and JSON

Source: https://pypi.org/project/hccinfhir/0.3.2

Demonstrates various methods for converting Pydantic models to dictionaries and JSON strings, including full conversion, partial conversion (include/exclude fields), and JSON-safe formats. Useful for serialization and API responses.

```python
from hccinfhir import HCCInFHIR, Demographics

processor = HCCInFHIR(model_name="CMS-HCC Model V28")
demographics = Demographics(age=67, sex="F")
result = processor.calculate_from_diagnosis(["E11.9"], demographics)

# Convert to dictionary
result_dict = result.model_dump()
print(result_dict["risk_score"])

# JSON-safe conversion
result_json = result.model_dump(mode='json')

# Partial conversion
summary = result.model_dump(include={"risk_score", "hcc_list", "model_name"})

# Exclude large nested data
compact = result.model_dump(exclude={"service_level_data"})

# Convert to JSON string
json_string = result.model_dump_json()
```

--------------------------------

### Process Service Data with HCCInFHIR

Source: https://pypi.org/project/hccinfhir/0.3.2

Use the run_from_service_data method to process service-level data. Similar to processing EOBs, it accepts demographics and adjustment parameters.

```python
run_from_service_data(service_data, demographics, prefix_override=None, maci=0.0, norm_factor=1.0, frailty_score=0.0)
```

--------------------------------

### Process X12 834 Enrollment Data

Source: https://pypi.org/project/hccinfhir/0.3.2

This snippet demonstrates how to parse an X12 834 enrollment file, iterate through member enrollments, and extract key demographic and dual eligibility information. It also checks for Medicaid coverage loss and summarizes Medicaid status.

```python
from hccinfhir import HCCInFHIR, Demographics
from hccinfhir.extractor_834 import (
    extract_enrollment_834,
    enrollment_to_demographics,
    is_losing_medicaid,
    medicaid_status_summary
)

# Step 1: Parse X12 834 enrollment file
with open("enrollment_834.txt", "r") as f:
    x12_834_data = f.read()

enrollments = extract_enrollment_834(x12_834_data)

# Step 2: Process each member
processor = HCCInFHIR(model_name="CMS-HCC Model V28")

for enrollment in enrollments:
    # Convert enrollment to Demographics for RAF calculation
    demographics = enrollment_to_demographics(enrollment)

    print(f"\n=== Member: {enrollment.member_id} ===")
    print(f"MBI: {enrollment.mbi}")
    print(f"Medicaid ID: {enrollment.medicaid_id}")
    print(f"Dual Status: {enrollment.dual_elgbl_cd}")
    print(f"Full Benefit Dual: {enrollment.is_full_benefit_dual}")
    print(f"Partial Benefit Dual: {enrollment.is_partial_benefit_dual}")

    # Step 3: Check for Medicaid coverage loss (critical for RAF projections)
    if is_losing_medicaid(enrollment, within_days=90):
        print(f"⚠️  ALERT: Member losing Medicaid coverage!")
        print(f"   Coverage ends: {enrollment.coverage_end_date}")
        print(f"   Expected RAF impact: -30% to -50%")

    # Step 4: Get comprehensive Medicaid status
    status = medicaid_status_summary(enrollment)
    print(f"\nMedicaid Status Summary:")
    print(f"  Has Medicare: {status['has_medicare']}")
    print(f"  Has Medicaid: {status['has_medicaid']}")
    print(f"  Dual Status Code: {status['dual_status']}")
    print(f"  Full Benefit Dual: {status['is_full_benefit_dual']}")
    print(f"  Partial Benefit Dual: {status['is_partial_benefit_dual']}")
    print(f"  Coverage End: {status['coverage_end_date']}")

    # Step 5: Calculate RAF with accurate dual status
    diagnosis_codes = ["E11.9", "I10", "N18.3"]  # From claims
    result = processor.calculate_from_diagnosis(diagnosis_codes, demographics)
    print(f"\nRAF Score: {result.risk_score:.3f}")

```

--------------------------------

### Accessing Sample Healthcare Data with hccinfhir

Source: https://pypi.org/project/hccinfhir/0.3.2

Use these functions to retrieve sample data for EOB, 837, 834, and 820 formats. The `list_available_samples` function can show available sample case numbers.

```python
from hccinfhir import (
    get_eob_sample, get_eob_sample_list,
    get_837_sample, get_837_sample_list,
    get_834_sample,
    get_820_sample,
    list_available_samples
)

# FHIR EOB samples (3 individual + 200 batch)
eob = get_eob_sample(1)           # cases 1-3
eob_list = get_eob_sample_list(limit=50)
result = processor.run([eob], demographics)  # processor.run() expects a list

# X12 837 samples (13 scenarios)
claim = get_837_sample(0)          # cases 0-12
claims = get_837_sample_list([0, 1, 2])

# X12 834 enrollment samples (CA DHCS dual eligibility)
enrollment_834 = get_834_sample(1)  # case 1

# X12 820 payment remittance samples (5 CA DHCS PACE scenarios, PHI masked)
remittance = get_820_sample(1)     # cases 1-5; case 2 has ADX adjustments

# List all available samples
info = list_available_samples()
print(info['820_case_numbers'])    # [1, 2, 3, 4, 5]

```

--------------------------------

### Custom Data File: RAF Coefficients

Source: https://pypi.org/project/hccinfhir/0.3.2

Format for the custom RAF coefficients file. Requires 'coefficient', 'value', 'model_domain', and 'model_version' columns.

```csv
coefficient,value,model_domain,model_version
cna_f70_74,0.395,CMS-HCC,V28
cna_hcc19,0.302,CMS-HCC,V28

```

--------------------------------

### Verify Dual Eligibility Rates in 820 vs 834

Source: https://pypi.org/project/hccinfhir/0.3.2

Cross-references the aid code in the 820 remittance with the dual eligibility code from an 834 enrollment file to detect rate mismatches.

```python
from hccinfhir.extractor_834 import extract_enrollment_834
from hccinfhir import get_834_sample

dual_map = {e.member_id: e.dual_elgbl_cd
            for e in extract_enrollment_834(get_834_sample(1))}
DUAL_AID_CODES = {"1H", "60", "10", "16", "17", "6H", "20"}

for member in payment.members:
    dual_cd = dual_map.get(member.member_id)
    if dual_cd is None:
        continue
    for entry in member.remittance_entries:
        paid_as_dual = entry.aid_code in DUAL_AID_CODES
        enrolled_as_dual = dual_cd not in ("00", "NA", None)
        if paid_as_dual != enrolled_as_dual:
            print(f"Rate mismatch {member.member_id}: "
                  f"paid as {'dual' if paid_as_dual else 'non-dual'} "
                  f"but enrolled dual_elgbl_cd={dual_cd}")

```

--------------------------------

### Process FHIR EOBs with HCCInFHIR

Source: https://pypi.org/project/hccinfhir/0.3.2

Use the run method of the HCCInFHIR class to process a list of FHIR ExplanationOfBenefit resources. Optional parameters allow for overrides and adjustments.

```python
run(eob_list, demographics, prefix_override=None, maci=0.0, norm_factor=1.0, frailty_score=0.0)
```

--------------------------------

### Import Functions for 834 Enrollment Processing

Source: https://pypi.org/project/hccinfhir/0.3.2

Import functions specifically for parsing 834 enrollment files, converting them to demographics, and checking Medicaid status.

```python
from hccinfhir.extractor_834 import (
    extract_enrollment_834,
    enrollment_to_demographics,
    is_losing_medicaid,
    medicaid_status_summary,
)
```

--------------------------------

### Convert Pydantic Model to Dictionary

Source: https://pypi.org/project/hccinfhir

Demonstrates converting Pydantic models to dictionaries for various purposes like JSON serialization or database storage. Supports full, partial, and JSON-safe conversions.

```python
from hccinfhir import HCCInFHIR, Demographics

processor = HCCInFHIR(model_name="CMS-HCC Model V28")
demographics = Demographics(age=67, sex="F")
result = processor.calculate_from_diagnosis(["E11.9"], demographics)

# Convert to dictionary
result_dict = result.model_dump()
print(result_dict["risk_score"])

# JSON-safe conversion
result_json = result.model_dump(mode='json')

# Partial conversion
summary = result.model_dump(include={"risk_score", "hcc_list", "model_name"})

# Exclude large nested data
compact = result.model_dump(exclude={"service_level_data"})

# Convert to JSON string
json_string = result.model_dump_json()

```

--------------------------------

### Parse and Print 820 Remittance Details

Source: https://pypi.org/project/hccinfhir/0.3.2

Parses an X12 820 remittance file and prints payer, payee, total amount, and EFT details. It also iterates through per-member payment entries.

```python
from hccinfhir import get_820_sample
from hccinfhir.extractor_820 import extract_payment_820

# Parse remittance file
payment = extract_payment_820(get_820_sample(1))[0]
print(f"{payment.payer_name} → {payment.payee_name}")
print(f"Total: ${payment.total_amount:,.2f}  EFT: {payment.check_number}")

# Per-member payment detail
for member in payment.members:
    for entry in member.remittance_entries:
        print(f"  {member.member_id}  {entry.coverage_period_start}..{entry.coverage_period_end} "
              f"${entry.payment_amount:,.2f}  {entry.description}")

```

--------------------------------

### Reconcile 820 Payments Against Calculated RAF Scores

Source: https://pypi.org/project/hccinfhir/0.3.2

Compares payment amounts from an 820 remittance file against expected amounts derived from calculated RAF scores and a CMS benchmark. Flags significant variances.

```python
calculated_rafs = {"MBR001": 1.42, "MBR002": 0.98}
cms_benchmark = 1200.00

for member in payment.members:
    raf = calculated_rafs.get(member.member_id)
    if not raf:
        continue
    for entry in member.remittance_entries:
        if entry.payment_amount is None:
            continue
        variance = entry.payment_amount - raf * cms_benchmark
        if abs(variance) > 10:
            print(f"Variance {member.member_id}: ${variance:+.2f} "
                  f"(paid {entry.payment_amount:.2f}, expected {raf * cms_benchmark:.2f})")

```

--------------------------------

### Reconcile 820 Payments Against Calculated RAF Scores

Source: https://pypi.org/project/hccinfhir

Compares payment amounts from an 820 remittance against expected amounts derived from calculated RAF scores and a benchmark. It flags significant variances exceeding a $10 threshold.

```python
calculated_rafs = {"MBR001": 1.42, "MBR002": 0.98}
cms_benchmark = 1200.00

for member in payment.members:
    raf = calculated_rafs.get(member.member_id)
    if not raf:
        continue
    for entry in member.remittance_entries:
        if entry.payment_amount is None:
            continue
        variance = entry.payment_amount - raf * cms_benchmark
        if abs(variance) > 10:
            print(f"Variance {member.member_id}: ${variance:+.2f} "
                  f"(paid {entry.payment_amount:.2f}, expected {raf * cms_benchmark:.2f})")
```

--------------------------------

### Compare RxHCC Scores Across Plan Types (2027 Proposed)

Source: https://pypi.org/project/hccinfhir/0.3.2

This snippet demonstrates how to calculate and compare RAF scores for different RxHCC plan types (PDP_AND_MAPD, PDP_ONLY, MAPD_ONLY) using the proposed 2027 coefficients. It's useful for understanding variations in Part D estimates.

```python
# PDP and MA-PD combined (traditional reference estimate)
processor_pdp_mapd = HCCInFHIR(
    model_name="RxHCC Model V08 PDP_AND_MAPD",
    coefficients_filename="ra_proposed_coefficients_2027.csv"
)

# PDP-only plans (standalone Part D)
processor_pdp = HCCInFHIR(
    model_name="RxHCC Model V08 PDP_ONLY",
    coefficients_filename="ra_proposed_coefficients_2027.csv"
)

# MA-PD only plans (Medicare Advantage with Part D)
processor_mapd = HCCInFHIR(
    model_name="RxHCC Model V08 MAPD_ONLY",
    coefficients_filename="ra_proposed_coefficients_2027.csv"
)

# Compare scores across plan types
demographics = Demographics(age=70, sex="F", low_income=True)
diagnosis_codes = ["E11.9"]

for name, proc in [("PDP_AND_MAPD", processor_pdp_mapd),
                   ("PDP_ONLY", processor_pdp),
                   ("MAPD_ONLY", processor_mapd)]:
    result = proc.calculate_from_diagnosis(diagnosis_codes, demographics)
    print(f"{name}: {result.risk_score:.3f}")

```