explore_choropleth_map

explore_choropleth_map(
    df,
    var,
    *,
    gdf,
    period=None,
    animate=False,
    entity=None,
    time=None,
    scheme='fisherjenks',
    k=5,
    bins=None,
    tiles='carto-positron',
    hover=None,
    simplify='auto',
    title=None,
)

Map one variable across entities as a classed (or continuous) choropleth.

The panel df is aligned to the entity geometry gdf for one cross section (the latest period by default) and drawn as a Plotly choropleth with one legend-togglable trace per class. With animate=True every period becomes an animation frame, classified on pooled breaks (computed from all periods together) so colors are comparable over time.

Parameters

Name	Type	Description	Default
df	pd.DataFrame	Long panel (or cross section) holding var per entity.	required
var	str	Numeric column of df to map.	required
gdf	gpd.GeoDataFrame	Entity geometry; must carry the same entity-id column as df.	required
period	Any	Period to map. Defaults to the latest period when df has a time dimension (a note records this). Ignored when animate=True.	None
animate	bool	Draw every period as an animation frame with a slider and play button.	False
entity	str | None	Panel identifiers; default to the ids declared via :func:geometrics.set_panel.	None
time	str | None	Panel identifiers; default to the ids declared via :func:geometrics.set_panel.	None
scheme	str | None	A mapclassify scheme name ("fisherjenks", "quantiles", …), or None for a continuous colorbar map.	'fisherjenks'
k	int	Number of classes for scheme (ignored when bins are given).	5
bins	Sequence[float] | None	Explicit upper class bounds (overrides scheme / k).	None
tiles	str | None	MapLibre base-map style (default "carto-positron") or None for the vector backend (deterministic PNG export).	'carto-positron'
hover	str | Sequence[str] | None	Extra df column(s) appended to the hover box.	None
simplify	float | str | None	Geometry simplification: "auto" (metric tolerance = max bounding-box dimension / 2000), a float tolerance in meters, or None to disable.	'auto'
title	str | None	Figure title. Defaults to the variable label plus the mapped period.	None

Returns

Name	Type	Description
	ChoroplethMapResult	Frozen result with df (entity, value, class label), fig, gdf_plotted (the WGS84 geometry actually drawn, value and class attached), the applied bins, and notes.

Examples

Map a small two-period panel (latest period by default):

import geopandas as gpd
import pandas as pd
from shapely.geometry import box

from geometrics.maps import explore_choropleth_map

gdf = gpd.GeoDataFrame(
    {"region": ["a", "b", "c", "d"]},
    geometry=[box(i % 2, i // 2, i % 2 + 1, i // 2 + 1) for i in range(4)],
    crs="EPSG:4326",
)
df = pd.DataFrame(
    {
        "region": ["a", "b", "c", "d"] * 2,
        "year": [2000] * 4 + [2010] * 4,
        "gdppc": [1.0, 2.0, 3.0, 4.0, 1.5, 2.5, 3.5, 4.5],
    }
)
res = explore_choropleth_map(
    df, "gdppc", gdf=gdf, entity="region", time="year", k=2, tiles=None
)
print(res.period, res.bins)