Featured gallery · Map index · Data sources
From the repository root, install the package and run an example:
python -m pip install -e ".[dev]"
python examples/la_county_map.py
python examples/ag_census_maps.py
python examples/election_2024_margin.py
python examples/county_demographics.py
python examples/us_population_simple.pyImages are written to examples/visuals/. Network-backed examples download data
on the first run and reuse files in the ignored examples/data/raw/ directory.
No API keys or sibling repositories are required. LA's input and the agriculture
CSVs are included in this repository. Run with MPLBACKEND=Agg on a machine
without a display.
For a single agriculture or demographic image:
python examples/ag_census_maps.py --only farmland_share
python examples/county_demographics.py --only gen_z_shareThe other agriculture choices are cattle_sold and poultry_sold; demographic
choices also include millennial_share, median_income and population_density.
Open a map to view the full image, or its script to see how it is made. Commands run from the repository root after the installation step above.
| Map | What it demonstrates | Script | Run |
|---|---|---|---|
| Farmland share, 2022 | Rounded percentage breaks and state overlays | Agriculture | python examples/ag_census_maps.py --only farmland_share |
| Election margin, 2024 | Diverging colors with fixed breaks around zero | Election margin | python examples/election_2024_margin.py |
| LA demographics, 2020 | Detailed regional geography and explicit breaks | LA County | python examples/la_county_map.py |
| Gen Z share, 2018 | A 50-state county map with rounded percentage labels | County demographics | python examples/county_demographics.py --only gen_z_share |
| Cattle sold, 2022 | Log classification and compact count labels | Agriculture | python examples/ag_census_maps.py --only cattle_sold |
| Poultry sold, 2022 | Counts spanning orders of magnitude and missing data | Agriculture | python examples/ag_census_maps.py --only poultry_sold |
| Median household income, 2018 | Dollar labels on rounded class boundaries | County demographics | python examples/county_demographics.py --only median_income |
| Population density, 2018 | Log classification for a skewed distribution | County demographics | python examples/county_demographics.py --only population_density |
| Millennial share, 2018 | Generation shares with a sequential palette | County demographics | python examples/county_demographics.py --only millennial_share |
| State population, 2020 | A composite national map with Alaska and Hawaii | State population | python examples/us_population_simple.py |
The example downloads county results and geometry at a fixed repository revision
from stiles/presidential-elections and saves
raw/presidential_election_2024_8d641905.geojson. This is a historical snapshot,
not a feed of revised election results. The upstream processing documentation
attributes 2024 results to Dave Leip's Atlas; MIT supplies earlier elections in
that repository, not this map's 2024 results.
Margin is Republican vote percentage minus Democratic vote percentage, in percentage points. The shares use all votes as the denominator. Blue means a Democratic lead, red a Republican lead; the darkest shades cover leads of 30 points or more. The scale covers −100 to +100, with labels on interior boundaries. The map includes the contiguous-U.S. county geometries present in the snapshot; places absent from that file have no polygon and appear as gaps, rather than as the gray swatch used for missing values on existing polygons.
The downloaded county GeoJSON
is an export of Esri's 2018 demographic data. _CY means the current year
of that data release, not the year when you run the script.
The original Esri Generations county layer identifies the year, units and cohort definitions in its field aliases:
| Map | Fields and calculation | Definition |
|---|---|---|
| Gen Z share | GENZ_CY / TOTPOP_CY × 100 |
Born 1999–2016; share of total residents |
| Millennial share | MILLENN_CY / TOTPOP_CY × 100 |
Born 1981–1998; share of total residents |
| Median household income | MEDHINC_CY |
2018 U.S. dollars |
| Population density | POPDENS_CY |
Residents per square mile, 2018 |
Shares are rounded to one decimal place before classification. Maps use natural breaks with rounded interior boundaries; density is classified in log space. All four maps include the 50 states, with Alaska and Hawaii scaled and placed beneath the Southwest in the same map. The cohort definitions are Esri's and can differ from those used by other sources.
Verification on September 10, 2026: all five mapped source fields matched for the first 1,000 counties returned by the original Esri layer. The live GeoJSON download also matched the existing local snapshot byte for byte. Its SHA-256 is:
12722c0a927b3e4c40ed2f9af91ec1a8fc990e583dacba2456267a76a33372b9
The script checks this hash for both cached and freshly downloaded data. If the hosted file changes, it stops instead of labeling a different release as 2018. Restore a copy with this hash, or verify the new release's metadata and update the year, definitions, checksum and gallery images together. The host's URL is mutable; the checksum detects changes but does not archive the original file.
The example downloads the Census Bureau's historical population and apportionment CSV
to raw/census_apportionment_1910_2020.csv, selects Year == 2020, and joins
Resident Population to state boundaries by name. See the Census release documentation.
These are April 1, 2020 resident counts, not the apportionment population that includes certain overseas residents. The map shows all 50 states and D.C.; Alaska and Hawaii are projected locally, scaled to familiar atlas proportions, and repositioned beneath the Southwest. All states share one classification. Counts are expressed in millions. Population attributes in the boundary file are deliberately discarded; they are not the 2020 Census counts.
- LA uses the committed
data/processed/lacounty_demographics_blocks.geojson, fieldpc_nh_asn, attributed in the existing example to Los Angeles County's Census 2020 SRR and Demographic Characteristics data. No download is required. - Agriculture uses the committed
data/ag/farmland_share.csv,cattle_sold.csvandpoultry_sold.csv, attributed to the 2022 U.S. Census of Agriculture. The scripts join these tables to county boundaries by FIPS. The original extraction queries are not included in this repository; these examples reproduce maps from the committed tables.
- Simplified Esri state boundaries
→
raw/usa_states_esri_simple.json(elections, demographics, agriculture and population). - Simplified Esri county boundaries
→
raw/usa_counties_esri_simple.json(agriculture).
These hosted boundary exports are cached, but are not version-pinned. Retain the cache if you need the same geometry for a later render. National examples use CONUS Albers (EPSG:5070) for the lower 48 and D.C. The state-population map also uses Alaska Albers (EPSG:3338) and a local equal-area projection for Hawaii. The agriculture data has Hawaii but no Alaska records, so those examples remain lower-48 maps. The election snapshot has neither and also remains lower-48. Puerto Rico is outside the current U.S. composite helper and is excluded explicitly.
python tools/gallery.py creates a synthetic contact sheet for checking layouts
across shapes, legends and text configurations. It is separate from the real-data
examples above. pytest runs unit tests and the saved image comparisons.