PolicyEngine itemization bug demonstration

itemization_bug_minimal.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# PolicyEngine Itemization Bug Demo\n",
    "\n",
    "This notebook demonstrates a bug where household 4428 itemizes despite worse tax outcomes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from policyengine_us import Microsimulation\n",
    "from policyengine_us.model_api import *\n",
    "import numpy as np"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Setup\n",
    "\n",
    "Using household 4428 from the enhanced CPS 2024 dataset:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "DATASET = \"hf://policyengine/policyengine-us-data/enhanced_cps_2024.h5\"\n",
    "HOUSEHOLD_ID = 4428\n",
    "YEAR = 2026"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Create Minimal Reform Stack\n",
    "\n",
    "The bug occurs when CTC reform is applied after other reforms:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Minimal reform stack that triggers the bug\n",
    "reform = Reform.from_dict({\n",
    "    # Standard deduction increase\n",
    "    \"gov.irs.deductions.standard.amount.JOINT\": {\"2026-01-01\": 48900},\n",
    "    # Exemption elimination\n",
    "    \"gov.irs.income.exemption.amount\": {\"2026-01-01\": 0},\n",
    "    # CTC changes\n",
    "    \"gov.contrib.reconciliation.ctc.in_effect\": {\"2026-01-01\": True},\n",
    "    \"gov.irs.credits.ctc.amount.base[0].amount\": {\"2026-01-01\": 2200},\n",
    "}, country_id=\"us\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Demonstrate the Bug"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Create simulation\n",
    "sim = Microsimulation(reform=reform, dataset=DATASET)\n",
    "\n",
    "# Find household\n",
    "household_ids = sim.calculate(\"household_id\", map_to=\"household\", period=YEAR).values\n",
    "idx = np.where(household_ids == HOUSEHOLD_ID)[0][0]\n",
    "\n",
    "# Get values\n",
    "itemizes = sim.calculate(\"tax_unit_itemizes\", map_to=\"household\", period=YEAR).values[idx]\n",
    "tax_if_item = sim.calculate(\"tax_liability_if_itemizing\", map_to=\"household\", period=YEAR).values[idx]\n",
    "tax_if_std = sim.calculate(\"tax_liability_if_not_itemizing\", map_to=\"household\", period=YEAR).values[idx]\n",
    "\n",
    "print(f\"Itemizes: {bool(itemizes)}\")\n",
    "print(f\"Tax if itemizing: ${tax_if_item:,.2f}\")\n",
    "print(f\"Tax if standard: ${tax_if_std:,.2f}\")\n",
    "print(f\"Should itemize: {tax_if_item < tax_if_std}\")\n",
    "print(f\"\\nBUG: Household itemizes despite ${tax_if_item - tax_if_std:,.2f} worse outcome!\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Verify Bug Disappears Without CTC Reform"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Test without CTC reform\n",
    "reform_no_ctc = Reform.from_dict({\n",
    "    \"gov.irs.deductions.standard.amount.JOINT\": {\"2026-01-01\": 48900},\n",
    "    \"gov.irs.income.exemption.amount\": {\"2026-01-01\": 0},\n",
    "}, country_id=\"us\")\n",
    "\n",
    "sim_no_ctc = Microsimulation(reform=reform_no_ctc, dataset=DATASET)\n",
    "itemizes_no_ctc = sim_no_ctc.calculate(\"tax_unit_itemizes\", map_to=\"household\", period=YEAR).values[idx]\n",
    "\n",
    "print(f\"Without CTC reform, itemizes: {bool(itemizes_no_ctc)}\")\n",
    "print(\"✓ Correctly takes standard deduction without CTC reform\")"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python",
   "version": "3.9.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}