policyengine-us icon indicating copy to clipboard operation
policyengine-us copied to clipboard
verified publisher icon PolicyEngine

Implement Pennsylvania TANF

Open hua7450 opened this issue 4 months ago • 1 comments

Summary

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

Closes #6759

Status

  • [x] Documentation collected
  • [x] Parameters created (12 files)
  • [x] Variables implemented (10 files)
  • [x] Tests written (72 test cases across 9 files)
  • [x] CI passing
  • [x] Formula corrected to match PA DHS policy
  • [x] Real-world validation completed
  • [x] 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

Real-World Validation

Research Sources

Branch Information

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

Recent Changes (Commit f0731102ef)

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

hua7450 avatar Nov 04 '25 07:11 hua7450

Codecov Report

:white_check_mark: All modified and coverable lines are covered by tests. :white_check_mark: Project coverage is 100.00%. Comparing base (dcf172c) to head (ce6e000). :warning: Report is 99 commits behind head on master.

Additional details and impacted files 
@@            Coverage Diff            @@
##            master     #6764   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            4        11    +7     
  Lines           92       172   +80     
  Branches         4         0    -4     
=========================================
+ Hits            92       172   +80
Flag Coverage Δ
unittests 100.00% <100.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

:rocket: New features to boost your workflow:
  • :snowflake: Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

codecov[bot] avatar Nov 04 '25 08:11 codecov[bot]