Bubble Map
Signature
sp.bubble_map(title, labels=None, values=None, *, variant="proportional", map="world", region=None, center_lat=None, center_lon=None, **kwargs) -> Chart
Aliases: sp.bubble_map, sp.bubblemap, sp.bubble_map_chart, sp.geo_bubble, sp.geo_bubble_map, sp.build_bubble_map
Description
sp.bubble_map() marks matched regions on a map with a proportionally-sized circle at each centroid by default — real bubbles, not filled shapes; pick variant="filled" instead when it’s the regions themselves the reader should compare, not a magnitude. map selects which registered geographic region set to draw; region optionally restricts drawing to one named group inside that set. 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.
The default, and the real graduated-symbol map: the base is muted, and a circle sits on each matched region’s centroid, its radius scaled by sqrt(value) so area — not radius — reads proportionally to magnitude. min_bubble_size / max_bubble_size set the radius range in pixels.
Not a bubble at all by design: each matched region filled solid with its own palette color and labeled at its centroid — a categorical highlight map, for when it’s the regions themselves the reader should compare rather than a magnitude. Reach for choropleth instead if the fill color should encode a continuous value.
Proportional circles projected onto an orthographic sphere — every centroid is converted to real latitude/longitude and re-projected with actual globe math, so bubbles on the far side simply aren’t drawn. center_lat / center_lon aim the view (default 15, 10). Only region sets that expose a coordinate inversion support this — today, "world".
A hollow circle instead of a filled one — stroke-width carries the magnitude, not just radius, so a thin ring reads small and a thick ring reads large even where two circles overlap and one would otherwise hide behind the other.
Two faint concentric rings behind the solid marker, fading out with distance — a static radar-ping look, well suited to data that reads as an alert or a hotspot rather than a plain quantity.
A density map, not a values map: pass raw lats/lons samples instead of labels/values and each point is binned into a hexagonal grid — real axial hex-coordinate binning with cube-coordinate rounding, the same technique a proper geographic hexbin uses, not a nearest-center search. Each hexagon is sized and colored by how many samples landed inside it, with the count itself labeled once a cell holds more than one.
A proportional symbol map where the symbol is a real pie, not a circle: pass a series of per-point category breakdowns plus shared categories names instead of a flat values array, and each point draws its own mini pie sized by its category total (sqrt-scaled, same convention as proportional) with genuine arc-path slices — not a bubble with a label. Category colors stay fixed across every point so two pies stay comparable at a glance, with a legend rendered top-right.
sub_variant picks the glyph itself from sp.pie()’s own variant vocabulary — "donut", "semi", "exploded", "nightingale", "waffle" render each map point with that exact 2D pie style, scaled down. donut/semi/exploded call the identical shared renderer a standalone sp.pie(variant=...) uses, just aimed at a small per-marker area; nightingale and waffle reimplement the same polar-area and largest-remainder-apportionment math at marker scale, since their 2D renderers build a full standalone document rather than a reusable sub-area piece. Any other sub_variant (or none) falls back to a plain pie.