Implement Pennsylvania TANF

[hua7450]

Summary

Implements Pennsylvania TANF (Temporary Assistance for Needy Families) cash assistance program with corrected income deduction formula per PA DHS policy.

Closes #6759

Status

• Documentation collected
• Parameters created (12 files)
• Variables implemented (10 files)
• Tests written (72 test cases across 9 files)
• CI passing
• Formula corrected to match PA DHS policy
• Real-world validation completed
• Ready for review (mark ready when you want review)

---

Key Changes

Implementation Summary

• ✅ 10 new variables for PA TANF benefit calculation
• ✅ 12 parameter files covering 4 county groups, FSA tables, Standard of Need, and deductions
• ✅ 72 comprehensive test cases across 9 test files (13 integration + 59 unit tests)
• ✅ Formula validated against real-world Just Harvest example
• ✅ All tests passing

Correct Formula (Per PA DHS Cash Assistance Handbook Section 160.22)

For EID-eligible individuals (enrolled OR passes Standard of Need test):
  1. Apply 50% Earned Income Disregard to GROSS earned income
  2. Subtract $200 Work Expense Deduction
  
For non-EID-eligible individuals:
  Full earned income is countable (no deductions)
  
Monthly Benefit = MAX(Family Size Allowance - Countable Income, 0)

Formula Correction: Latest commit fixes deduction order to match PA DHS policy exactly. The $90 deduction is used only for EID eligibility testing, not benefit calculation.

---

Files Added

Parameters (12 files)

policyengine_us/parameters/gov/states/pa/dhs/tanf/
├── county_group/                                   # 4 files
│   ├── group_1.yaml
│   ├── group_2.yaml
│   ├── group_3.yaml
│   └── group_4.yaml
├── family_size_allowance/                          # 2 files
│   ├── additional_person.yaml                      # $83 increment for 7+
│   └── amount.yaml                                 # FSA by group (1-6 people)
├── income/
│   └── deductions/                                 # 3 files
│       ├── earned_income_disregard/
│       │   └── percentage.yaml                     # 50% disregard
│       └── work_expense/
│           ├── additional.yaml                     # $200 (WED)
│           └── initial.yaml                        # $90 (eligibility test only)
├── standard_of_need/                               # 2 files
│   ├── additional_person.yaml                      # $102 increment for 7+
│   └── amount.yaml                                 # Standard by group (1-6 people)
└── resource_limit.yaml                             # 1 file ($1,000)

Variables (10 files)

policyengine_us/variables/gov/states/pa/dhs/tanf/
├── eligibility/                                    # 4 files
│   ├── pa_tanf_disregard_eligible.py               # EID eligibility test
│   ├── pa_tanf_eligible.py                         # Overall eligibility
│   ├── pa_tanf_income_eligible.py                  # Income < FSA test
│   └── pa_tanf_resource_eligible.py                # Assets <= $1,000 test
├── income/                                         # 2 files
│   ├── pa_tanf_countable_income.py                 # Total countable income
│   └── pa_tanf_earned_income_after_deductions_person.py  # EID + WED per person
├── pa_tanf_county_group.py                         # Geographic group assignment
├── pa_tanf_maximum_benefit.py                      # FSA calculation
├── pa_tanf_standard_of_need.py                     # Standard of Need
└── pa_tanf.py                                      # Main benefit calculation

Tests (9 files, 72 test cases total)

policyengine_us/tests/policy/baseline/gov/states/pa/dhs/tanf/
├── eligibility/                                    # 4 files, 27 tests
│   ├── pa_tanf_disregard_eligible.yaml             # 8 tests
│   ├── pa_tanf_eligible.yaml                       # 6 tests
│   ├── pa_tanf_income_eligible.yaml                # 7 tests
│   └── pa_tanf_resource_eligible.yaml              # 6 tests
├── income/                                         # 2 files, 15 tests
│   ├── pa_tanf_countable_income.yaml               # 8 tests
│   └── pa_tanf_earned_income_after_deductions_person.yaml  # 7 tests
├── integration.yaml                                # 13 integration tests
├── pa_tanf_maximum_benefit.yaml                    # 11 tests (sizes 1-12)
└── pa_tanf.yaml                                    # 6 tests

---

Example Calculations

Real-World Verification: Just Harvest Example

Household: Family of 3 (1 parent, 2 children), enrolled in TANF
Income: $580/month employment income

Step 1: Apply 50% EID to gross income
        $580 × 50% = $290

Step 2: Subtract $200 WED
        $290 - $200 = $90 countable income

Step 3: Calculate benefit
        FSA for family of 3 = $403
        Benefit = $403 - $90 = $313/month
        
Total household income: $580 + $313 = $893/month ✓ VERIFIED

Source: Just Harvest - PA TANF Policy Analysis (Sept 2020)

Multiple Earners Example

Household: Family of 4 (2 parents, 2 children), both working
Income: Parent 1 = $1,000/month, Parent 2 = $800/month

Parent 1: $1,000 × 50% - $200 = $300 countable
Parent 2: $800 × 50% - $200 = $200 countable
Total countable: $500

FSA for family of 4 = $497
Income exceeds FSA → Benefit = $0

---

Testing & Verification

Test Results

✅ All 72 tests passing across 9 test files
   - 13 integration tests
   - 59 unit tests
   - 0 failures

Test Coverage Breakdown

Test File	Count	Purpose
integration.yaml	13	End-to-end scenarios
pa_tanf_maximum_benefit.yaml	11	FSA for sizes 1-12
pa_tanf_disregard_eligible.yaml	8	EID eligibility rules
pa_tanf_countable_income.yaml	8	Income calculations
pa_tanf_income_eligible.yaml	7	Income thresholds
pa_tanf_earned_income_after_deductions_person.yaml	7	Deduction steps
pa_tanf.yaml	6	Main benefit formula
pa_tanf_eligible.yaml	6	Overall eligibility
pa_tanf_resource_eligible.yaml	6	Resource limits
Total	72

How to Run Tests

# All PA TANF tests
policyengine-core test policyengine_us/tests/policy/baseline/gov/states/pa/dhs/tanf/ -c policyengine_us

# Integration tests only
policyengine-core test policyengine_us/tests/policy/baseline/gov/states/pa/dhs/tanf/integration.yaml -c policyengine_us

---

Implementation Highlights

Key Features Implemented

• ✅ Family Size Allowance (FSA) by county group (4 groups supported)
• ✅ Earned income deductions (50% EID + $200 WED)
• ✅ Earned Income Disregard (EID) eligibility rules
• ✅ Standard of Need test for new applicants
• ✅ Resource limits ($1,000)
• ✅ Demographic eligibility (using federal TANF rules)
• ✅ Self-employment income support
• ✅ Multiple earner households

Geographic Variations

Pennsylvania has 4 benefit groups implemented (5 groups exist, Group 5 TBD):

• Group 1: $421/month (family of 3) - Highest
• Group 2: $403/month (family of 3) - Philadelphia (default)
• Group 3: $393/month (family of 3)
• Group 4: $365/month (family of 3)

Design Decisions

1. Vectorization: All formulas use where(), max_(), min_() for proper array handling
2. Per-person deductions: Each person's earned income processed individually, then summed
3. Federal rule reuse: Uses is_demographic_tanf_eligible and is_citizen_or_legal_immigrant from federal TANF
4. County default: GROUP_2 (Philadelphia) used if county not specified

---

Known Limitations & Future Enhancements

Not Yet Implemented

1. Child care deductions (55 Pa. Code § 181.311) - Can be added as enhancement
2. 60-month lifetime limit - Requires time-series tracking
3. County Group 5 - Needs additional research for benefit amounts
4. Personal expense deductions - For incapacitated adult care
5. Sanction tracking - Sanctioned members can still receive WED if EID eligible

Simplified Assumptions

• County defaults to GROUP_2 if not specified
• Uses federal demographic eligibility rules
• is_tanf_enrolled boolean (no historical tracking)
• Monthly calculations (4.0 weekly multiplier handled at input level)

---

References

Official Government Sources

• PA DHS Cash Assistance Handbook Section 160.2 - Income deductions
• 55 Pa. Code § 183.94 - EID eligibility
• 55 Pa. Code § 183.91 - Deductions
• 55 Pa. Code § 183.22 - Self-employment
• Section 168, Appendix B - FSA tables

Real-World Validation

• Just Harvest - PA TANF Policy Analysis (Nov 2020) - $200 WED implementation

Research Sources

• NCCP Pennsylvania TANF Profile 2024
• Single Mother Guide - PA TANF

---

Branch Information

Branch: pa-tanf-simple
Base: master
Status: ✅ Formula corrected, all 72 tests passing, ready for review

---

Recent Changes (Commit f073110)

Formula Correction

Issue: Original implementation applied income deductions in wrong order
Fix: Corrected to match PA DHS Cash Assistance Handbook Section 160.22

Before (incorrect):

$1,000 - $90 = $910
$910 × 50% = $455
$455 - $200 = $255 countable

After (correct):

$1,000 × 50% = $500 (EID to gross income)
$500 - $200 = $300 countable

Impact:

• Formula now matches PA DHS policy exactly
• Over-estimated benefits by ~$45/month in old formula
• All 72 test values recalculated and verified
• Real-world Just Harvest example validates correctness

---

Implementation by: @hua7450
Issue: #6759
Ready for: Code review and testing feedback

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (6c8cb6a) to head (32e3099).
⚠️ Report is 37 commits behind head on master.

Additional details and impacted files

@@             Coverage Diff              @@
##           master     #6764       +/-   ##
============================================
+ Coverage   72.92%   100.00%   +27.07%     
============================================
  Files        3252        12     -3240     
  Lines       46840       189    -46651     
  Branches      243         0      -243     
============================================
- Hits        34159       189    -33970     
+ Misses      12667         0    -12667     
+ Partials       14         0       -14     

Flag	Coverage Δ
unittests	100.00% <100.00%> (+27.07%)	⬆️

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.