Skip to content

Conversation

@anth-volk
Copy link
Contributor

Fixes #216

Summary

Adds congressional district-level breakdowns to US state-level simulation results, mirroring the existing UK parliamentary constituency breakdown functionality.

Changes

Core Implementation

policyengine/outputs/macro/single/calculate_single_economy.py

  • Added congressional_district_geoid: List[int] | None to SingleEconomy model
  • Added calculate_congressional_district_geoid() method to GeneralEconomyTask

policyengine/outputs/macro/comparison/calculate_economy_comparison.py

  • Added USCongressionalDistrictImpact model (per-district results)
  • Added USCongressionalDistrictBreakdownWithValues model (list of districts)
  • Added us_congressional_district_breakdown() function using identical formulas to UK constituencies
  • Added congressional_district_impact field to EconomyComparison
  • Added geoid_to_district_name() helper to convert SSDD format to "GA-05" style names
  • Added STATE_FIPS_TO_ABBREV mapping

Tests

tests/country/test_us_congressional_districts.py (new file)

  • 16 tests following given-when-then naming pattern
  • Tests for geoid conversion, breakdown calculation, edge cases
  • Integration test verifying real GA dataset works

tests/fixtures/simulation.py

  • Added create_mock_single_economy() helper
  • Added mock fixtures for GA districts, multi-state districts, empty/null cases

tests/conftest.py and tests/fixtures/__init__.py

  • Added to properly expose fixtures

Output Format

{
  "congressional_district_impact": {
    "districts": [
      {
        "district": "RI-01",
        "average_household_income_change": 320.73,
        "relative_household_income_change": 0.001944
      },
      {
        "district": "RI-02",
        "average_household_income_change": 199.13,
        "relative_household_income_change": 0.001132
      }
    ]
  }
}

Verification

Tested with Rhode Island (2 districts) - making CTC fully refundable:

  • ✓ Returns exactly 2 districts (RI-01, RI-02)
  • ✓ District names formatted correctly
  • ✓ Numerical values are floats
  • ✓ Relative changes are decimals (not percentages)

Formula Confirmation

The district-level calculations use identical formulas to UK parliamentary constituencies:

Metric Formula
average_household_income_change (reform.sum() - baseline.sum()) / baseline.count()
relative_household_income_change reform.sum() / baseline.sum() - 1

Test Plan

  • Unit tests for geoid_to_district_name()
  • Unit tests for us_congressional_district_breakdown() with mocked data
  • Integration test with real GA state dataset
  • Manual verification with RI state simulation

anth-volk and others added 3 commits January 14, 2026 23:44
- Add congressional_district_geoid to SingleEconomy model
- Add us_congressional_district_breakdown() function mirroring UK constituency logic
- Add USCongressionalDistrictImpact and USCongressionalDistrictBreakdownWithValues models
- Add congressional_district_impact field to EconomyComparison
- Add comprehensive tests following given-when-then naming pattern
- Add mock fixtures for district testing

The district-level calculations use identical formulas to UK parliamentary
constituencies:
- average_household_income_change = (reform.sum() - baseline.sum()) / count()
- relative_household_income_change = reform.sum() / baseline.sum() - 1

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@anth-volk anth-volk changed the base branch from main to 0.x January 14, 2026 21:19
anth-volk and others added 2 commits January 15, 2026 00:24
- Move STATE_FIPS_TO_ABBREV mapping to utils/geography.py
- Move geoid_to_district_name() function to utils/geography.py
- Update imports in calculate_economy_comparison.py and tests

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@anth-volk anth-volk marked this pull request as ready for review January 14, 2026 22:10
@anth-volk anth-volk merged commit 1d95989 into 0.x Jan 14, 2026
3 checks passed
@anth-volk anth-volk deleted the feat/congressional-district-breakdown branch January 14, 2026 22:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add district breakdowns to state-level simulations

2 participants