Add voluntary tax filer assignment (#513)

* Add voluntary tax filer assignment

SOI data shows many low-AGI filers who file taxes voluntarily even when
not required and not receiving a refund. This affects calibration accuracy
when comparing CPS-based filer counts to SOI totals.

Add would_file_taxes_voluntarily variable at tax_unit level with ~5%
probability, using seeded RNG for reproducibility. This enables
policyengine-us to incorporate voluntary filing behavior in its
tax_unit_is_filer variable.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Improve voluntary tax filer logic with refund-seeking behavior

Replace simple 5% voluntary filing rate with more nuanced approach:

1. Add would_file_for_refund variable that identifies tax units taking
   up EITC (95% of EITC takers are assumed to know they'll get a refund)

2. Apply voluntary filing rate (3%) only to those NOT already filing
   for a refund, to avoid double-counting

This better models the actual filing decision process where refundable
credit recipients have a clear financial incentive to file, while others
may file for state requirements, documentation, or habit.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Simplify voluntary filer logic and add filer count calibration targets

Voluntary filer changes (cps.py):
- Remove redundant would_file_for_refund variable since takes_up_eitc
  already captures refund-seeking behavior
- Simplify to single would_file_taxes_voluntarily variable that applies
  only to tax units NOT taking up EITC
- Use 5% voluntary filing rate for non-EITC takers

Calibration target changes (loss.py):
- Add SOI Table 1.1 filer counts by AGI band as calibration targets
- Covers 7 bands: <$0, $0-5k, $5k-10k, $10k-25k, $25k-50k, $50k-100k, $100k+
- Includes all filers (not just taxable returns) to properly calibrate
  low-income filer counts which are important for distribution accuracy
- Uprates 2015 SOI counts to current year using population growth

This consolidates PR #514 into PR #513.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Add changelog entry

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: 2 people

changelog_entry.yaml

@@ -0,0 +1,4 @@
+- bump: minor
+  changes:
+    added:
+      - Add voluntary tax filer variable and filer count calibration targets by AGI band.

policyengine_us_data/datasets/cps/cps.py

@@ -289,6 +289,17 @@ def add_takeup(self):
     imputed_risk = rng.random(n_persons) < wic_risk_rate_by_person
     data["is_wic_at_nutritional_risk"] = receives_wic | imputed_risk
 
+    # Voluntary tax filing: some people file even when not required and not
+    # seeking a refund. EITC take-up already captures refund-seeking behavior
+    # (if you take up EITC, you file). This variable captures people who file
+    # for other reasons: state requirements, documentation, habit.
+    # ~5% of tax units who don't take up EITC still file voluntarily.
+    voluntary_filing_rate = 0.05
+    rng = seeded_rng("would_file_taxes_voluntarily")
+    data["would_file_taxes_voluntarily"] = ~data["takes_up_eitc"] & (
+        rng.random(n_tax_units) < voluntary_filing_rate
+    )
+
     self.save_dataset(data)
 
 

policyengine_us_data/utils/loss.py

@@ -339,6 +339,39 @@ def build_loss_matrix(dataset: type, time_period):
         )
         targets_array.append(row["eitc_total"] * eitc_spending_uprating)
 
+    # Tax filer counts by AGI band (SOI Table 1.1)
+    # This calibrates total filers (not just taxable returns) including
+    # low-AGI filers who are important for income distribution accuracy
+    SOI_FILER_COUNTS_2015 = {
+        # (agi_lower, agi_upper): total_returns
+        (-np.inf, 0): 2_072_066,
+        (0, 5_000): 10_134_703,
+        (5_000, 10_000): 11_398_595,
+        (10_000, 25_000): 23_447_927,
+        (25_000, 50_000): 23_727_745,
+        (50_000, 100_000): 32_801_908,
+        (100_000, np.inf): 25_120_985,
+    }
+
+    # Get AGI and filer status at tax unit level, mapped to household
+    agi_tu = sim.calculate("adjusted_gross_income").values
+    is_filer_tu = sim.calculate("tax_unit_is_filer").values > 0
+
+    for (
+        agi_lower,
+        agi_upper,
+    ), filer_count_2015 in SOI_FILER_COUNTS_2015.items():
+        in_band = (agi_tu >= agi_lower) & (agi_tu < agi_upper)
+        label = f"nation/soi/filer_count/agi_{fmt(agi_lower)}_{fmt(agi_upper)}"
+        loss_matrix[label] = sim.map_result(
+            (is_filer_tu & in_band).astype(float),
+            "tax_unit",
+            "household",
+        )
+        # Uprate from 2015 to current year using population growth
+        uprated_target = filer_count_2015 * population_uprating
+        targets_array.append(uprated_target)
+
     # Hard-coded totals
     for variable_name, target in HARD_CODED_TOTALS.items():
         label = f"nation/census/{variable_name}"