Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Resolve US state and congressional-district regions to the ACS local-area dataset

Open
  • Is something wrong?
#551 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
48/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
python
Domain
data-engineering

Research direction

Start with src/policyengine/countries/us/regions.py lines 46–90 and src/policyengine/data/bundle/manifest.json, then inspect the existing populace_us_2024_acs_local overlay registration from #471. Done means state and congressional-district regions resolve through the pinned ACS local-area dataset with their dataset_path values, while the loading contract is agreed with the simulation API issue #717.

Written by the indexing model from the issue text.

Description

Problem

US state and congressional-district regions filter the sparse national default file; no region resolves to the ACS local-area dataset.

On main (bundle us-6.2.1):

  • src/policyengine/countries/us/regions.py builds state regions (lines 46–60) and congressional-district regions (lines 63–90) with a RowFilterStrategy and no dataset_path, so they inherit the national region's populace_us_2024.h5.
  • src/policyengine/data/bundle/manifest.json → data_releases.us.region_datasets contains only national.
  • The local-area build is registered as the named non-default overlay populace_us_2024_acs_local (#471), pinned to populace-us-2024-buildo-acs-local-77e2061-20260724T110908Z, but nothing selects it for a region.

#437 previously resolved state regions to per-state policyengine-us-data files; since those retired, state reports in the app run on the national file. The API's deployed bundle (policyengine[models]==5.2.0) stamps state reports with populace-us-2024-buildp-sparse-rmloss100-cae8640-20260728T011454Z.

Evidence: Pennsylvania

Kish effective sample size, ESS = (Σw)² / Σw², 2026 baseline.

PA slice Sparse national, app pair (buildp-sparse-rmloss100-cae8640, policyengine-us 1.764.6) ACS local-area (buildo-acs-local-767312d60, policyengine-us 2.19.0)
Household records 1,999 64,981
Records holding 90% of weight 288 13,346
ESS, all households 314 558
ESS, households with children 120 234
ESS, poor SPM units with children 15.4 28.8
ESS, poor SPM units with children under 6 5.2 10.5
Median congressional-district ESS, all households 18 34

What this does to results: Children First PA (via the PA CTC analysis) asked why a Pennsylvania refundable credit for children under 6 showed almost no poverty or child poverty impact at any amount. On the app's data pair, poor SPM units with children under 6 whose poverty gap is at most $1,000 per child under 6 carry 0 weighted units. At $2,200 per child they carry 2. So no credit up to $2,200 can lift a family over the line in that data. On the local-area file the same groups carry 7,582 and 10,755 weighted units (ESS 1.6 and 3.1).

Proposed change

  1. Add region_datasets entries for state and congressional_district that resolve to populace_us_2024_acs_local.h5 through the overlay's own repo, revision and sha256. Set dataset_path on state and district regions and keep the existing RowFilterStrategy.
  2. Bump the overlay pin from the Jul 24 Build O (77e2061) to the Sep 23 build populace-us-2024-buildo-acs-local-767312d60-20260923T074941Z (or Build P 592ae5d6). In 77e2061's calibration_diagnostics.json, Pennsylvania taxable-interest targets miss by +178% (all returns) to +523% (AGI $200k–$500k). 767312d60 fits 94 of 96 Pennsylvania targets within 10%. Its misses are net capital gains returns (−34%) and taxable interest under $1 of AGI (−19%).
  3. Agree the loading contract with the simulation API (sibling issue): the national local-area file is 9.8 GB.

The local-area file improves the effective sample but still concentrates weight (the top 1% of PA records hold 69% of it). That calibration question is tracked in PolicyEngine/microcosm#403.

Related

🤖 Generated with Claude Code

Dominant language
Python
Stars
8
Forks
9
Avg merge
15h 28m
Merged PRs (30d)
13

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from PolicyEngine/policyengine.py

All issues in PolicyEngine/policyengine.py

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.