Proportional Symbols¶

ProportionalLayer draws circles whose area is proportional to a data column. Circle centroids are computed from polygon centroids automatically.

from mappyng import Map, BasemapLayer, ProportionalLayer

m = Map(gdf, width=800, height="auto")
m.add(BasemapLayer())
m.add(ProportionalLayer(
    gdf_pts,
    column="population",
    fill="#e31a1c",
    fill_opacity=0.7,
    stroke="#ffffff",
    stroke_width=0.5,
    reference_value=1_000_000,
    reference_radius=20,
    legend={
        "title": "Population",
        "orientation": "nested",
        "values": [100_000, 500_000, 1_000_000],
        "number_format": "space",
        "leader_opacity": 0.5,
    },
))

Layer parameters¶

Key	Default	Description
`column`	required	Numeric column for circle sizing.
`fill`	`"#1f77b4"`	Circle fill color.
`fill_opacity`	0.7	Circle fill opacity 0-1.
`stroke`	`"#ffffff"`	Circle stroke color.
`stroke_width`	0.5	Circle stroke width (SVG px).
`max_radius`	30	Maximum circle radius in auto-scale mode (SVG px).
`reference_value`	`None`	Data value that maps exactly to `reference_radius`. Use with `reference_radius` to fix the scale across multiple maps.
`reference_radius`	`None`	Radius in SVG px for `reference_value`. Both must be set together.
`on_zoom`	`True`	Render on zoom viewport.
`on_cartouches`	`True`	Render on cartouche viewports.
`legend`	`None`	Legend sub-config dict. See tables below.

Legend parameters (`legend` sub-dict)¶

Shared fields: see the choropleth guide (shared fields table under “Legend parameters”).

Proportional-specific fields¶

Key	Default	Description
`orientation`	`"nested"`	Layout: `"nested"` (concentric circles), `"vertical"`, or `"horizontal"`.
`values`	`None`	Explicit list of data values to show. Auto-generated if None.
`num_values`	4	Number of auto-generated legend values.
`decimals`	0	Decimal places for value labels.
`number_format`	`"space"`	Thousands separator: `"space"` (narrow no-break) or `"none"`.
`circle_fill`	`None`	Override circle fill color in the legend. Uses layer fill if None.
`circle_fill_opacity`	0.7	Legend circle fill opacity.
`circle_stroke`	`"black"`	Legend circle stroke color.
`circle_stroke_width`	0.8	Legend circle stroke width (SVG px).
`circle_spacing`	`None`	Fixed gap between circles in horizontal mode (SVG px). Auto if None.
`label_gap`	4	Gap between circle edge and label (SVG px).
`leader_color`	`"black"`	Leader line color (nested mode).
`leader_width`	0.5	Leader line stroke width (SVG px).
`leader_dash`	`"4 2"`	Leader line SVG `stroke-dasharray`.
`leader_opacity`	0.6	Leader line opacity 0-1.