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:
- 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.
- 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?
- Update both helpers to match the chosen contract.
- Update TAXSIM mapping if the contract changes semantics.
Out of scope
References
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.pycovers 8 states: CT, ID, MO, ND, NM, SC, UT, CO.state_itemized_deductions.pycovers 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'svariable_mappings.yaml. So a TAXSIM consumer querying a CO household still seesstate_standard_deduction = $31,500andstate_itemized_deductions = $0, which is misleading.Proposed work
Decide on consistent semantics, then apply across all states:
$0.Out of scope
tax_unit_itemizesdecision logic (already fixed in Fix tax_unit_itemizes tied-federal-tax fallback (#8210) #8213).References
policyengine-taxsim'svariable_mappings.yamlfor v34/v35 consumers