Add tax filing propensity variables (#7333)

* Add voluntary tax filer variable and update tax_unit_is_filer

- Add would_file_taxes_voluntarily input variable for tax units that file
  for reasons other than being required or seeking refundable credits
- Update tax_unit_is_filer to use propensity variables from microdata:
  - required_to_file (income thresholds from IRC § 6012)
  - takes_up_eitc (refund-seeking behavior)
  - would_file_taxes_voluntarily (state requirements, documentation, habit)

Closes #4286

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

* Refactor tax filing logic with explicit eligibility check

- Add tax_unit_is_required_to_file for rules-based filing requirement
- Add eligible_for_refundable_credits to check EITC/CTC eligibility
- Add would_file_if_eligible_for_refundable_credit propensity variable
- Update tax_unit_is_filer to use three-part logic:
  1. Required to file (income thresholds)
  2. Eligible for refundable credits AND would file to claim them
  3. Would file voluntarily (state requirements, habit, documentation)

This separates the refundable credit eligibility check from the propensity
to file, enabling policy reforms that change credit eligibility to affect
filing behavior.

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

* Update changelog entry

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

* Fix exemption suspension in filing requirement and simplify credit check

- Use 0 for exemption_amount when personal exemption is suspended (2018+)
  to match the old tax_unit_is_filer logic
- Simplify eligible_for_refundable_credits: eitc + refundable_ctc > 0

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

---------

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

Author: MaxGhenis

changelog_entry.yaml

@@ -0,0 +1,9 @@
+- bump: minor
+  changes:
+    added:
+      - Add tax_unit_is_required_to_file variable for rules-based filing requirement.
+      - Add eligible_for_refundable_credits variable for EITC/CTC eligibility check.
+      - Add would_file_if_eligible_for_refundable_credit propensity variable.
+      - Add would_file_taxes_voluntarily propensity variable for voluntary filers.
+    changed:
+      - Refactor tax_unit_is_filer to use three-part filing logic with propensity variables.

policyengine_us/tests/policy/baseline/gov/irs/tax_unit_is_filer.yaml

@@ -0,0 +1,61 @@
+- name: High income - required to file
+  period: 2024
+  input:
+    people:
+      person:
+        age: 30
+        employment_income: 100000
+    tax_units:
+      tax_unit:
+        members: [person]
+  output:
+    tax_unit_is_required_to_file: true
+    tax_unit_is_filer: true
+
+- name: Low income with child - not required but files for credits
+  period: 2024
+  input:
+    people:
+      adult:
+        age: 30
+        employment_income: 5000
+      child:
+        age: 5
+    tax_units:
+      tax_unit:
+        members: [adult, child]
+  output:
+    tax_unit_is_required_to_file: false
+    eligible_for_refundable_credits: true
+    tax_unit_is_filer: true
+
+- name: No income - not required and no credits
+  period: 2024
+  input:
+    people:
+      person:
+        age: 30
+        employment_income: 0
+    tax_units:
+      tax_unit:
+        members: [person]
+  output:
+    tax_unit_is_required_to_file: false
+    eligible_for_refundable_credits: false
+    tax_unit_is_filer: false
+
+- name: Voluntary filer - not required but chooses to file
+  period: 2024
+  input:
+    people:
+      person:
+        age: 30
+        employment_income: 0
+    tax_units:
+      tax_unit:
+        members: [person]
+        would_file_taxes_voluntarily: true
+  output:
+    tax_unit_is_required_to_file: false
+    eligible_for_refundable_credits: false
+    tax_unit_is_filer: true

policyengine_us/variables/gov/irs/eligible_for_refundable_credits.py

@@ -0,0 +1,18 @@
+from policyengine_us.model_api import *
+
+
+class eligible_for_refundable_credits(Variable):
+    value_type = bool
+    entity = TaxUnit
+    label = "eligible for refundable tax credits"
+    documentation = """
+    Whether this tax unit is eligible for any refundable federal tax credits
+    (EITC, refundable CTC, etc.) that would create an incentive to file even
+    if not legally required.
+    """
+    definition_period = YEAR
+
+    def formula(tax_unit, period, parameters):
+        eitc = tax_unit("eitc", period)
+        refundable_ctc = tax_unit("refundable_ctc", period)
+        return (eitc + refundable_ctc) > 0

policyengine_us/variables/gov/irs/tax_unit_is_filer.py

@@ -2,73 +2,39 @@
 
 
 class tax_unit_is_filer(Variable):
-    value_type = float
+    value_type = bool
     entity = TaxUnit
     label = "files taxes"
-    unit = USD
-    documentation = (
-        "Whether this tax unit has a non-zero income tax liability."
-    )
-    definition_period = YEAR
-
-    """
-    (a) General rule
-    Returns with respect to income taxes under subtitle A shall be made by the following:
-    (1)
-    (A) Every individual having for the taxable year gross income which equals or exceeds the exemption amount, except that a return shall not be required of an individual—
-    (i) who is not married (determined by applying section 7703), is not a surviving spouse (as defined in section 2(a)), is not a head of a household (as defined in section 2(b)), and for the taxable year has gross income of less than the sum of the exemption amount plus the basic standard deduction applicable to such an individual,
-    (ii) who is a head of a household (as so defined) and for the taxable year has gross income of less than the sum of the exemption amount plus the basic standard deduction applicable to such an individual,
-    (iii) who is a surviving spouse (as so defined) and for the taxable year has gross income of less than the sum of the exemption amount plus the basic standard deduction applicable to such an individual, or
-    (iv) who is entitled to make a joint return and whose gross income, when combined with the gross income of his spouse, is, for the taxable year, less than the sum of twice the exemption amount plus the basic standard deduction applicable to a joint return, but only if such individual and his spouse, at the close of the taxable year, had the same household as their home.
-    Clause (iv) shall not apply if for the taxable year such spouse makes a separate return or any other taxpayer is entitled to an exemption for such spouse under section 151(c).
-    (B) The amount specified in clause (i), (ii), or (iii) of subparagraph (A) shall be increased by the amount of 1 additional standard deduction (within the meaning of section 63(c)(3)) in the case of an individual entitled to such deduction by reason of section 63(f)(1)(A) (relating to individuals age 65 or more), and the amount specified in clause (iv) of subparagraph (A) shall be increased by the amount of the additional standard deduction for each additional standard deduction to which the individual or his spouse is entitled by reason of section 63(f)(1).
-    (C) The exception under subparagraph (A) shall not apply to any individual—
-    (i) who is described in section 63(c)(5) and who has—
-    (I) income (other than earned income) in excess of the sum of the amount in effect under section 63(c)(5)(A) plus the additional standard deduction (if any) to which the individual is entitled, or
-    (II) total gross income in excess of the standard deduction, or
-    (ii) for whom the standard deduction is zero under section 63(c)(6).
-    (D) For purposes of this subsection—
-    (i) The terms "standard deduction", "basic standard deduction" and "additional standard deduction" have the respective meanings given such terms by section 63(c).
-    (ii) The term "exemption amount" has the meaning given such term by section 151(d). In the case of an individual described in section 151(d)(2), the exemption amount shall be zero.
+    documentation = """
+    Whether this tax unit files a federal income tax return.
+
+    A tax unit files if any of the following apply:
+    1. They are legally required to file (IRC § 6012)
+    2. They are eligible for refundable credits and would file to claim them
+    3. They would file voluntarily for other reasons (state requirements,
+       documentation, habit)
+
+    The propensity variables (would_file_if_eligible_for_refundable_credit
+    and would_file_taxes_voluntarily) are assigned during microdata
+    construction.
     """
+    definition_period = YEAR
+    reference = "https://www.law.cornell.edu/uscode/text/26/6012"
 
     def formula(tax_unit, period, parameters):
-        gross_income = add(tax_unit, period, ["irs_gross_income"])
-        p = parameters(period).gov.irs.income.exemption
-        exemption_amount = 0 if p.suspended else p.amount
+        # Required to file based on income thresholds
+        required = tax_unit("tax_unit_is_required_to_file", period)
 
-        # (a)(1)(A), (a)(1)(B)
-
-        filing_status = tax_unit("filing_status", period).decode_to_str()
-        separate = filing_status == "SEPARATE"
-        standard_deduction = tax_unit("standard_deduction", period)
-        threshold = where(
-            separate,
-            exemption_amount,
-            standard_deduction + exemption_amount,
+        # Would file to claim refundable credits (EITC, CTC, etc.)
+        eligible_for_credits = tax_unit(
+            "eligible_for_refundable_credits", period
         )
-
-        income_over_exemption_amount = gross_income > threshold
-
-        # (a)(1)(C)
-
-        unearned_income_threshold = 500 + tax_unit(
-            "additional_standard_deduction", period
-        )
-        unearned_income = gross_income - add(
-            tax_unit, period, ["earned_income"]
-        )
-        unearned_income_over_threshold = (
-            unearned_income > unearned_income_threshold
+        would_file_for_credits = tax_unit(
+            "would_file_if_eligible_for_refundable_credit", period
         )
+        files_for_credits = eligible_for_credits & would_file_for_credits
 
-        required_to_file = (
-            income_over_exemption_amount | unearned_income_over_threshold
-        )
-
-        tax_refund = tax_unit("income_tax", period) < 0
-        not_required_but_likely_filer = ~required_to_file & tax_refund
-
-        # (a)(1)(D) is just definitions
+        # Would file voluntarily for other reasons
+        files_voluntarily = tax_unit("would_file_taxes_voluntarily", period)
 
-        return required_to_file | not_required_but_likely_filer
+        return required | files_for_credits | files_voluntarily

policyengine_us/variables/gov/irs/tax_unit_is_required_to_file.py

@@ -0,0 +1,44 @@
+from policyengine_us.model_api import *
+
+
+class tax_unit_is_required_to_file(Variable):
+    value_type = bool
+    entity = TaxUnit
+    label = "required to file federal taxes"
+    documentation = """
+    Whether this tax unit is legally required to file a federal income tax
+    return under IRC § 6012, based on gross income thresholds and filing
+    status.
+    """
+    definition_period = YEAR
+    reference = "https://www.law.cornell.edu/uscode/text/26/6012"
+
+    def formula(tax_unit, period, parameters):
+        gross_income = add(tax_unit, period, ["irs_gross_income"])
+        p = parameters(period).gov.irs.income.exemption
+        exemption_amount = 0 if p.suspended else p.amount
+
+        # (a)(1)(A), (a)(1)(B)
+        filing_status = tax_unit("filing_status", period).decode_to_str()
+        separate = filing_status == "SEPARATE"
+        standard_deduction = tax_unit("standard_deduction", period)
+        threshold = where(
+            separate,
+            exemption_amount,
+            standard_deduction + exemption_amount,
+        )
+
+        income_over_exemption_amount = gross_income > threshold
+
+        # (a)(1)(C) - unearned income threshold for dependents
+        unearned_income_threshold = 500 + tax_unit(
+            "additional_standard_deduction", period
+        )
+        unearned_income = gross_income - add(
+            tax_unit, period, ["earned_income"]
+        )
+        unearned_income_over_threshold = (
+            unearned_income > unearned_income_threshold
+        )
+
+        return income_over_exemption_amount | unearned_income_over_threshold

policyengine_us/variables/gov/irs/would_file_if_eligible_for_refundable_credit.py

@@ -0,0 +1,17 @@
+from policyengine_us.model_api import *
+
+
+class would_file_if_eligible_for_refundable_credit(Variable):
+    value_type = bool
+    entity = TaxUnit
+    label = "would file taxes if eligible for refundable credit"
+    documentation = """
+    Whether this tax unit would file taxes if eligible for a refundable tax
+    credit (EITC, ACTC, etc.), even if not legally required to file.
+
+    This is an input variable assigned during microdata construction based
+    on propensity modeling. The vast majority of refundable credit eligible
+    filers do file to claim their credits.
+    """
+    definition_period = YEAR
+    default_value = True

policyengine_us/variables/gov/irs/would_file_taxes_voluntarily.py

@@ -0,0 +1,14 @@
+from policyengine_us.model_api import *
+
+
+class would_file_taxes_voluntarily(Variable):
+    value_type = bool
+    entity = TaxUnit
+    label = "would file taxes voluntarily"
+    documentation = """
+    Whether this tax unit would file taxes even when not required and not
+    seeking a refund from refundable credits. Captures filing for reasons
+    such as state requirements, documentation needs, or habit.
+    """
+    definition_period = YEAR
+    default_value = False