Skip to content

Latest commit

 

History

History
148 lines (116 loc) · 9.15 KB

README.md

File metadata and controls

148 lines (116 loc) · 9.15 KB

Reproduce the example gallery

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.py

Images 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_share

The other agriculture choices are cattle_sold and poultry_sold; demographic choices also include millennial_share, median_income and population_density.

Map index

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

Data sources and definitions

2024 election margin

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.

County demographics: 2018 estimates

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.

2020 state population

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 County demographics and Census of Agriculture

  • LA uses the committed data/processed/lacounty_demographics_blocks.geojson, field pc_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.csv and poultry_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.

Shared boundaries

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.

Visual development matrix

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.