# Maine census database — README (v1.3, 2026-10-14 — v1.2 plus crosswalk rows for the 49 historical units added in election results v3.11; see "What changed in v1.3")

**What this is.** Every demographic figure the town pages use (population, median age, household income, home value, race and ethnicity, households, housing, work and income, education, veterans, and the rest of the "Who Lives Here" panels) — plus a much wider set — for **every geography the Census Bureau publishes for Maine**, tied to the project's `unit_id`s. The same figures can be produced for any custom group of towns with the included aggregation script.

**Geographies covered (734 current + 18 historical):**

| geo_level | count | what |
|---|---|---|
| `state` | 1 | Maine |
| `county` | 16 | counties |
| `congress` | 2 | U.S. House districts (current plan, 119th/120th Congress) |
| `state_senate` | 35 | State Senate districts, 2021 plan (Census "2024/2026 state legislative districts – upper") |
| `state_house` | 151 | State House districts, 2021 plan (lower) |
| `town` | 529 (+18 historical) | Census county subdivisions: every city, town and plantation, plus the Census's "UT" aggregates of unorganized townships, the Penobscot Indian Island reservation and Hibberts Gore |

The `town` level is the Census Bureau's *county subdivision*. It matches the SOS registration/election units (`unit_id`) one-for-one for all 493 organized cities, towns and plantations (`unit_census_crosswalk.csv`). The Bureau does **not** publish anything for individual unorganized townships: they are folded into 36 county-level "UT" aggregates (e.g. "South Aroostook UT"). So the 172 township units that appear only in the election files have no Census row of their own; the crosswalk says so on each and, since v1.2, names the Census UT that contains the township (`parent_ut_geoid`) wherever that can be derived (111 of 172). Places that de-organized or changed their Census code (Sanford, Verona Island, Westport Island, Bancroft, Drew, Codyville, Magalloway, Cary, Oxbow, Atkinson, Madrid, Centerville, the Penobscot reservation, Marshall Island) keep their old codes in `census_geographies.csv` as "historical only" with a `successor_geoid`; their 2000/2010 counts are carried on the current row (see v1.2).

## Files

| File | What it holds |
|---|---|
| `census_profile.csv` | **The main table.** One row per geography (734 rows), ~110 named indicators with margins of error and a reliability flag. Columns are listed in `census_profile_dictionary.csv`. Includes `unit_id` for towns. **Key: (`geo_level`, `geoid`)** — a `geoid` is unique only together with `geo_level` (86 rows share digits with a row at another level, e.g. congressional and legislative district codes). |
| `census_profile_dictionary.csv` | Every indicator: name, source Census variable, how it was computed, plain-English description. |
| `census_values_long.csv` | **Everything downloaded**, one row per geography × variable (1.04 million rows): the full ACS 2020–2024 data profiles DP02–DP05 (1,088 variables: estimate, margin of error, percent, percent margin) and 29 detailed tables (age/sex, race, nativity, commuting, household type, education, poverty, income distribution, medians, veterans, employment, tenure, rent and value distributions, internet, vacancy, disability, health insurance, Gini) at all six levels; the 2020 Census (DHC P1, P12, H1; PL P2, P3, P4), 2010 and 2000 Census (P1/P001, P12/P012, H1/H001) at state/county/town; and the ACS 2010–2014 and 2015–2019 vintages of nine key tables at state/county/town for trends. Columns: `geo_level, geoid, dataset, year, table, table_id, variable, estimate, moe, pct, pct_moe, annotation`. |
| `census_variables.csv` | Label, concept and type of every variable in the long table (from the Bureau's own metadata). |
| `census_geographies.csv` | The geography list: level, GEOID, name, county, district number, unit type, whether it is current or historical, and which datasets cover it; (v1.2) `successor_geoid` on the 18 historical rows and `history_note` on those rows and on every current row whose Census counts come from or include a predecessor code. |
| `unit_census_crosswalk.csv` | `unit_id` ↔ Census GEOID for all 800 project units (every unit in `registration-data/units.csv` and in the `units_election_additions.csv` inside election results v3.11: 538 + 262), with the relation (same place / historical only / no Census geography at this level / historical unit, no census geography) and, for townships, `parent_ut_geoid`, `parent_ut_name`, `parent_ut_basis`. |
| `town_district_crosswalk.csv` | Every town × U.S. House / State Senate / State House district it lies in under the current plan, with the 2020 Census population and housing units of the overlap and the share of the town's population in each district. Built from the 2020 Census blocks (see FLAGS). |
| `block_assignments.csv` | Every 2020 Census block in Maine (47,138) with its 2020 population and housing units and the town, county, U.S. House, State Senate and State House district it falls in. This is what lets any custom region — a district, a group of towns, half a city — be population-weighted correctly. |
| `aggregate.py` | Python: `region_profile([geoids], level)` builds the full indicator set for any set of towns (or counties, districts…) using the Census Bureau's own rules for combining estimates. Validated: summing Cumberland County's towns reproduces every published county percentage exactly and the medians within 0.1%. |
| `sources/` | The raw downloads (JSON as served by data.census.gov, the Vintage 2025 population-estimates CSV, TIGERweb block/district relationships) so every number can be traced. |

## Sources and vintages

* **ACS vintage in this release: ACS 2020–2024 5-year, released Dec 2025; next refresh Dec 2026** (ACS 2021–2025).
* **American Community Survey 5-year estimates, 2020–2024** (released December 2025) — the most recent; the only ACS product published for places under 65,000 people. Dollar figures are in 2024 dollars. Every estimate carries a 90% margin of error (`_moe`).
* **2020 Census** (PL 94-171 redistricting file and the Demographic and Housing Characteristics file), **2010 and 2000 Census** (Summary File 1) — actual counts, no margins.
* **Population estimates, Vintage 2025** (Census Bureau, released 2026): July 1 estimates 2020–2025 for the state, counties and every county subdivision (`pop_est_2020` … `pop_est_2025`). Not available for legislative or congressional districts.
* **TIGERweb** (Census Bureau's boundary service): 2020 blocks with population, the current legislative and congressional district boundaries.
* All of it was pulled from the Census Bureau's public data service (data.census.gov / api.census.gov metadata / www2.census.gov / tigerweb.geo.census.gov) on 2026-09-29.

## How to read the numbers

* **Margins of error matter for small towns.** An ACS 5-year estimate for a town of 1,000 people can have a margin of ±10 points on a percentage. `census_profile.csv` flags each figure: `ok` (coefficient of variation ≤ 15%), `medium` (15–30%), `low` (> 30%: don't quote it as a fact; show it greyed or with its ± range). The town pages already flag the widest ones (e.g. Yarmouth poverty 10.2% ± 8.4).
* **Percentages** in the profile are the Bureau's own published percentages (`pct`) with their own margins; **counts and medians** are the estimates (`estimate`) with their margins.
* **Medians cannot be added.** For a custom region use `aggregate.py`, which re-derives them from the underlying distributions (income bins, value bins, rent bins, age bins) the standard way; they will be within a percent or two of what the Bureau would publish.
* **Vacant housing** in Maine is mostly seasonal homes; `vacant_units_pct` includes them.
* **Unemployment** here is the ACS five-year average from a household survey; it runs higher than BLS's monthly rate.
* The Bureau's sentinel codes (−888,888,888 = not applicable, −666,666,666 = too few sample cases, −999,999,999 = suppressed) have been converted to blanks; the `annotation` column in the long table keeps the Bureau's symbol.

## Regions (added 2026-10-02)

`census_profile_regions.csv` is the same profile for the 12 Regions of Maine (`geo_level = region`, `geoid` = region id such as `GP`), made with `aggregate.py` from the county subdivisions in `geography/regions_census_cousub.csv`. Medians are re-derived from the distributions. Since v1.2 the region geoid lists use the same county-subdivision codes as `census_profile.csv`, and the decennial counts (2000/2010/2020 population, 18+, housing units) and the population estimates are sums of the profile rows, so every region total equals the sum of its towns and the 12 regions add up to the state for every count.

## Keeping it current

Each December the Bureau releases a new ACS 5-year vintage; the population estimates come each spring/summer. The pull is scripted: re-running the fetch for `ACSDP5Y2025.DP02–DP05` etc. and the build scripts (`build_long.py → build_profile.py → build_export.py`) regenerates everything.

## What changed in v1.3 (2026-10-14)

* **`unit_census_crosswalk.csv`: 49 rows added (751 → 800).** Election results v3.11 created units MPD-1033 to MPD-1081: places in the 1831–1839 Governor returns, the 1872–73 Annual Register and the 1892 abstract (Danville, Dearborn, Berlin, Wilson, Bloomfield, Seaville, Summit Plt and others) and 32 lines the tabulation books print but nobody has yet tied to a present-day place ("not identified"). Each is "historical unit, no census geography". Two carry a parent Census UT because the township that now covers them is a single GeoLibrary township: Summit Plt → Summit Twp → East Central Penobscot UT; Berlin → Township 6 North of Weld → West Central Franklin UT. Nine whose ground is now inside organized towns say so in `parent_ut_basis` (Clinton Gore → Clinton, Danville → Auburn, Bloomfield → Skowhegan, and so on). The README's "every unit" claim is true again. (Audit II, GC-5.)
* `FLAGS.md` §1: deorganization years corrected to the State Auditor's list (Oxbow 2017, not 2016; Drew 2023, not 2019; Magalloway 2021). No data changed. (GC-8.)
* No figures changed. Script: `fix_v1_3_census.py` (reads the v1.2 crosswalk, the census block table, the geography block table and the v3.11 unit additions).

## What changed in v1.2 (2026-10-05)

* **Current geoids for three de-organized places.** The 2020 Census still tabulated Drew plantation (2301918580), Codyville plantation (2302913610) and Magalloway plantation (2301742835); the ACS 2020–2024 profile uses Drew UT (2301918582), Codyville UT (2302913612) and North Oxford UT (2301752575, which absorbed Magalloway). `block_assignments.csv` (91 blocks), `town_district_crosswalk.csv` (1,662 → 1,659 rows) and the region geoid lists now use the profile's codes, so these places no longer drop out of joins. The old codes stay in `census_geographies.csv` as "historical only".
* **2000/2010 history across code changes.** 14 predecessor codes are mapped to today's rows (55 cells): Sanford (2000 20,806; 2010 20,798), Verona Island, Westport Island, Bancroft UT, Penobscot Indian Island Reservation, Marshall Island UT, Drew UT and Codyville UT take their predecessor's counts; North Oxford UT (Magalloway, incl. 2020), South Aroostook UT (Cary), Central Aroostook UT (Oxbow), Southeast Piscataquis UT (Atkinson), East Central Franklin UT (Madrid) and North Washington UT (Centerville) add the place they absorbed. Town sums now equal the county rows for 2000, 2010 and 2020 population, 18+ and housing units (before: York 2000 short 20,806, nine counties off in 2000). Change percentages recomputed. Chebeague Island has no 2000 figure of its own (it was part of Cumberland until 2007).
* `pop_change_*` is blank where the base year is 0 (7 cells were ±infinity). An ACS estimate of 0 with a margin above 0 is now flagged `low` instead of `ok` (3,972 cells, mostly 0% race/ethnicity and heating-fuel shares in small towns).
* **Perkins.** Registration unit MPD-0139 (Perkins Twp, Franklin County, 37 people) had been linked by name to the Census "Perkins UT", which is Swan Island in Sagadahoc County (0 people). The link is removed (profile `unit_id`, block table, crosswalk); MPD-0139 now points to its parent, South Franklin UT.
* `unit_census_crosswalk.csv`: 83 rows added (MPD-0950…MPD-1032, the 1969–70 township lines, Maine Register 1868–1928 units and the 1918 soldier vote), relation "historical unit, no census geography"; `parent_ut_*` columns added.
* `census_profile_regions.csv` recomputed (Western Maine 81 → 79 places, Midcoast 59 → 60: Perkins UT moved with Swan Island; North Woods and Downeast ACS totals now include Drew UT and Codyville UT).
* Scripts: `fix_v1_2_census.py` (run after `geography/fix_v1_1_geography.py`) and `verify_v1_2_census_geography.py` (before/after identities).