A Python helper that creates clean choropleth maps with defaults for projection, layout, legend and other key configurations.
Install · Quick start · Configuration · All examples and data sources
Share of county land devoted to farming, 2022. Demonstrates a sequential palette, rounded percentage breaks, state boundary overlays and a left-aligned legend. Example script · Data and reproduction guide
Democratic and Republican leads in 2024, measured in percentage points. Demonstrates a diverging scale with fixed breaks around zero; the darkest shades include leads of 30 points or more. Example script · Data and definitions
Non-Hispanic Asian share of the population, 2020. Demonstrates detailed regional geography, explicit class breaks and a layout that adapts to a tall map. Example script · Data and reproduction guide
Gen Z as a share of county population across all 50 states, using Esri's 2018 estimates and its 1999–2016 birth-year definition. Demonstrates natural breaks, readable percentage labels, and repositioned Alaska and Hawaii counties. Example script · Data and definitions
Browse all 10 maps, including cattle, poultry, income, population density, millennials and the 50-state population map. The example guide includes commands, data sources and cache behavior.
pip install chorokitFor development:
git clone https://github.com/mstiles/chorokit.git
cd chorokit
pip install -e ".[dev]"import geopandas as gpd
from chorokit import plot_choropleth
gdf = gpd.read_file("data/states.geojson")
fig, ax = plot_choropleth(
gdf=gdf,
value="value_column",
title="headline",
subtitle="subhead",
source="Source: dataset",
)
fig.savefig("out.png", dpi=300)Figure height is derived from the map's aspect ratio and the text/legend bands, so spacing stays consistent across geographies. Pass layout=LayoutConfig(width=10) to set the width in inches.
chorokit data/states.geojson value_column --title "headline" --subtitle "subhead" --source "Source: dataset" -o out.pngfrom chorokit import plot_choropleth, LegendConfig, LayoutConfig, Projection
legend = LegendConfig(
kind="binned",
title="value per 100k residents",
location="top",
scheme="quantiles",
k=5,
)
layout = LayoutConfig(
title="headline",
subtitle="subhead",
source="Source: dataset",
projection=Projection.us_albers(),
width=12,
)
fig, ax = plot_choropleth(gdf, value="value_column", cmap="Reds", legend=legend, layout=layout)# pass an EPSG code directly
fig, ax = plot_choropleth(gdf, value="value_column", projection=3857)
# or set in layout config
layout = LayoutConfig(projection="EPSG:3857")
fig, ax = plot_choropleth(gdf, value="value_column", layout=layout)from chorokit import plot_us_choropleth
fig, ax = plot_us_choropleth(
states,
value="population",
fips="state_fips",
legend=legend,
layout=layout,
)plot_us_choropleth() accepts state or county FIPS codes and creates one
conventional national map. It draws the lower 48 and D.C. in Albers, projects
Alaska and Hawaii locally, then scales and repositions them beneath the
Southwest. Every state remains in the same axes and shares one classification
and legend. The CLI equivalent is --us-composite state_fips.
chorokit data.geojson value_column \
--scheme quantiles -k 5 \
--legend-location top --legend-title "value per 100k"# 7-class Blues palette with natural breaks
chorokit us_states.geojson POPULATION --palette Blues:7 --scheme natural \
--title "US State Population" --source "Source: U.S. Census Bureau"
# 5-class Reds palette with quantile breaks
chorokit data.geojson value --palette Reds:5 --scheme quantilesfrom chorokit import plot_choropleth, LegendConfig
legend = LegendConfig(
kind="binned",
palette=("Reds", 5),
scheme="quantiles",
title="Population density",
)
fig, ax = plot_choropleth(gdf, value="density", legend=legend)import geopandas as gpd
from chorokit import plot_choropleth, LegendConfig, LayoutConfig
gdf = gpd.read_file("demographics.geojson")
legend = LegendConfig(
kind="binned",
title="Percent of population, by block",
breaks=[0, 5, 15, 30, 50, 90],
labels=["0", "5", "15", "30", "50", "90"],
)
layout = LayoutConfig(
title="Percent non-Hispanic Asian",
subtitle="Los Angeles County blocks, 2020",
source="Source: County of Los Angeles, Census 2020",
width=10,
)
fig, ax = plot_choropleth(gdf, value="pc_nh_asn", cmap="Reds", legend=legend, layout=layout)- Layout: figure height comes from the map aspect plus fixed-size title, legend and source bands, so spacing is identical for wide, tall or square geographies
- Projection: auto-projects geographic data. Local/regional extents use a suitable UTM zone; large CONUS extents use EPSG:5070. You can pass an explicit CRS via int, EPSG string or
pyproj.CRS. - Composite U.S. maps:
plot_us_choropleth()and--us-compositescale and reposition Alaska and Hawaii beneath the Southwest while preserving one national color scale - Legend: top or bottom placement (always horizontal); left or center align; binned or continuous; auto breaks via
schemeandk; optional log classification and nice-round edges; interval or boundary labels with compactk/M/%formatting; automatic No-data swatch - Overlays: pass
Overlaylayers (state lines, etc.) drawn on top of the fill - ColorBrewer palettes: access to ColorBrewer 2.0 sequential, diverging and qualitative color schemes with discrete class counts
- Theme: Barlow ships with the package for consistent typography; override via
LayoutConfig.theme - CLI: flags for projection, legend options and auto classification
See the project principles and roadmap for design goals and priorities.
pip install -e ".[dev]"
pytest # unit + image comparison tests
python tools/gallery.py # contact sheet across the case matrixRegenerate image baselines after intentional layout changes:
pytest tests/test_visual.py --mpl-generate-path=tests/baselineColorBrewer color specifications and designs were developed by Cynthia Brewer (https://colorbrewer2.org/). Please see the ColorBrewer Apache-Style license.
Copyright 2002 Cynthia Brewer, Mark Harrower, and The Pennsylvania State University
MIT



