Skip to content
stilesPublic

About

A Python helper that creates clean choropleth maps with defaults for projection, layout, legend and other key configurations.

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Chorokit

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

Gallery

Farmland by county

Farmland as a share of county land area in 2022

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

Presidential election margin

Democratic and Republican presidential vote margins by county in 2024

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

Los Angeles County demographics

Non-Hispanic Asian share of population in Los Angeles County, 2020

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 by county

Gen Z share of county population using Esri's 2018 estimates

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.

Install

pip install chorokit

For development:

git clone https://github.com/mstiles/chorokit.git
cd chorokit
pip install -e ".[dev]"

Quick start

Basic Python example

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.

CLI example

chorokit data/states.geojson value_column --title "headline" --subtitle "subhead" --source "Source: dataset" -o out.png

Configuration

Auto classification with top legend and projection

from 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)

Projection override

# 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)

Composite U.S. maps

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.

CLI with classification and top legend

chorokit data.geojson value_column \
  --scheme quantiles -k 5 \
  --legend-location top --legend-title "value per 100k"

ColorBrewer palettes

# 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 quantiles

Python with ColorBrewer palettes

from 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)

Explicit breaks and labels

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)

Features

  • 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-composite scale 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 scheme and k; optional log classification and nice-round edges; interval or boundary labels with compact k/M/% formatting; automatic No-data swatch
  • Overlays: pass Overlay layers (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

Development

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 matrix

Regenerate image baselines after intentional layout changes:

pytest tests/test_visual.py --mpl-generate-path=tests/baseline

ColorBrewer attribution

ColorBrewer 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

License

MIT

About

A Python helper that creates clean choropleth maps with defaults for projection, layout, legend and other key configurations.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages