PolicyEngine / PolicyEngine/policyengine-us

Harmonize state_standard_deduction and state_itemized_deductions coverage

Open
#8,275 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
162
Forks
212
Avg merge
3d 3h
Merged PRs (30d)
96

Description

## Background

PR #8213 fixed the user-visible bug in `tax_unit_itemizes` (it now falls back to federal-level deduction comparison when federal tax is tied between the itemize/standard branches). But it explicitly left the underlying helper asymmetry in place:

- **`state_standard_deduction.py`** covers **8 states**: CT, ID, MO, ND, NM, SC, UT, CO.
- **`state_itemized_deductions.py`** covers only **5 states**: CT, GA, ND, SC, UT. For everyone else it sums state-specific line items, which for many states evaluates to `$0`.

The helpers are still exposed via TAXSIM v34 ("Standard Deduction") and v35 ("Itemized Deductions") in `policyengine-taxsim`'s `variable_mappings.yaml`. So a TAXSIM consumer querying a CO household still sees `state_standard_deduction = $31,500` and `state_itemized_deductions = $0`, which is misleading.

## Proposed work

Decide on consistent semantics, then apply across all states:

1. **Pick a contract.** Options:
- "Returns the actual amount the household would deduct on the state return." Requires per-state research; many states have hybrid rules (separate caps, add-backs, federal-conformity dates).
- "Returns NaN or raises for unmapped states." Conservative — surfaces gaps rather than silently returning `$0`.
2. **Per-state audit.** For each state with an income tax (≈42 states + DC):
- Standard deduction: federal-conforming? Own amount? None?
- Itemized deductions: federal-conforming? Own subset (e.g. SALT caps differ)? None allowed?
3. **Update both helpers** to match the chosen contract.
4. **Update TAXSIM mapping** if the contract changes semantics.

## Out of scope

- The `tax_unit_itemizes` decision logic (already fixed in #8213).

## References

- PR #8213 (the targeted fix)
- TAXSIM tickets driven by this asymmetry: [#870](https://github.com/PolicyEngine/policyengine-taxsim/issues/870) (CO), [#869](https://github.com/PolicyEngine/policyengine-taxsim/issues/869) (VT), [#868](https://github.com/PolicyEngine/policyengine-taxsim/issues/868) (RI), [#854](https://github.com/PolicyEngine/policyengine-taxsim/issues/854) (LA)
- `policyengine-taxsim`'s `variable_mappings.yaml` for v34/v35 consumers

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.