Choropleth Maps¶

ChoroplethLayer classifies a numeric column using mapclassify and draws filled polygons. The legend is drawn automatically below the main map.

import geopandas as gpd
from mappyng import Map, BasemapLayer, ChoroplethLayer

gdf = gpd.read_file("departements_population.gpkg")

m = Map(gdf, width=800, height="auto")
m.add(BasemapLayer())
m.add(ChoroplethLayer(
    gdf,
    column="pop",
    cmap="YlOrRd",
    method="Quantiles",
    num_classes=5,
    stroke_width=0.15,
    legend={
        "title": "Population",
        "decimals": 0,
        "orientation": "vertical",
    },
))
m.render("choropleth.svg")

Layer parameters¶

These are passed as keyword arguments to ChoroplethLayer(gdf, ...).

Key	Default	Description
`column`	required	Numeric column to classify.
`cmap`	`"YlOrRd"`	Colormap name (`"YlOrRd"`, `"Blues"`, `"Greens"`, `"Reds"`, `"RdYlGn"`) or a list of hex strings of length `num_classes`.
`method`	`"FisherJenks"`	Classification scheme: `"EqualInterval"`, `"Quantiles"`, `"FisherJenks"`, `"Q6"`, `"StdMean"`, or a list of custom break values (length `num_classes + 1`).
`num_classes`	5	Number of classes (4-7). Ignored when `method` is a list.
`stroke`	from style	Polygon outline color.
`stroke_width`	from style	Polygon outline width in SVG px.
`dissolve`	`False`	Dissolve polygons by class before rendering (reduces SVG size).
`on_zoom`	`True`	Render this layer on the zoom viewport.
`on_cartouches`	`True`	Render this layer on cartouche viewports.
`legend`	`None`	Legend sub-config dict. See tables below.

Legend parameters (`legend` sub-dict)¶

Shared fields (all legend types)¶

Key	Default	Description
`title`	`None`	Legend title text.
`subtitle`	`None`	Subtitle rendered below the title.
`title_fontsize`	from style	Title font size.
`title_fontcolor`	from style	Title font color.
`title_fontweight`	from style	Title font weight (e.g. `"bold"`).
`title_fontfamily`	from style	Title font family.
`title_max_chars`	35	Characters per line before title wraps.
`title_offset_x`	0.0	Additional horizontal offset for title (SVG px).
`title_offset_y`	0.0	Additional vertical offset for title (SVG px).
`fontsize`	from style	Label font size.
`fontcolor`	from style	Label font color.
`fontweight`	from style	Label font weight.
`fontfamily`	from style	Label font family.
`hatch_style`	from style	SVG hatch fill for swatches: `"///"`, `"\\\\"`, `"xxx"`, `"..."`, `"\|\|\|"`, `"---"`.
`hatch_color`	from style	Hatch line color.
`spacing`	0.01	Extra vertical offset added to auto-position (fraction of content height).
`position`	`None`	Manual position `{"x": frac, "y": frac}` (0,0 = top-left, 1,1 = bottom-right).
`frame`	`None`	Background frame: `False` = none, `True` = default frame, dict = overrides (see Legend frame fields (frame dict)).

Choropleth-specific fields¶

Key	Default	Description
`decimals`	1	Decimal places for class boundary labels.
`orientation`	`"horizontal"`	Legend layout: `"horizontal"` or `"vertical"`.
`swatch_size`	`None`	Global width override for all swatches (horizontal and vertical modes). Height is always derived as `swatch_size / phi` (golden ratio). Overrides `swatch_width` and `vertical_swatch_width`. Example: `"swatch_size": 40`.
`swatch_width`	30	Color swatch width in horizontal mode (SVG px).
`swatch_height`	auto	Swatch height in horizontal mode. Defaults to `swatch_width / phi` (golden ratio).
`swatch_spacing`	2	Gap between swatches (SVG px).
`label_rotation`	0	Label rotation in degrees.
`label_position`	`"border"`	`"border"`, n+1 labels at swatch edges. `"center"`, n labels centered inside each swatch.
`label_format`	`"value"`	With `label_position="center"`: `"value"` (lower bound) or `"range"` (`[min, max]` interval).
`label_anchor`	`"middle"`	SVG text-anchor for rotated labels: `"middle"` or `"end"`.
`label_margin`	4	Gap between swatch bottom and label baseline (SVG px).
`nodata_label`	`"N/A"`	Label for missing-value swatch.
`nodata_gap`	10	Gap between last class swatch and N/A swatch (SVG px).
`nodata_label_gap`	4	Gap between N/A swatch right edge and its label (SVG px).
`vertical_swatch_width`	16	Swatch width in vertical mode (SVG px).
`vertical_swatch_height`	12	Swatch height in vertical mode (SVG px).
`vertical_label_gap`	6	Gap between swatch and label in vertical mode (SVG px).
`labels`	`None`	Custom label list (length == num_classes) replacing auto-generated labels.

Legend frame fields (`frame` dict)¶

Key	Default	Description
`fill`	`"white"`	Frame background color.
`fill_opacity`	0.9	Frame background opacity.
`stroke`	`"#cccccc"`	Frame border color.
`stroke_width`	0.5	Frame border width (SVG px).
`border_radius`	4	Frame corner radius (SVG px).
`padding`	8	Inner padding between content and frame edge (SVG px).
`shadow`	`False`	Add drop shadow behind the frame.
`shadow_dx` / `shadow_dy`	2 / 2	Shadow offset (SVG px).
`shadow_blur`	4	Shadow blur radius (SVG px).
`shadow_opacity`	0.3	Shadow opacity.