Add comprehensive SNAP utility allowance data (FY2019-FY2026, sub-regions, household size)

[MaxGhenis]

Summary

Ref #7741

New data

• Add FY2019, FY2023, and FY2026 SNAP utility allowance values for all 53 states/territories
• FY2019 covers all allowance types: HCSUA (standard), LUA (limited), and all 6 individual utility allowances (electricity, gas/fuel, phone, sewage, trash, water)
• Total coverage is now FY2019, FY2022–FY2026; FY2020 and FY2021 are not yet available
• Split Alaska into 6 SNAP utility sub-regions (Central, Northern, Northwest, Southcentral, Southeast, Southwest) per 7 AAC 45.531, with county-to-region mapping
• Split New York into 3 sub-regions (Nassau/Suffolk, NYC, Other NY) with county mapping
• Add household-size-based SUA and BUA for AZ, TN, VA (NC was already modeled)
• Add HI and GU individual utility allowances (electricity, gas, water) that vary by household size
• Rename participating_states → states parameter files for clarity

Bug fixes

• Fix Maryland SUA/LUA effective dates from October 1 to January 1 (Maryland uses calendar-year cycle, not federal fiscal year); corrected 2023 SUA value from $551 to $505; added missing 2020 and 2025 entries
• Fix Indiana SUA values and effective dates per IN DFR policy transmittals
• Fix Alaska region values and date entries
• Fix Wyoming YAML formatting
• Fix missing FY2019 LUA and individual utility allowance entries for all states (were only added to HCSUA); update LUA test expectation for CA 2021 (432 → 1602, now correctly reflects FY2019 CA LUA of $130)
• Add household-size floor guard (max_(1, min_(10, size))) in snap_standard_utility_allowance, snap_limited_utility_allowance, and snap_individual_utility_allowance to prevent ParameterNotFoundError when spm_unit_size is 0
• Fix FY2026 LUA/IUA data swap for 10 states/regions (AR, IA, LA, MA, OK, TX, UT, NY_NAS, NY_NYC, NY_ONY) — bogus LUA values were placed in IUA fields and LUA values were zeroed out
• Fix by_household_size/states.yaml effective date from 2024-01-01 to 2023-10-01 to match amount data (AZ/TN had household-size-varying SUA since at least FY2019 per USDA spreadsheets)
• Fix SNAPUttilityAllowanceType typo → SNAPUtilityAllowanceType

Cleanup

• Remove unit: USD from boolean parameter files (states.yaml, active.yaml, etc.)
• Fix name: → title: in parameter reference metadata
• Apply underscore formatting to numeric values across all parameter files
• Add FY2019 USDA SUA spreadsheet reference to all 8 parameter files
• Add missing reference: section to limited/active.yaml
• Refactor AK/NY county-to-region mappings to dict comprehensions

Related issues

• Add missing Alaska boroughs to county_enum.py (Haines, Petersburg) #7744 — Missing AK boroughs (Haines, Petersburg) in county_enum.py
• Track OBBBA "Heat and Eat" HCSUA eligibility change for FY2026 #7745 — OBBBA "Heat and Eat" HCSUA eligibility change starting FY2026

Data sourced from USDA SNAP utility allowance spreadsheets (including SNAP-SUA-Table-FY2019.xlsx via Wayback Machine) and snapscreener.com.

Test plan

• All existing SNAP tests pass
• 11 new region/sub-region tests (AK sub-regions, NY sub-regions, HI/GU household-size IUA)
• AK Anchorage end-to-end integration test (county → region → SUA amount)
• Wrong-allowance-type-returns-zero tests for SUA and LUA
• Household size zero edge case test (verifies floor guard)
• CI passes

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (406df75) to head (76a2cfd).
⚠️ Report is 116 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##              main     #7726    +/-   ##
==========================================
  Coverage   100.00%   100.00%            
==========================================
  Files            1         7     +6     
  Lines           23       215   +192     
  Branches         1         6     +5     
==========================================
+ Hits            23       215   +192     

Flag	Coverage Δ
unittests	100.00% <100.00%> (ø)

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.

[MaxGhenis]

Microsim impact analysis

Ran household-level examples comparing 2024 vs 2026 values — all features working correctly:

SUA examples:

State	2024 SUA	2026 SUA	Change
CA	$7,299	$7,956	+$657 (+9.0%)
NC HH3 (by HH size)	$8,607	$9,216	+$609 (+7.1%)
AK (Southcentral sub-region)	$7,053	$7,092	+$39 (+0.6%)
NY (Other NY sub-region)	$9,933	$10,524	+$591 (+6.0%)

IUA examples:

State	2024 IUA	2026 IUA	Change
HI HH2 (by HH size)	$11,331	$11,608	+$277
AK (Southcentral)	$7,053	$7,132	+$79

Aggregate microsim (Enhanced CPS): Utility expense variables (electricity_expense, gas_expense, etc.) are all zero in the current microdata, so the aggregate SNAP impact is near-zero. The parameters are correct and verified at the household level — the microdata gap is tracked separately.

[hua7450]

Program Review: PR #7726 -- Add comprehensive SNAP utility allowance data

Source Documents

• PDF 1: Alaska FSP-77 FY2026 (2 pages)
• PDF 2: Indiana SNAP/TANF Policy Manual Ch. 3000 (9 pages)
• PDF 3: USDA FNS FY2026 COLA Memo (7 pages)
• PDF 4: California CalFresh FY2026 COLA (8 pages)
• Excel: USDA FNS FY2025 SUA Table
• Year: FY2019-FY2026
• Scope: PR changes only

---

Critical (Must Fix)

1. WY FY2026 SUA value orphaned after metadata block

   • File: policyengine_us/parameters/gov/usda/snap/income/deductions/utility/standard/main.yaml (line 493)
   • The entry 2025-10-01: 510 appears AFTER the metadata: block instead of under the WY: key. The YAML parser will attach this value to the metadata dict, meaning Wyoming has no FY2026 SUA value. Any WY SNAP calculation after Oct 2025 returns FY2025 value ($497) instead of the correct $510.
   • Found independently by: reference-checker (C1) and code-validator (Critical).
   • Fix: Move 2025-10-01: 510 under the WY: key before the metadata: block.

2. Indiana SUA (SUA 1) FY2025 value is wrong: $502 should be $473

   • File: policyengine_us/parameters/gov/usda/snap/income/deductions/utility/standard/main.yaml (line 177)
   • Repo has 2024-10-01: 502. The Indiana FSSA Policy Manual Section 3020.00.00 (PDF 2, p.6) states SUA 1 = $473 from 5/1/2024 through 9/30/2025. The $502 value does not appear in any Indiana source -- it matches Oregon/Washington FY2025 values and was likely a data extraction error.
   • Confirmed at 600 DPI against PDF 2, p.6.
   • Impact: $29/month overstatement (+6.1%) for Indiana SNAP households from 10/1/2024 through 9/30/2025.
   • Found independently by: IN/CA PDF auditor (B.1) and reference-checker (C2).
   • Fix: Remove the 2024-10-01: 502 entry. The existing 2023-05-01: 473 remains in effect through 9/30/2025.

3. Indiana LUA (SUA 2) FY2025 value is wrong: $274 should be $276

   • File: policyengine_us/parameters/gov/usda/snap/income/deductions/utility/limited/main.yaml (line 139)
   • Repo has 2024-05-01: 274. The Indiana FSSA Policy Manual Section 3020.00.00 (PDF 2, p.6) states SUA 2 = $276 from 5/1/2024 through 9/30/2025.
   • Confirmed at 600 DPI against PDF 2, p.6.
   • Impact: $2/month understatement for Indiana SNAP households from 5/1/2024 through 9/30/2025.
   • Fix: Either remove the 2024-05-01: 274 entry (since $276 from 2023-05-01 remains in effect) or correct to 2024-05-01: 276.

4. Alaska county mapping: 3 boroughs/census areas incorrectly assigned to South Central (should be Southwest)

   • File: policyengine_us/variables/gov/usda/snap/snap_utility_region.py (lines 89-96)
   • BRISTOL_BAY_BOROUGH_AK, DILLINGHAM_CENSUS_AREA_AK, and LAKE_AND_PENINSULA_BOROUGH_AK are mapped to AK_SOUTHCENTRAL but Alaska FSP-77 (PDF 1, p.2) lists them under the "Southwestern Utility Region (SW)."
   • All 3 confirmed at 600 DPI against FSP-77 p.2.
   • Impact: Affected households receive South Central SUA ($591 FY2026) instead of correct Southwest SUA ($1,064 FY2026) -- a $473/month understatement.
   • Fix: Move these 3 entries from AK_SOUTHCENTRAL to AK_SOUTHWEST in snap_utility_region.py.

5. Alaska county mapping: 2 boroughs missing from Southeast region (default to Central)

   • File: policyengine_us/variables/gov/usda/snap/snap_utility_region.py (lines 99-113)
   • HAINES_BOROUGH_AK and PETERSBURG_BOROUGH_AK are not in any region mapping list. They default to AK_C (Central) via the fallback logic. Alaska FSP-77 (PDF 1, p.2) lists both under the "Southeastern Utility Region (SE)."
   • Both confirmed at 600 DPI against FSP-77 p.2.
   • Note: HAINES_BOROUGH_AK and PETERSBURG_BOROUGH_AK may also be missing from the county enum (county_enum.py); if so, they must be added there first.
   • Impact: Affected households receive Central SUA ($625 FY2026) instead of correct Southeast SUA ($517 FY2026).
   • Fix: Add both to the AK_SOUTHEAST list in snap_utility_region.py (and to county_enum.py if absent).

6. County-to-region mapping formula has zero test coverage

   • File: policyengine_us/variables/gov/usda/snap/snap_utility_region.py (formula method)
   • Tests: snap_utility_region.yaml (1 test for IL pass-through only)
   • The snap_utility_region formula contains the most complex new logic in this PR: mapping state_code + county_str to 6 AK sub-regions and 3 NY sub-regions using nested where() calls. Not a single test exercises this code path with AK or NY county inputs. This means the 5 county mapping errors above (items 4-5) could not have been caught by the test suite.
   • Priority: P0 from test coverage agent.
   • Fix: Add tests for at least: one AK county per region, AK default fallback, one NY NYC county, one NY Nassau/Suffolk county, one NY other county.

7. FY2026 values for ~45 states rely on snapscreener.com estimates (not official sources)

   • Files: standard/main.yaml, limited/main.yaml, all single/*.yaml
   • Only 5 states have officially verified FY2026 values (CA, IL, IN, NY, TX). The remaining ~45 states use snapscreener.com estimates based on the USDA-approved 2.7% CPI-U adjustment. Several outlier states show increases inconsistent with the 2.7% methodology and are unverified:
     • NJ: +11.3% ($878 -> $977)
     • PA: +13.1% ($758 -> $857)
     • ME: +4.7% ($1,047 -> $1,096)
     • ND: +0.9% ($765 -> $772)
   • The working_references.md transparently documents which values are estimates vs. official.
   • Severity note: This is informational for FY2025 and earlier values (all verified), but the unverified outlier FY2026 values for NJ, PA, ME, ND warrant a follow-up issue.

---

Should Address

1. No tests for AZ, TN, or VA household-size-varying SUA

   • Files: snap_standard_utility_allowance.yaml
   • The standard/by_household_size/states parameter lists AZ, NC, TN, VA. Only NC is tested. No test verifies the AZ size 3/4 tier boundary (314 vs 426), TN per-person SUA schedule (439-586), or VA size 3/4 tier boundary (369 vs 467).

2. No tests for AZ or TN household-size-varying LUA

   • Files: snap_limited_utility_allowance.yaml
   • The limited/by_household_size/states parameter lists AZ, NC, TN. Only NC is tested.

3. No tests verifying AK/NY sub-regions produce different SUA values

   • The IUA test covers AK_C only. No test verifies that AK_NW returns 1,078 vs AK_SE returning 503, or that NY_NYC returns 1,034 vs NY_ONY returning 854.

4. Hard-coded MAX_SPM_SIZE = 10 in 3 variable files (pre-existing)

   • Files: snap_individual_utility_allowance.py, snap_standard_utility_allowance.py, snap_limited_utility_allowance.py
   • Should be parameterized, though it is tied to the parameter table dimension (sizes 1-10) and is functionally correct.

5. spm_unit_size accessed with period instead of period.this_year (pre-existing)

   • Files: same 3 variable files as above
   • spm_unit_size is YEAR-defined. Using period from a MONTH formula triggers auto-conversion (divides by 12), which is semantically incorrect for a count variable. May work correctly in practice due to framework handling.

6. documentation field used instead of reference in variable files (pre-existing)

   • Files: snap_utility_region.py, snap_individual_utility_allowance.py, snap_standard_utility_allowance.py, snap_limited_utility_allowance.py
   • Per PolicyEngine standards, variables should use a reference field with a URL rather than plain-text documentation.

7. unit = USD on boolean variables (pre-existing)

   • Files: snap_limited_utility_allowance_by_household_size.py, snap_standard_utility_allowance_by_household_size.py
   • Boolean variables should not have unit = USD.

8. Parameter references use name: instead of title: (pre-existing)

   • Files: 8 existing parameter YAML files (all under standard/ and limited/ and single/)
   • PolicyEngine parameter patterns specify title: as the reference field name. The new by_household_size/ files correctly use title:.

9. Maryland SUA effective dates changed from January to October

   • File: standard/main.yaml
   • The USDA FY2025 Excel footnote states Maryland's SUA is effective January 1. The PR changes pre-FY2023 MD entries from January-based to October-based dates, contradicting the official guidance.

10. No FY2026-specific USDA reference in parameter metadata

    • All files receiving FY2026 values lack a corresponding FY2026 reference in their metadata blocks.

11. standard/by_household_size/amount.yaml has only one reference (snapscreener)

    • This file should also reference the official USDA FNS SUA spreadsheet.

12. Colorado inline references missing #page=XX (pre-existing)

    • Files: standard/main.yaml, limited/main.yaml
    • CO entries reference a 227-page dynamically-generated PDF without page numbers.

---

Suggestions

1. Add integration test for full county-to-allowance chain

   • Test the end-to-end flow: state_code + county_str -> snap_utility_region -> snap_utility_region_str -> snap_standard_utility_allowance for an AK or NY household.

2. Add test for household size = 0 edge case

   • The formulas use min_(MAX_SPM_SIZE, spm_size) but never max_(1, ...). Querying size-dependent parameters with key 0 could produce unexpected behavior.

3. Add test for wrong allowance type returns zero

   • No test confirms that the SUA formula returns 0 when snap_utility_allowance_type: IUA, or vice versa.

4. Guam IUA error margin of 3 could be tightened

   • The GU tests use absolute_error_margin: 3 -- this could be tightened once official FY2025 GU values are confirmed.

5. Inconsistent test naming conventions

   • New tests use different naming styles than pre-existing ones. Minor style issue.

6. Google Sheets link for FY2024 data

   • Six files reference a Google Sheets copy of the USDA FY2024 SUA table because the original USDA URL returned 404. The reference should note it is a cached/archived copy.

7. Create follow-up issue for OBBBA "Heat and Eat" policy change

   • The OBBBA / H.R. 1 change restricting HCSUA eligibility for non-elderly/non-disabled LIHEAP-only households starting FY2026 affects the snap_utility_allowance_type formula logic, not the dollar amounts in this PR. Worth tracking separately.

8. Copper River Census Area split is a known granularity limitation

   • The FSP-77 splits the Copper River Census Area between Northern (specific communities) and South Central (Chugach subarea communities). The repo cannot model this since it uses county/borough/census-area as the smallest geographic unit. Informational only.

---

PDF Audit Summary

Category	Count
Confirmed correct	84
Mismatches (confirmed + visually verified at 600 DPI)	7
Unverifiable items (gas/trash FY2026 AK -- not in FSP-77)	12

Breakdown of confirmed correct values:

• Alaska FY2025 SUA: 6 regions (all match USDA FY2025 Excel)
• Alaska FY2026 SUA: 6 regions (all match FSP-77 p.2)
• Alaska FY2025 individual utilities: 30 values (6 regions x 5 types, all match USDA Excel)
• Alaska FY2026 individual utilities (electricity, phone, sewer, water): 24 values (all match FSP-77 p.2)
• Alaska FY2025 gas_and_fuel: 6 regions (all match USDA Excel)
• Alaska LUA/BUA: all regions confirmed zero (correct)
• Indiana FY2026 (SUA 1-4): 4 values (all match PDF 2)
• Indiana FY2025 (SUA 3, SUA 4): 2 values (match PDF 2)
• California FY2026 (SUA, LUA, TUA): 3 values (all match PDF 4)
• California FY2025 (SUA, LUA, TUA): 3 values (all match PDF 4)

Breakdown of 7 confirmed mismatches:

1. IN SUA 1 (HCSUA): repo $502, correct $473 (confirmed PDF 2 p.6 at 600 DPI)
2. IN SUA 2 (LUA): repo $274, correct $276 (confirmed PDF 2 p.6 at 600 DPI)
3. AK BRISTOL_BAY_BOROUGH mapped to SC, correct is SW (confirmed FSP-77 p.2 at 600 DPI)
4. AK DILLINGHAM_CENSUS_AREA mapped to SC, correct is SW (confirmed FSP-77 p.2 at 600 DPI)
5. AK LAKE_AND_PENINSULA_BOROUGH mapped to SC, correct is SW (confirmed FSP-77 p.2 at 600 DPI)
6. AK HAINES_BOROUGH missing from SE region mapping (confirmed FSP-77 p.2 at 600 DPI)
7. AK PETERSBURG_BOROUGH missing from SE region mapping (confirmed FSP-77 p.2 at 600 DPI)

---

Validation Summary

Check	Result
Regulatory Accuracy	2 value mismatches (IN SUA, IN LUA), 5 county mapping errors (AK), 1 structural issue (WY YAML)
Reference Quality	FY2019-FY2025 fully traceable; FY2026 partially traceable (~45 states from snapscreener)
Code Patterns	4 pre-existing warnings (hard-coded constant, period usage, documentation field, unit mismatch); no new violations
Test Coverage	P0: county mapping formula untested; P1-P2: AZ/TN/VA SUA/LUA, sub-region differentiation untested
PDF Value Audit	7 mismatches / 84 confirmed correct / 12 unverifiable
CI Status	Passing (codecov warnings only)

---

Review Severity: REQUEST_CHANGES

Rationale: 6 critical issues require code changes:

• 1 structural YAML error (WY data loss)
• 2 confirmed value mismatches (IN SUA $502->$473, IN LUA $274->$276)
• 5 confirmed county mapping errors (3 wrong region, 2 missing)
• County mapping formula has zero test coverage (the feature most likely to contain bugs, and it does)

These are not edge cases or informational notes. The Indiana and Alaska issues produce materially incorrect SNAP benefit calculations for affected households.

---

Next Steps

To auto-fix issues: /fix-pr 7726

Priority order for fixes:

1. WY YAML: move 2025-10-01: 510 under WY: key (1 line move)
2. IN SUA: remove 2024-10-01: 502 from standard/main.yaml (1 line deletion)
3. IN LUA: remove 2024-05-01: 274 from limited/main.yaml (or correct to 276)
4. AK county mapping: move Bristol Bay, Dillingham, Lake and Peninsula from AK_SOUTHCENTRAL to AK_SOUTHWEST in snap_utility_region.py
5. AK county mapping: add Haines Borough and Petersburg Borough to AK_SOUTHEAST list (may require additions to county_enum.py)
6. Add county mapping tests for snap_utility_region (AK and NY county inputs)

[hua7450]

See detailed review comment above. 6 critical issues require fixes before merge: WY YAML structural error, 2 Indiana value mismatches (confirmed at 600 DPI), 5 Alaska county mapping errors (confirmed against FSP-77), and zero test coverage for the county mapping formula.