Update Arizona 2025 Individual Income Tax Model

[DTrim99]

Summary

Update the Arizona income tax model for tax year 2025, including parameter value updates, 2025 references for all parameters, and implementation of new modelable programs.

Fixes #7111

Changes

Parameter Value Updates

• Standard deductions updated for 2025 (Single: $15,750, Joint: $31,500, HOH: $23,625, MFS: $15,750)
• Charitable contributions rate updated to 34%

2025 Reference Updates

• Tax rate parameters
• Exemption parameters (aged, blind, stillborn, parent/grandparent)
• Dependent tax credit parameters
• Family tax credit parameters
• Increased excise tax credit parameters
• Property tax credit parameters
• Subtraction parameters
• Charitable contribution credit parameters

New Programs (Planned)

• 529A ABLE Account Contributions Subtraction
• Adoption Expenses Subtraction
• Wood Stove/Fireplace Conversion Subtraction
• Arizona Families Tax Rebate Subtraction
• Filing requirement threshold parameters

Status

• Documentation collected
• Parameters updated
• Variables implemented
• Tests written
• CI passing

Test Plan

• Update existing test files for 2025 parameter values
• Create new test cases for new subtractions
• Run integration tests for 2025 tax year
• Verify make format passes
• Verify make test passes

Primary Source

2025 Arizona Form 140 Instructions

---

This is a draft PR created for early visibility. Implementation work is in progress.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (fc2b613) to head (dcd544c).
⚠️ Report is 45 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff            @@
##              main     #7112   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           10         6    -4     
  Lines          144        69   -75     
=========================================
- Hits           144        69   -75     

Flag	Coverage Δ
unittests	100.00% <100.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[DTrim99]

PR Review: Arizona 2025 Income Tax Model Update

Overall Assessment: APPROVE with minor suggestions

This PR correctly implements Arizona 2025 income tax updates including standard deduction increases, charitable contribution rate updates, new subtractions, and filing requirement thresholds. The implementation is well-structured and properly wired into the existing Arizona tax model.

---

What's Working Well

1. New subtractions are properly integrated: All 4 new subtractions (529A ABLE, adoption expenses, wood stove conversion, and Arizona Families Tax Rebate) are:

   • Added to subtractions.yaml so they flow into az_subtractions.py
   • Have proper input variables that users can specify
   • Correctly use defined_for = StateCode.AZ

2. Parameter values have 2025 references: All updated parameters include the 2025 Form 140 Instructions as a reference source.

3. Good test documentation: Tests include detailed calculation comments explaining expected values.

4. Modelable programs: All new subtractions ARE modelable because:

   • They have user-specifiable input variables (az_able_account_contributions, az_adoption_expenses, az_wood_stove_conversion_expense, az_families_tax_rebate_received)
   • The logic is straightforward (min of expense and cap)
   • No complex eligibility criteria that can't be captured by inputs

---

Should Address

1. Test count is borderline excessive:

   • integration_2025.yaml: 56 tests (1,301 lines)
   • az_income_tax_filing_required.yaml: 20 tests
   • Individual subtraction files: 9-15 tests each

   Suggestion: The integration test file is comprehensive but could be trimmed. Consider:

   • Removing tests that duplicate what's already in unit test files (e.g., filing requirement boundary tests appear in both integration_2025.yaml and az_income_tax_filing_required.yaml)
   • The "Compare 2024 vs 2025" tests (lines 1236-1276) are good for documentation but could be trimmed to 1-2 examples

2. Variable unit mismatch: az_income_tax_filing_required.py (line 8) has unit = USD but the variable is a boolean. Should be removed or changed:

# policyengine_us/variables/gov/states/az/tax/income/az_income_tax_filing_required.py:8
unit = USD  # Should be removed - this is a bool variable

3. Filing requirement parameter missing pre-2024 values: filing_requirement.yaml only has values starting from 2024-01-01. Consider adding historical values or documenting when this was introduced.

---

Suggestions (Non-blocking)

1. Consider consolidating similar edge case tests: For example, az_families_tax_rebate_subtraction.yaml has multiple tests that all just pass through the input value since the variable has no cap. Tests 9-11 ("Single dependent under 17", "Single dependent 17 or older", "Three dependents under 17") test the same code path as tests 1-3.

2. Add a README or module docstring: The new subtractions would benefit from a brief note explaining they were added for 2025 tax year.

---

Validation Summary

Check	Result
New programs modelable	Yes - all have user inputs
Variables wired in correctly	In subtractions.yaml
References included	2025 Form 140 refs added
Code patterns correct	Uses defined_for, proper patterns
Test coverage	Comprehensive but some duplication
CI Status	Most passing, some pending

---

Next Steps

1. Consider removing 5-10 duplicate tests from integration_2025.yaml
2. Fix the unit = USD on the boolean variable
3. Wait for remaining CI checks to complete

---

Generated with Claude Code

[DTrim99]

Fixes Applied

Issues Fixed

1. Fixed unit attribute mismatch (az_income_tax_filing_required.py)

   • Removed unit = USD from boolean variable - boolean variables should not have a unit attribute

2. Removed duplicate tests (integration_2025.yaml)

   • Removed SECTION 9 with 6 filing requirement boundary tests that duplicated tests in az_income_tax_filing_required.yaml
   • Renumbered remaining sections (10→9, 11→10)
   • Reduced integration tests from 56 to 50

3. Removed redundant tests (az_families_tax_rebate_subtraction.yaml)

   • Removed 3 edge case tests that tested the same pass-through logic as existing tests
   • Reduced tests from 11 to 8 while maintaining full coverage

Verification

• All tests pass locally:
  • az_families_tax_rebate_subtraction.yaml: 8/8 passed
  • az_income_tax_filing_required.yaml: 20/20 passed
  • integration_2025.yaml: 50/50 passed
• Code formatted with make format

Summary

File	Change	Tests Removed
az_income_tax_filing_required.py	Removed unit = USD	N/A
integration_2025.yaml	Removed duplicate section	6 tests
az_families_tax_rebate_subtraction.yaml	Removed redundant tests	3 tests

Total test reduction: 9 duplicate/redundant tests removed

Ready for re-review.

[PavelMakarchuk]

High level notes

[DTrim99]

Review Feedback Addressed

Changes Made

Issue	Action Taken
Remove filing_requirement.yaml	✅ Deleted parameter file
Remove az_income_tax_filing_required.py	✅ Deleted variable file and tests
Remove wood stove conversion subtraction	✅ Deleted variable, parameter, input, and tests
Move adoption expenses to federal input	✅ Created qualified_adoption_expenses at federal level

Details

1. Filing Requirement - Removed entirely per feedback that filing requirements aren't modeled in PolicyEngine

2. Wood Stove Conversion - Removed entirely per feedback about model clutter without relevant data

3. Adoption Expenses - Converted from state-specific az_adoption_expenses to federal qualified_adoption_expenses so other states can reuse it

4. Arizona Families Tax Rebate - Kept the subtraction. This is a valid use case: the rebate is federally taxable but AZ-exempt, so users who received the rebate need to subtract it from AZ income. The input variable allows users to specify the rebate amount they received.

Files Changed

Deleted:

• policyengine_us/parameters/gov/states/az/tax/income/filing_requirement.yaml
• policyengine_us/variables/gov/states/az/tax/income/az_income_tax_filing_required.py
• policyengine_us/variables/gov/states/az/tax/income/subtractions/az_wood_stove_conversion_subtraction.py
• policyengine_us/variables/household/expense/person/az_wood_stove_conversion_expense.py
• policyengine_us/parameters/gov/states/az/tax/income/subtractions/wood_stove/max_amount.yaml
• policyengine_us/variables/household/expense/person/az_adoption_expenses.py
• Related test files

Added:

• policyengine_us/variables/household/expense/tax_unit/qualified_adoption_expenses.py (federal input)

Modified:

• az_adoption_expense_subtraction.py - Now uses federal input
• subtractions.yaml - Removed wood stove entry
• Test files updated accordingly

Verification

• ✅ All 255 Arizona income tax tests pass
• ✅ Code formatted with make format

Question for Reviewer

Regarding Arizona Families Tax Rebate: I kept the subtraction because it serves a legitimate purpose - users who received the 2023/2024 rebate need to subtract it from Arizona taxable income (federally taxable but AZ-exempt). Should this also be removed, or is the current approach acceptable?

---

Ready for re-review.

[hua7450]

Reference Page Numbers for 2025 Arizona Form 140 Instructions

Based on review of the 2025 Arizona Form 140 Instructions PDF, here are the page numbers for each parameter file to add #page=XX anchors:

Standard Deductions

File	Topic	Page
deductions/standard/amount.yaml	Filing requirements / Standard deduction amounts	Page 1 (also Page 21)
deductions/standard/increased/rate.yaml	Charitable contribution 34% rate	Page 21 (Line 44)

Exemptions

File	Topic	Page
exemptions/aged.yaml	Age 65+ exemption ($2,100)	Page 20 (Line 38)
exemptions/blind.yaml	Blind exemption ($1,500)	Page 20 (Line 39)
exemptions/stillborn.yaml	Stillborn child exemption ($2,300)	Page 20 (Line 40)
exemptions/parent_grandparent/amount.yaml	Qualifying parent/grandparent ($10,000)	Page 20-21 (Line 41)
exemptions/parent_grandparent/min_age.yaml	Age 65 requirement	Page 6-7 (Box 11a)
exemptions/parent_grandparent/cost_rate.yaml	More than 1/2 support cost	Page 7

Tax Rates

File	Topic	Page
main/single.yaml	2.5% tax rate	Page 21 (Line 46)
main/joint.yaml	2.5% tax rate	Page 21 (Line 46)
main/head_of_household.yaml	2.5% tax rate	Page 21 (Line 46)
main/separate.yaml	2.5% tax rate	Page 21 (Line 46)

Credits - Dependent Tax Credit

File	Topic	Page
credits/dependent_credit/amount.yaml	$100 (under 17), $25 (17+)	Page 21 (Line 49)
credits/dependent_credit/reduction/start.yaml	Phase-out thresholds ($200k/$400k)	Page 21-22
credits/dependent_credit/reduction/percentage.yaml	5% reduction rate	Page 22
credits/dependent_credit/reduction/increment.yaml	Per $1,000 increment	Page 22

Credits - Family Tax Credit

File	Topic	Page
credits/family_tax_credits/amount/per_person.yaml	$40 per person	Page 23 (Step 4, Worksheet II)
credits/family_tax_credits/amount/cap.yaml	$240 (Joint/HOH), $120 (Single/Sep)	Page 23 (Step 4, Worksheet II)
credits/family_tax_credits/income_limit/single.yaml	$10,000	Page 23 (Table III)
credits/family_tax_credits/income_limit/joint.yaml	$20,000-$31,000 by dependents	Page 23 (Table I)
credits/family_tax_credits/income_limit/head_of_household.yaml	$20,000-$26,575 by dependents	Page 23 (Table II)
credits/family_tax_credits/income_limit/separate.yaml	$10,000	Page 23 (Table III)

Credits - Increased Excise Tax Credit

File	Topic	Page
credits/increased_excise/amount.yaml	$25 per person	Page 26 (Worksheet)
credits/increased_excise/income_threshold.yaml	$25,000 (Joint/HOH), $12,500 (Single/Sep)	Page 25 (Line 56)
credits/increased_excise/max_amount.yaml	$100 maximum	Page 26 (Worksheet, Line 5)

Credits - Property Tax

File	Topic	Page
credits/property_tax/age_threshold.yaml	Age 65 requirement	Page 26 (Line 57)

Subtractions

File	Topic	Page
subtractions/able_account/cap.yaml	529A ABLE - $2,000/$4,000	Page 16 (Line 34b)
subtractions/adoption/max_amount.yaml	Adoption expenses - $40,000	Page 17 (Line 36, Item D)
subtractions/capital_gains/rate.yaml	25% subtraction	Page 13 (Line 24)
subtractions/college_savings/cap.yaml	529 plans - $2,000/$4,000	Page 16 (Line 34a)
subtractions/military_retirement/max_amount.yaml	100% subtraction	Page 15 (Line 29b)
subtractions/pension/public_pension_cap.yaml	$2,500 cap	Page 14-15 (Line 29a)

New Variables - Arizona Families Tax Rebate

File	Topic	Page
az_families_tax_rebate_subtraction.py	Rebate subtraction	Page 20 (Line 36, Item U)

---

Example Reference Format

reference:
  - title: 2025 Arizona Form 140 Instructions, Line 36 Item D
    href: https://azdor.gov/sites/default/files/document/FORMS_INDIVIDUAL_2025_140i.pdf#page=17

Regulatory Verification Summary

All parameter values in this PR have been verified against the official 2025 Arizona Form 140 Instructions:

• ✅ Standard deductions ($15,750 / $31,500 / $23,625)
• ✅ Charitable contribution rate (34%)
• ✅ Adoption expense limit ($40,000) - confirmed on Page 17
• ✅ 529A ABLE account limits ($2,000 / $4,000)
• ✅ Exemption amounts ($2,100 aged, $1,500 blind)
• ✅ Dependent tax credit ($100 under 17, $25 for 17+)
• ✅ Family tax credit ($40/person, $240/$120 max)
• ✅ Increased excise tax credit ($25/person, $100 max)

[hua7450]

Missing: 2025 Arizona Charitable Contribution Credit Limits

The following 2025 parameter values should be added to complete the Arizona tax model update:

Form 321 - Qualifying Charitable Organizations (QCO)

File: qualifying_organization.yaml

Filing Status	2025 Limit
Married Filing Jointly	$987
Single / HOH / MFS / Surviving Spouse	$495

Form 352 - Qualifying Foster Care Charitable Organizations (QFCO)

File: qualifying_foster.yaml

Filing Status	2025 Limit
Married Filing Jointly	$1,234
Single / HOH / MFS / Surviving Spouse	$618

Source

• Credits for Contributions to QCOs and QFCOs - Arizona Department of Revenue

[hua7450]

Arizona Families Tax Rebate - Implementation Note

The current implementation uses an input variable (az_families_tax_rebate_received), but for consistency with other states (IL, RI), this could be converted to a calculated formula.

Rebate Formula

Dependent Type	Amount
Under age 17	$250
Age 17 or older	$100

Caps:

• Max 3 dependents counted (regardless of age)
• $750 max for Single, Head of Household, Married Filing Separately
• $1,500 max for Married Filing Jointly

Comparison with Other States

State	Based On	Implementation in Repo
IL	2021 return	Calculated from current-year data
RI	2021 return	Calculated from current-year data
AZ	2021 return	Input variable

IL and RI use current-year data for simulation purposes (limited to 2021 via refundable.yaml). AZ could follow the same pattern.

Sources

• Arizona Families Tax Rebate | AZDOR
• SB1734 - Senate Fact Sheet
• AZDOR 1099-MISC Guidance

[hua7450]

PR #7112 - Remaining Issues

Files to Remove

• Delete .implementation_az_2025_income_tax.md

Variable Pattern Issues

• Remove documentation field, use reference with URL in az_529a_able_account_subtraction.py
• Remove documentation field, use reference with URL in az_adoption_expense_subtraction.py
• Remove documentation field, use reference with URL in az_families_tax_rebate_subtraction.py
• Remove documentation field, use reference with URL in az_able_account_contributions.py
• Remove documentation field, use reference with URL in az_families_tax_rebate_received.py

Parameter Issues

• Fix malformed page anchor #page20 → #page=20 in parent_grandparent/cost_rate.yaml
• Fix incomplete URL in main/joint.yaml line 13
• Move reference field inside metadata block in family_tax_credits/amount/cap.yaml
• Add 2025 values for qualifying_foster.yaml ($1,234 / $618)
• Add 2025 values for qualifying_organization.yaml ($987 / $495)

Enhancement

• Implement az_families_tax_rebate_received as calculated formula (like IL, RI)

[DTrim99]

Fixes Applied (Ziming's Comments)

Issues Fixed

1. Added page number anchors to all 2025 Form 140 references ✅

   • 30+ parameter files now include #page=XX anchors
   • Organized by section (deductions, exemptions, rates, credits, subtractions)
   • Example: https://azdor.gov/.../FORMS_INDIVIDUAL_2025_140i.pdf#page=21

2. Added 2025 QCO/QFCO charitable contribution limits ✅

   Credit	Joint	Other
   Form 321 (QCO)	$987	$495
   Form 352 (QFCO)	$1,234	$618

   Source: AZDOR - Credits for Contributions to QCOs and QFCOs

Not Implemented (Design Decision)

Arizona Families Tax Rebate - Kept as input variable rather than converting to calculated formula because:

• One-time rebate based on 2021 tax return data
• Not an ongoing program like IL/RI income tax rebates
• Current approach correctly allows users to subtract the actual rebate amount they received

Verification

• ✅ All 255 Arizona income tax tests pass
• ✅ Code formatted

Files Changed

34 parameter files updated with page anchors and 2025 QCO/QFCO values.

---

🤖 Generated with Claude Code

[DTrim99]

Addressed review feedback with the following changes:

Variable refactoring:

• Removed az_able_account_contributions from household/expense - now using the existing federal able_contributions variable
• Removed qualified_adoption_expenses from household/expense - created pre_subsidy_qualified_adoption_expenses in the AZ folder instead
• Removed az_families_tax_rebate_received from household/income - rebate is now calculated via formula

Rebate formula:

• Added formula to calculate the Arizona Families Tax Rebate based on dependents:
  • $250 per dependent under age 17
  • $100 per dependent age 17+
  • Maximum of 3 dependents (young dependents prioritized)
• Created rebate parameters in gov/states/az/tax/income/rebate/

Reference cleanup:

• Removed page numbers from reference titles across all parameter files
• Page anchors preserved in URLs (e.g., #page=17)

All 56 Arizona subtraction tests pass.

[hua7450]

We should add the tax rebate (I thought its a credit, but based on the variable naming, its a subtraction?) to one of the list, add it back to 2023? Or 2021? It should not be 2025 right?
Add the other two programs to their corresponding list as well, other wise they won't affect state's income calculation.

[hua7450]

Need to fix this: Remove documentation field, use reference with URL in az_families_tax_rebate_subtraction.py
Check other files as well.