Policyengine Healthcare

PolicyEngine healthcare programs

Scope: This skill covers the healthcare domain — Medicaid, ACA marketplace, CHIP, and Medicare as modeled in PolicyEngine-US. For general PolicyEngine-US patterns, see the policyengine-us skill. For variable/parameter implementation patterns, see the policyengine-variable-patterns and policyengine-parameter-patterns skills.

For users

What healthcare programs does PolicyEngine model?

PolicyEngine-US models four interconnected healthcare programs:

These programs are mutually exclusive by design — Medicaid eligibility disqualifies you from ACA subsidies, and CHIP covers children who don't qualify for Medicaid. This interconnection is a key modeling challenge.

Why healthcare is different from other benefits

Most benefit programs (SNAP, TANF, EITC) have a single income test and a single benefit amount. Healthcare programs are different:

• 9 eligibility categories for Medicaid alone (infant, young child, older child, young adult, adult expansion, parent, pregnant, SSI recipient, senior/disabled)
• 51 different Medicaid programs — every state sets its own income limits and rules
• ~500 ACA rating areas — premiums vary by geographic zone, not just by state
• Actuarial calculations — ACA subsidies depend on the second-lowest silver plan premium in your area, adjusted by age
• Program interactions — losing Medicaid doesn't automatically mean gaining ACA access (the "coverage gap")

For analysts

Healthcare variables reference

Medicaid

ACA marketplace

CHIP

Household setup for healthcare analysis

Healthcare calculations require the state to be specified (unlike some federal-only programs):

from policyengine_us import Simulation

situation = {
    "people": {
        "person1": {
            "age": {"2026": 35},
            "employment_income": {"2026": 25_000},
            "is_tax_unit_head": {"2026": True},
        },
        "person2": {
            "age": {"2026": 8},
            "is_tax_unit_dependent": {"2026": True},
        },
    },
    "tax_units": {"tax_unit": {"members": ["person1", "person2"]}},
    "families": {"family": {"members": ["person1", "person2"]}},
    "spm_units": {"spm_unit": {"members": ["person1", "person2"]}},
    "marital_units": {"marital_unit": {"members": ["person1"]}},
    "households": {
        "household": {
            "members": ["person1", "person2"],
            "state_name": {"2026": "NY"},
        }
    },
}

sim = Simulation(situation=situation)

# Check Medicaid eligibility at person level
medicaid_eligible = sim.calculate("is_medicaid_eligible", 2026)
# Check ACA PTC at tax unit level
aca_ptc = sim.calculate("aca_ptc", 2026)

Healthcare reform modeling

Medicaid expansion repeal (parameter modification)

from policyengine_core.reforms import Reform
from policyengine_core.periods import instant

YEAR = 2026

def create_medicaid_expansion_repeal(state="UT"):
    """Remove adult Medicaid expansion by setting income limit to -inf."""
    def modify_parameters(parameters):
        parameters.gov.hhs.medicaid.eligibility.categories.adult.income_limit[state].update(
            start=instant(f"{YEAR}-01-01"),
            stop=instant("2100-12-31"),
            value=float("-inf"),
        )
        return parameters

    class reform(Reform):
        def apply(self):
            self.modify_parameters(modify_parameters)
    return reform

ACA subsidy changes

def modify_aca_contribution_rates():
    """Modify ACA required contribution percentages."""
    def modify_parameters(parameters):
        # The contribution percentage has sub-keys: threshold, initial, final
        # Increase the initial contribution rate at a given FPL bracket
        parameters.gov.aca.required_contribution_percentage.initial.update(
            start=instant(f"{YEAR}-01-01"),
            stop=instant("2100-12-31"),
            value=0.06,  # 6% instead of current rate
        )
        return parameters

    class reform(Reform):
        def apply(self):
            self.modify_parameters(modify_parameters)
    return reform

Population-level healthcare analysis

from policyengine_us import Microsimulation
import numpy as np

YEAR = 2026

# Use state-calibrated dataset for state-level analysis (much more accurate)
sim = Microsimulation(
    dataset="hf://policyengine/policyengine-us-data/states/UT.h5"
)

# Calculate baseline
weights = sim.calculate("person_weight", YEAR).values
medicaid_enrolled = sim.calculate("medicaid_enrolled", YEAR).values
aca_ptc = sim.calculate("aca_ptc", YEAR, map_to="person").values

# Weighted population counts
total_medicaid = (weights * medicaid_enrolled.astype(float)).sum()
total_aca_spending = (weights * aca_ptc).sum()

print(f"Medicaid enrollment: {total_medicaid:,.0f}")
print(f"Total ACA PTC spending: ${total_aca_spending:,.0f}")

Common healthcare analysis patterns

Tracking coverage transitions

When modeling reforms that change Medicaid eligibility, track where people go:

baseline_medicaid = baseline.calculate("medicaid_enrolled", YEAR).values
reform_medicaid = reform_sim.calculate("medicaid_enrolled", YEAR).values
reform_ptc_eligible = reform_sim.calculate("is_aca_ptc_eligible", YEAR).values

loses_medicaid = baseline_medicaid & ~reform_medicaid
gains_aca = loses_medicaid & reform_ptc_eligible
coverage_gap = loses_medicaid & ~reform_ptc_eligible  # Below 100% FPL, no ACA access

print(f"Lose Medicaid: {(weights * loses_medicaid.astype(float)).sum():,.0f}")
print(f"Transition to ACA: {(weights * gains_aca.astype(float)).sum():,.0f}")
print(f"Fall into coverage gap: {(weights * coverage_gap.astype(float)).sum():,.0f}")

Distributional analysis by income

income_level = sim.calculate("medicaid_income_level", YEAR).values

# Group by FPL brackets
brackets = [(0, 1.0), (1.0, 1.38), (1.38, 2.0), (2.0, 4.0)]
for low, high in brackets:
    mask = (income_level >= low) & (income_level < high)
    enrolled = (weights * mask * medicaid_enrolled.astype(float)).sum()
    total = (weights * mask.astype(float)).sum()
    print(f"{low*100:.0f}-{high*100:.0f}% FPL: {enrolled:,.0f} / {total:,.0f}")

Known pitfalls

Use state datasets for state analysis

The national CPS dataset can give implausible state-level results. For example, national CPS showed 76% employer-sponsored insurance at 100-138% FPL in Utah — the state-calibrated dataset gives much more realistic estimates.

# National (less accurate for state analysis)
sim = Microsimulation(dataset="hf://policyengine/policyengine-us-data/enhanced_cps_2024.h5")

# State-calibrated (preferred for state analysis)
sim = Microsimulation(dataset="hf://policyengine/policyengine-us-data/states/UT.h5")

California ACA rating area bug

LA county's rating area can cause errors in California simulations. Workaround:

import numpy as np

try:
    aca_ptc = sim.calculate("aca_ptc", YEAR)
except Exception as e:
    if state == "CA":
        sim.set_input("in_la", YEAR, np.zeros(n_households, dtype=bool))
        aca_ptc = sim.calculate("aca_ptc", YEAR)

The coverage gap

People below 100% FPL who lose Medicaid may not qualify for ACA premium tax credits (which start at 100% FPL in non-expansion states). Always check for this when modeling Medicaid eligibility changes.

Medicaid category transitions

When removing one Medicaid eligibility pathway (e.g., adult expansion), some people may remain eligible through a different category (e.g., parent Medicaid). Track medicaid_category in both baseline and reform to identify true coverage loss vs. category reassignment.

For contributors

Healthcare review checklist

When reviewing healthcare PRs, check these domain-specific items in addition to the standard review checklist:

Program interactions:

• If Medicaid eligibility changed, verify downstream ACA effects (is_aca_ptc_eligible checks Medicaid status)
• If CHIP eligibility changed, verify it still excludes Medicaid-eligible children
• Check that mutual exclusion logic in is_aca_ptc_eligible includes all relevant coverage sources

Eligibility structure:

• New Medicaid categories use the _fc / _nfc split pattern
• Category precedence order in medicaid_category.py is preserved (mandatory before optional, per 42 CFR 435.119)
• Income variable uses correct MAGI definition (medicaid_magi for Medicaid/ACA, not raw AGI)

Geographic variation:

• State-specific Medicaid income limits use the correct parameter path (gov.hhs.medicaid.eligibility.categories.[category].income_limit.[STATE])
• ACA changes check whether affected states use default federal age curves or custom curves (AL, DC, MA, MN, MS, OR, UT) or family tiers (NY, VT)
• SLCSP updates cover all affected rating areas

Temporal correctness:

• ACA calculations use prior-year FPL where required
• SLCSP premiums handled as monthly values (not accidentally annualized)
• ARPA/IRA subsidy enhancement sunset dates are correct in parameter timeline

Take-up and costs:

• Take-up rates are parameterized (not hard-coded)
• Cost allocation uses calibrated per-capita values by eligibility group and state
• Enrollment calibration targets updated if eligibility rules changed

Code organization

Healthcare variables live in three directories under policyengine_us/variables/gov/:

gov/hhs/medicaid/          # ~44 variable files
gov/aca/                    # ~24 variable files
gov/hhs/chip/              # 8 variable files
gov/hhs/medicare/          # Parts A, B, savings programs

Variable naming patterns

The _fc / _nfc pattern

Healthcare eligibility splits financial and non-financial criteria into separate variables. This is important because:

1. Testability — you can test income thresholds independently from age/demographic requirements
2. Reform modeling — reforms often change only one dimension (e.g., raising income limits without changing age ranges)
3. Clarity — reviewers can verify each criterion against its regulatory source

# is_adult_for_medicaid.py combines both using a class attribute (not a formula):
class is_adult_for_medicaid(Variable):
    # all_of_variables as class attribute — no formula method needed
    formula = all_of_variables([
        "is_adult_for_medicaid_fc",   # Income < state limit
        "is_adult_for_medicaid_nfc",  # Age 19-64, not pregnant
    ])

Medicaid categorical hierarchy

Categories are evaluated in regulatory precedence order (42 CFR 435.119). Mandatory groups first, then optional:

# From medicaid_category.py — ORDER MATTERS
variable_to_category = dict(
    is_ssi_recipient_for_medicaid=MedicaidCategory.SSI_RECIPIENT,          # 1st
    is_infant_for_medicaid=MedicaidCategory.INFANT,                         # 2nd
    is_young_child_for_medicaid=MedicaidCategory.YOUNG_CHILD,               # 3rd
    is_older_child_for_medicaid=MedicaidCategory.OLDER_CHILD,               # 4th
    is_pregnant_for_medicaid=MedicaidCategory.PREGNANT,                     # 5th
    is_parent_for_medicaid=MedicaidCategory.PARENT,                         # 6th
    is_young_adult_for_medicaid=MedicaidCategory.YOUNG_ADULT,               # 7th
    is_adult_for_medicaid=MedicaidCategory.ADULT,                           # 8th (expansion)
    is_senior_or_disabled_for_medicaid=MedicaidCategory.SENIOR_OR_DISABLED, # Last
)

A person matched to an earlier category is assigned that category even if they also qualify for a later one. This means adult expansion is always the residual category.

Parameter structure

Healthcare parameters are deeply nested with state-level overrides:

parameters/gov/hhs/medicaid/
├── eligibility/
│   └── categories/
│       ├── adult/income_limit.yaml     # State-by-state limits
│       ├── infant/income_limit.yaml
│       ├── parent/income_limit.yaml
│       └── [5 more categories]
├── income/modification.yaml            # AGI adjustments
├── takeup_rate.yaml                    # 0.93 nationally
└── emergency_medicaid/enabled.yaml

parameters/gov/aca/
├── state_rating_area_cost.yaml         # 1,565 lines — SLCSP by state x rating area
├── age_curves/
│   ├── default.yaml                    # Federal 3:1 ratio
│   ├── al.yaml, dc.yaml, ...          # 7 states with custom curves
│   └── ny.yaml, vt.yaml               # Family tier states
├── required_contribution_percentage/
│   ├── threshold.yaml                  # FPL brackets
│   ├── initial.yaml                    # Initial contribution rates by bracket
│   └── final.yaml                      # Final contribution rates by bracket
└── ptc_income_eligibility.yaml         # 100-400%+ FPL range

ACA geographic complexity

The ACA premium calculation involves three layers of geographic variation:

1. Rating area — ~500 state+rating-area zones across the US, each with its own SLCSP benchmark premium
2. Age curves — most states use the federal 3:1 age rating; 7 states (AL, DC, MA, MN, MS, OR, UT) use custom curves; NY and VT use family tiers instead of age rating entirely
3. State-specific rules — max child count for subsidies, child age definitions

When adding or updating ACA parameters, check whether the state uses the default federal rules or has its own.

Program interaction rules

Healthcare programs check for mutual exclusion:

# In is_aca_ptc_eligible.py
INELIGIBLE_COVERAGE = [
    "is_medicaid_eligible",
    "is_chip_eligible",
    # ... other coverage sources
]
is_coverage_eligible = add(person, period, INELIGIBLE_COVERAGE) == 0

When modifying one program's eligibility, always verify the downstream effects on other programs. Removing Medicaid expansion, for example, shifts people to ACA eligibility (if above 100% FPL) or into a coverage gap (if below).

Healthcare test patterns

Healthcare tests require attention to program interactions and categorical complexity that other benefit programs don't have.

Testing category precedence:

Verify that a person eligible for multiple Medicaid categories gets assigned the highest-precedence one:

- name: Case 1, pregnant adult assigned PREGNANT not ADULT.
  period: 2026-01
  absolute_error_margin: 0.1
  input:
    people:
      person1:
        age: 25
        is_pregnant: true
        employment_income: 15_000
    households:
      household1:
        state_code_str: NY
  output:
    medicaid_category: PREGNANT  # Not ADULT, even though income qualifies for expansion

Testing program mutual exclusion:

Verify that Medicaid-eligible people are excluded from ACA PTC:

- name: Case 2, Medicaid eligible person gets no ACA PTC.
  period: 2026
  absolute_error_margin: 0.1
  input:
    people:
      person1:
        age: 30
        employment_income: 15_000
        is_tax_unit_head: true
    households:
      household1:
        state_code_str: NY
  output:
    is_medicaid_eligible: true
    aca_ptc: 0

Testing the _fc / _nfc split independently:

Test financial and non-financial criteria separately to isolate failures:

# Financial criteria only
- name: Case 3, adult income below Medicaid limit.
  period: 2026-01
  absolute_error_margin: 0.1
  input:
    people:
      person1:
        age: 30
        employment_income: 15_000
    households:
      household1:
        state_code_str: NY
  output:
    is_adult_for_medicaid_fc: true

# Non-financial criteria only
- name: Case 4, person in adult age range.
  period: 2026-01
  absolute_error_margin: 0.1
  input:
    people:
      person1:
        age: 30
        is_pregnant: false
  output:
    is_adult_for_medicaid_nfc: true

Testing coverage transitions in reforms:

When testing reforms that change eligibility, verify where people land:

# In integration tests, check all three outcomes:
# 1. Still has coverage (different program)
# 2. Transitions to ACA
# 3. Falls into coverage gap (below 100% FPL, no ACA access)

Testing state-specific ACA rules:

For states with custom age curves or family tiers, include state-specific test cases:

# NY uses family tiers instead of age rating
- name: Case 5, NY family tier premium.
  period: 2026
  absolute_error_margin: 1
  input:
    people:
      person1:
        age: 35
        employment_income: 40_000
        is_tax_unit_head: true
      person2:
        age: 8
        is_tax_unit_dependent: true
    households:
      household1:
        state_code_str: NY
  output:
    slcsp: 0  # Verify against NY family tier rates, not age-based

Take-up modeling

All healthcare programs use pseudo-random seeding for take-up:

class takes_up_medicaid_if_eligible(Variable):
    def formula(person, period, parameters):
        seed = person("medicaid_take_up_seed", period)  # Random 0-1
        takeup_rate = parameters(period).gov.hhs.medicaid.takeup_rate
        return seed < takeup_rate

Default take-up rates: Medicaid ~93%, ACA PTC ~62-67%. These are parameterized and can be modified in reforms.

Cost allocation

Healthcare costs use per-capita lookups calibrated from MACPAC and CMS data, broken down by eligibility group and state:

class medicaid_cost_if_enrolled(Variable):
    def formula(person, period, parameters):
        group = person("medicaid_group", period)  # Enum
        state = person.household("state_code", period)
        per_capita = parameters(period).calibration.gov.hhs.medicaid.spending
        return per_capita.by_eligibility_group[group][state]

Temporal considerations

• ACA uses prior-year FPL: Income eligibility is measured against the previous year's federal poverty guidelines
• SLCSP premiums are monthly: But benefits are typically calculated annually — watch for period mismatches
• Contribution rates sunset: ARPA/IRA enhanced subsidies have expiration dates encoded in the parameter timeline

Resources

• Medicaid variables: policyengine_us/variables/gov/hhs/medicaid/
• ACA variables: policyengine_us/variables/gov/aca/
• CHIP variables: policyengine_us/variables/gov/hhs/chip/
• Healthcare parameters: policyengine_us/parameters/gov/hhs/medicaid/, policyengine_us/parameters/gov/aca/
• Calibration data: policyengine_us/parameters/calibration/gov/hhs/
• Analysis examples: analysis-notebooks/us/healthcare/, analysis-notebooks/us/medicaid/, analysis-notebooks/us/states/ut/
• Legal references: 42 CFR 435.119 (Medicaid categories), IRC 36B (premium tax credit)