Choropleth Map
Signature
sp.choropleth(title, labels=None, values=None, *, variant="sequential", map="world", region=None, center_lat=None, center_lon=None, **kwargs) -> Chart
Aliases: sp.choropleth, sp.choropleths, sp.choropleth_map, sp.choropleth_chart, sp.geo_map, sp.build_choropleth
Description
sp.choropleth() fills country or region polygons by a scalar value. variant selects the color-classification strategy; map selects which registered geographic region set to draw; region optionally restricts drawing to one named group inside that set (e.g. a continent or a census region). All three are read live from the same register/inventory system the rest of the framework uses — nothing below is hardcoded.
Variants
Region Sets
Parameters
Returns
Chart — object with .html property and .show() method.
Continuous heat gradient from the lowest to the highest value in the visible set — the classic choropleth, one smooth color ramp.
Splits the values into bins discrete quantile classes (equal counts per class, not equal-width) and paints each class its own step of a viridis scale — the standard cartographic technique for reading patterns at a glance instead of guessing shades on a gradient.
Red–white–blue diverging scale centered on diverging_midpoint (default 0) — built for signed data where the story is above/below a reference point: year-over-year change, deviation from a target, a delta rather than a magnitude.
The globe, seen from space: every polygon vertex is converted from map pixels to real latitude/longitude and re-projected with actual orthographic sphere math, then clipped to the visible hemisphere. center_lat / center_lon aim the view (default 15, 10). Only region sets that expose a coordinate inversion support this — today, "world".
Azimuthal equidistant, centered on a pole by default (center_lat=90, center_lon=0) — the classic polar-projection read, where distance from the center is true distance from the chosen point.
Two value series at once instead of one: values and secondary_values each split into three bins, looked up in a 3×3 color grid instead of a single ramp, so a single glance separates “high on both”, “high on one, low on the other”, and “low on both” — a technique real cartographers use and almost no charting library ships.
One dot per fixed unit of value, scattered at random inside the real region outline (rejection-sampled against the actual polygon, not just its bounding box) instead of one flat fill color — texture and density carry the magnitude the way an old-school population map does.
Not data-driven at all — the real day/night terminator, solved from the spherical law of cosines for where the sun sits exactly on the horizon, not a cosmetic gradient band. center_lat/center_lon are read as the current subsolar point (the latitude tracks the season, the longitude the time of day); the correct pole is shaded by comparing which one the sun’s declination actually leaves in darkness, and a sun glyph marks the subsolar point itself. labels/values are ignored entirely for this variant.