Layers¶

Every drawable is a Layer added to a map with + or mappyng.Map.add(). Layers carry their data and parameters, validate themselves, and render into the map when it is built.

Base classes¶

class mappyng.layers.Layer(gdf=None, *, z_index=0, visible=True, **params)[source]¶

Bases: ABC

Abstract description of a cartographic layer.

A layer holds its data (gdf) and parameters (params) and draws nothing until render() is called. It is validated at construction and at every update().

Parameters:

gdf (GeoDataFrame, optional) – The layer data. Required for data layers (requires_gdf); ignored by reference layers such as the basemap.
z_index (int, default 0) – Render order. Layers with equal z_index keep insertion order.
visible (bool, default True) – Whether the layer is drawn.
**params (Any) – Layer-specific parameters (see each concrete subclass).

id¶

Identifier, assigned by the map when the layer is added.

Type:: str or None

__init__(gdf=None, *, z_index=0, visible=True, **params)[source]¶

copy()[source]¶

Return an unrendered copy that shares the same data.

The parameters are copied, the GeoDataFrame is shared. The copy has no id until it is added to a map.

Return type:: Layer

classmethod from_dict(data, gdf=None)[source]¶

Rebuild a layer from to_dict() output.

Parameters:

data (dict) – A serialised layer.
gdf (GeoDataFrame, optional) – Geometry to reattach (the serialised form does not carry it).

Return type:

Layer

kind: str = 'layer'¶: Identifier prefix for this layer family.

abstractmethod render(ctx)[source]¶

Draw the layer into the map carried by ctx.

Called when the map is built. Implementations must set self._rendered = True once drawn.

Return type:: None

requires_gdf: bool = False¶: Whether a non-empty gdf is required at construction.

to_dict()[source]¶

Serialise the layer’s intent (not its geometry).

The geometry is flagged by data['in_memory']; persisting it by reference or path is handled by serialisation.

Return type:: dict[str, Any]

classmethod type_name()[source]¶

Name under which the layer type is registered.

Return type:: str

update(**kwargs)[source]¶

Update parameters and re-validate. Returns self.

z_index and visible are treated as layer metadata; any other keyword updates params.

Raises:: LayerStateError – If the layer has already been rendered.
Return type:: Layer

validate()[source]¶

Check internal consistency. Override in subclasses.

Raises in plain language (see errors.py convention) for structural problems such as a missing required parameter. Semiological advice is emitted as a warning, never an error.

Return type:: None

class mappyng.layers.RenderContext(map)[source]¶

Bases: object

Carries what a Layer needs to render itself.

The context is the decoupling point between a layer and the map: a layer never reaches into Map directly, it goes through the context. It transports the host map (whose viewports, CRS, internal state and font scaling a layer reaches through).

Parameters:: map (Map) – The host map the layer draws into.

__init__(map)[source]¶

exception mappyng.layers.LayerStateError[source]¶

Bases: RuntimeError

Raised when a layer is mutated after it has been rendered.

A layer’s parameters describe an intent that is consumed at render time. Once rendered, changing them would silently desynchronise the object from the SVG already produced, so Layer.update() is refused.

Thematic layers¶

class mappyng.Choropleth(gdf=None, *, column=<unset>, cmap=<unset>, reverse=<unset>, method=<unset>, num_classes=<unset>, stroke=<unset>, stroke_width=<unset>, legend=<unset>, dissolve=<unset>, simplify=<unset>, opacity_column=<unset>, min_opacity=<unset>, max_opacity=<unset>, blend_background=<unset>, opacity_bins=<unset>, detail=<unset>, detail_join=<unset>, border_contrast=<unset>, on_zoom=<unset>, on_cartouches=<unset>, z_index=0, visible=True)[source]¶

Bases: Layer

Choropleth (graduated colour) layer.

Maps a relative quantity (rate, ratio, density) to colour value.

Parameters:

gdf (GeoDataFrame) – Polygons with a numeric column.
column (str) – Column to classify (required).
cmap (str or list, optional) – Colour ramp name or explicit list of hex colours (default from defaults). With "StdMean" a diverging ramp ("RdBu", "BrBG", "RdYlGn") reads the two sides of the mean apart; a sequential ramp raises a warning.
reverse (bool, optional) – Reverse the colour order, so the lowest class takes the ramp’s last colour (default False). Applies to named ramps and explicit lists.
method (str, optional) – Classification scheme: "Quantiles", "EqualInterval", "FisherJenks", "Q6", "StdMean" or "PrettyBreaks".
num_classes (int, optional) – Number of classes, usually 4 to 7 (default 5). "StdMean" supports 5 or 7 (the central class straddles the mean, so the count is odd); any other count snaps to the nearest valid one with a warning. "Q6" always yields 6.
stroke (str, optional) – Outline colour of each area as #RRGGBB (default from style).
stroke_width (float, optional) – Outline width (default from style).
legend (dict or False, optional) – Legend configuration (see ChoroplethLegendConfig), or a legend config instance. False draws no legend.
dissolve (bool, optional) – Merge adjacent areas that share a class before drawing (default False).
simplify (None, str or float, optional) – Geometry simplification: None (default, no simplification), "auto" (half a pixel at the render scale) or a tolerance in the data CRS units.
opacity_column (str, optional) – Column holding a probability/confidence in [0, 1]. When set, colour still encodes column’s class while opacity encodes certainty (linearly mapped onto [min_opacity, max_opacity]).
min_opacity, max_opacity (float, optional) – Opacity bounds for opacity_column (defaults 0.15 and 1.0). Ignored without opacity_column.
blend_background (str, optional) – With opacity_column, pre-composite the class colour over this #RRGGBB background and draw an opaque solid fill instead of relying on SVG fill-opacity. Gives a colour that looks the same regardless of what renders underneath; omit it to use native SVG transparency, which blends live with the basemap or other layers.
opacity_bins (int or list of float, optional) – Discretize opacity_column into this many equal-width bins over [0, 1] (or explicit bin edges). With dissolve, features sharing both class and opacity bin merge into one path instead of having their opacity averaged. None (default) keeps opacity continuous, one value per feature.
detail (GeoDataFrame or dict, optional) – Finer geometry for the zoom window and the cartouches, drawn instead of the generalised one. The symbology computed from gdf is carried to it through detail_join. A GeoDataFrame applies to the zoom and every cartouche; a dict maps "zoom", "cartouches" or a cartouche index to a GeoDataFrame. See mappyng.detail.
detail_join (str, tuple or None, optional) – Key shared by gdf and detail: a column name present in both, a (gdf_column, detail_column) pair, or None (default) to join on the index.
border_contrast (bool, str, dict or BorderContrast, optional) – Make the borders between touching areas of similar colour visible: True redraws only those shared borders in a contrasting colour, "check" reveals them thick in magenta and warns, a dict or a BorderContrast sets thresholds and colours. Default off. See mappyng.border_contrast.
on_zoom (bool, optional) – Draw on the zoom viewport (default True).
on_cartouches (bool, optional) – Draw on cartouche viewports (default True).
z_index (int, optional) – Render order (default 0).
visible (bool, optional) – Whether the layer is drawn (default True).

Examples

>>> m.add(Choropleth(gdf, column="density", method="FisherJenks"))

__init__(gdf=None, *, column=<unset>, cmap=<unset>, reverse=<unset>, method=<unset>, num_classes=<unset>, stroke=<unset>, stroke_width=<unset>, legend=<unset>, dissolve=<unset>, simplify=<unset>, opacity_column=<unset>, min_opacity=<unset>, max_opacity=<unset>, blend_background=<unset>, opacity_bins=<unset>, detail=<unset>, detail_join=<unset>, border_contrast=<unset>, on_zoom=<unset>, on_cartouches=<unset>, z_index=0, visible=True)[source]¶

kind: str = 'choropleth'¶: Identifier prefix for this layer family.

render(ctx)[source]¶

Draw the layer into the map carried by ctx.

Called when the map is built. Implementations must set self._rendered = True once drawn.

Return type:: None

report = None¶: ClassificationReport of the last render (method applied, bounds, class sizes, excluded values, adjustments); None until the layer has been drawn.

requires_gdf: bool = True¶: Whether a non-empty gdf is required at construction.

validate()[source]¶

Check internal consistency. Override in subclasses.

Raises in plain language (see errors.py convention) for structural problems such as a missing required parameter. Semiological advice is emitted as a warning, never an error.

Return type:: None

class mappyng.Category(gdf=None, *, column=<unset>, fill_map=<unset>, default_fill=<unset>, default_label=<unset>, stroke=<unset>, stroke_width=<unset>, legend=<unset>, dissolve=<unset>, simplify=<unset>, opacity_column=<unset>, min_opacity=<unset>, max_opacity=<unset>, blend_background=<unset>, opacity_bins=<unset>, detail=<unset>, detail_join=<unset>, border_contrast=<unset>, on_zoom=<unset>, on_cartouches=<unset>, z_index=0, visible=True)[source]¶

Bases: Layer

Categorical (qualitative) choropleth layer.

Colours each polygon by a nominal category (an id, a type, a cluster label…) via an explicit mapping, rather than classifying a continuous value like Choropleth. Opacity can separately encode a probability/confidence column.

Parameters:

gdf (GeoDataFrame) – Polygons with a category column.
column (str) – Column holding the category per feature (required).
fill_map (dict) – Mapping category -> "#RRGGBB" (required).
default_fill (str, optional) – Colour for categories present in column but absent from fill_map. Without it, an unmapped category raises ValueError.
default_label (str, optional) – Legend label for the default_fill bucket (default "Autre").
stroke (str, optional) – Outline colour of each area as #RRGGBB (default from style).
stroke_width (float, optional) – Outline width (default from style).
legend (dict or False, optional) – Legend configuration (ChoroplethLegendConfig fields). Defaults to a vertical legend with one swatch per category. False draws no legend.
dissolve (bool, optional) – Merge adjacent areas that share a category before drawing (default False).
simplify (None, str or float, optional) – Geometry simplification, see Choropleth.
opacity_column (str, optional) – Column holding a probability/confidence in [0, 1]. When set, colour encodes the category while opacity encodes certainty (linearly mapped onto [min_opacity, max_opacity]).
min_opacity, max_opacity (float, optional) – Opacity bounds for opacity_column (defaults 0.15 and 1.0).
blend_background (str, optional) – With opacity_column, pre-composite the category colour over this #RRGGBB background and draw an opaque solid fill instead of relying on SVG fill-opacity.
opacity_bins (int or list of float, optional) – Discretize opacity_column into this many equal-width bins over [0, 1] (or explicit bin edges). With dissolve, features sharing both category and opacity bin merge into one path instead of having their opacity averaged.
detail (GeoDataFrame or dict, optional) – Finer geometry for the zoom window and the cartouches, drawn instead of the generalised one. The symbology computed from gdf is carried to it through detail_join. A GeoDataFrame applies to the zoom and every cartouche; a dict maps "zoom", "cartouches" or a cartouche index to a GeoDataFrame. See mappyng.detail.
detail_join (str, tuple or None, optional) – Key shared by gdf and detail: a column name present in both, a (gdf_column, detail_column) pair, or None (default) to join on the index.
border_contrast (bool, str, dict or BorderContrast, optional) – Make the borders between touching areas of similar colour visible: True redraws only those shared borders in a contrasting colour, "check" reveals them thick in magenta and warns, a dict or a BorderContrast sets thresholds and colours. Default off. See mappyng.border_contrast.
on_zoom (bool, optional) – Draw on the zoom viewport (default True).
on_cartouches (bool, optional) – Draw on cartouche viewports (default True).
z_index (int, optional) – Render order (default 0).
visible (bool, optional) – Whether the layer is drawn (default True).

Examples

>>> m.add(Category(
...     gdf, column="cluster",
...     fill_map={"A": "#1f78b4", "B": "#33a02c", "C": "#e31a1c"},
...     opacity_column="confidence",
... ))

__init__(gdf=None, *, column=<unset>, fill_map=<unset>, default_fill=<unset>, default_label=<unset>, stroke=<unset>, stroke_width=<unset>, legend=<unset>, dissolve=<unset>, simplify=<unset>, opacity_column=<unset>, min_opacity=<unset>, max_opacity=<unset>, blend_background=<unset>, opacity_bins=<unset>, detail=<unset>, detail_join=<unset>, border_contrast=<unset>, on_zoom=<unset>, on_cartouches=<unset>, z_index=0, visible=True)[source]¶

kind: str = 'category'¶: Identifier prefix for this layer family.

render(ctx)[source]¶

Draw the layer into the map carried by ctx.

Called when the map is built. Implementations must set self._rendered = True once drawn.

Return type:: None

report = None¶: CategoryReport of the last render (features per category, excluded values); None until drawn.

requires_gdf: bool = True¶: Whether a non-empty gdf is required at construction.

validate()[source]¶

Check internal consistency. Override in subclasses.

Raises in plain language (see errors.py convention) for structural problems such as a missing required parameter. Semiological advice is emitted as a warning, never an error.

Return type:: None

class mappyng.Proportional(gdf=None, *, column=<unset>, fill=<unset>, fill_opacity=<unset>, stroke=<unset>, stroke_width=<unset>, max_radius=<unset>, reference_value=<unset>, reference_radius=<unset>, legend=<unset>, on_zoom=<unset>, on_cartouches=<unset>, detail=<unset>, detail_join=<unset>, fill_column=<unset>, fill_map=<unset>, z_index=0, visible=True)[source]¶

Bases: Layer

Proportional symbols layer.

Maps an absolute quantity (stock) to symbol size, preserving magnitude where colour value would flatten it.

Parameters:

gdf (GeoDataFrame) – Geometries with a numeric column.
column (str) – Column driving symbol size (required).
fill (str, optional) – Symbol fill colour as #RRGGBB (default from defaults).
fill_opacity (float, optional) – Symbol fill opacity in [0, 1] (default from defaults).
stroke (str, optional) – Symbol outline colour (default from defaults).
stroke_width (float, optional) – Symbol outline width (default from defaults).
max_radius (float, optional) – Radius in pixels of the largest symbol (default from defaults).
reference_value (float, optional) – Value mapped to reference_radius for the legend. Defaults to the data maximum.
reference_radius (float, optional) – Radius in pixels for reference_value. Defaults to max_radius.
legend (dict or False, optional) – Legend configuration (see ProportionalLegendConfig). False draws no legend.
on_zoom (bool, optional) – Draw on the zoom viewport (default True).
on_cartouches (bool, optional) – Draw on cartouche viewports (default True).
fill_column (str, optional) – Column giving a category per feature. With fill_map, colours each circle individually so a single layer can mix colours while keeping the global “smallest on top” ordering (one layer per colour breaks it).
fill_map (dict, optional) – Mapping category -> colour used with fill_column; unmapped categories fall back to fill.
detail (GeoDataFrame or dict, optional) – Finer geometry for the zoom window and the cartouches, used to place the circles instead of the generalised one. Values and colours stay those of gdf, carried through detail_join. A GeoDataFrame applies to the zoom and every cartouche; a dict maps "zoom", "cartouches" or a cartouche index to a GeoDataFrame. See mappyng.detail.
detail_join (str, tuple or None, optional) – Key shared by gdf and detail: a column name present in both, a (gdf_column, detail_column) pair, or None (default) to join on the index.
z_index (int, optional) – Render order (default 0).
visible (bool, optional) – Whether the layer is drawn (default True).

Examples

>>> m.add(Proportional(gdf, column="population", max_radius=30))
>>> m.add(Proportional(gdf, column="n", fill_column="type",
...                         fill_map={"a": "#6A1B9A", "b": "#78909C"}))

__init__(gdf=None, *, column=<unset>, fill=<unset>, fill_opacity=<unset>, stroke=<unset>, stroke_width=<unset>, max_radius=<unset>, reference_value=<unset>, reference_radius=<unset>, legend=<unset>, on_zoom=<unset>, on_cartouches=<unset>, detail=<unset>, detail_join=<unset>, fill_column=<unset>, fill_map=<unset>, z_index=0, visible=True)[source]¶

kind: str = 'proportional'¶: Identifier prefix for this layer family.

render(ctx)[source]¶

Draw the layer into the map carried by ctx.

Called when the map is built. Implementations must set self._rendered = True once drawn.

Return type:: None

requires_gdf: bool = True¶: Whether a non-empty gdf is required at construction.

validate()[source]¶

Check internal consistency. Override in subclasses.

Raises in plain language (see errors.py convention) for structural problems such as a missing required parameter. Semiological advice is emitted as a warning, never an error.

Return type:: None

class mappyng.Situation(gdf=None, *, column=<unset>, symbol=<unset>, marker=<unset>, fill=<unset>, size=<unset>, stroke=<unset>, stroke_width=<unset>, fill_opacity=<unset>, inner_fill=<unset>, inner_stroke=<unset>, label=<unset>, legend=<unset>, on_zoom=<unset>, on_cartouches=<unset>, detail=<unset>, detail_join=<unset>, z_index=0, visible=True)[source]¶

Bases: Layer

Situation (qualitative point/area) layer.

Parameters:

gdf (GeoDataFrame) – Geometries to draw.
column (str, optional) – Category column. When set together with symbol, each category gets its own marker.
symbol (dict, optional) – Mapping of category value to a per-category marker style.
marker (str, optional) – Marker shape used in uniform mode (default "circle").
fill (str, optional) – Marker fill colour as #RRGGBB (default "#e31a1c").
size (float, optional) – Marker size in pixels (default 8).
stroke (str, optional) – Marker outline colour (default "#ffffff").
stroke_width (float, optional) – Marker outline width (default 0.5).
fill_opacity (float, optional) – Marker fill opacity in [0, 1] (default 1).
inner_fill (str, optional) – Fill colour of an inner marker, for layered symbols.
inner_stroke (str, optional) – Outline colour of the inner marker.
label (str, optional) – Column holding a short text drawn next to each marker.
legend (dict or False, optional) – Legend configuration (see SituationLegendConfig). None or False draws no legend.
on_zoom (bool, optional) – Draw on the zoom viewport (default True).
on_cartouches (bool, optional) – Draw on cartouche viewports (default True).
detail (GeoDataFrame or dict, optional) – Finer geometry for the zoom window and the cartouches, used to place the markers instead of the generalised one. Values and colours stay those of gdf, carried through detail_join. A GeoDataFrame applies to the zoom and every cartouche; a dict maps "zoom", "cartouches" or a cartouche index to a GeoDataFrame. See mappyng.detail.
detail_join (str, tuple or None, optional) – Key shared by gdf and detail: a column name present in both, a (gdf_column, detail_column) pair, or None (default) to join on the index.
z_index (int, optional) – Render order (default 0).
visible (bool, optional) – Whether the layer is drawn (default True).

Examples

>>> m.add(Situation(gdf, marker="square", fill="#1f78b4"))

__init__(gdf=None, *, column=<unset>, symbol=<unset>, marker=<unset>, fill=<unset>, size=<unset>, stroke=<unset>, stroke_width=<unset>, fill_opacity=<unset>, inner_fill=<unset>, inner_stroke=<unset>, label=<unset>, legend=<unset>, on_zoom=<unset>, on_cartouches=<unset>, detail=<unset>, detail_join=<unset>, z_index=0, visible=True)[source]¶

kind: str = 'situation'¶: Identifier prefix for this layer family.

render(ctx)[source]¶

Draw the layer into the map carried by ctx.

Called when the map is built. Implementations must set self._rendered = True once drawn.

Return type:: None

requires_gdf: bool = True¶: Whether a non-empty gdf is required at construction.

validate()[source]¶

Check internal consistency. Override in subclasses.

Raises in plain language (see errors.py convention) for structural problems such as a missing required parameter. Semiological advice is emitted as a warning, never an error.

Return type:: None

class mappyng.Label(gdf=None, *, column=<unset>, target=<unset>, font_size=<unset>, font_family=<unset>, font_weight=<unset>, color=<unset>, halo_color=<unset>, halo_width=<unset>, priority_col=<unset>, min_priority=<unset>, max_labels=<unset>, initial_position=<unset>, candidate_positions=<unset>, label_offset=<unset>, max_displacement=<unset>, avoid_overlap=<unset>, allow_hide=<unset>, allow_symbol_overlap=<unset>, leader_lines=<unset>, leader_threshold=<unset>, leader_color=<unset>, leader_width=<unset>, wrap=<unset>, wrap_max_chars=<unset>, numbered_above=<unset>, numbered_legend_position=<unset>, numbered_circle_r=<unset>, numbered_circle_fill=<unset>, numbered_circle_stroke=<unset>, numbered_legend_bg=<unset>, numbered_legend_bg_opacity=<unset>, numbered_legend_border=<unset>, numbered_legend_title=<unset>, n_sweeps=<unset>, initial_temperature=<unset>, final_temperature=<unset>, seed=<unset>, w_LL=<unset>, w_LO=<unset>, w_LC=<unset>, w_LA=<unset>, w_D=<unset>, w_OR=<unset>, w_OOB=<unset>, detail=<unset>, detail_join=<unset>, z_index=0, visible=True)[source]¶

Bases: Layer

Text label layer placed by simulated annealing.

Parameters:

gdf (GeoDataFrame) – Geometries to label.
column (str) – Column holding the label text (required).
target (str, optional) – Viewport to place labels on: "main" (default), "zoom" or "cartouche:<index>".
font_size (float, optional) – Label font size in pixels (default 10).
font_family (str, optional) – Font family (default "sans-serif").
font_weight (str, optional) – Font weight (default "normal").
color (str, optional) – Text colour as #RRGGBB (default "#000000").
halo_color (str or None, optional) – Halo (outline) colour; None disables the halo.
halo_width (float, optional) – Halo width in pixels (default 2).
priority_col (str, optional) – Column ranking which labels are placed first (higher first).
min_priority (float, optional) – Skip rows whose priority is below this threshold.
max_labels (int, optional) – Hard cap on the number of labels placed.
initial_position (str, optional) – Starting candidate position (default "NE").
candidate_positions (list of str, optional) – Candidate positions tried around each anchor.
label_offset (float, optional) – Distance from anchor to label edge in pixels (default 4).
max_displacement (float, optional) – Maximum displacement before a label is hidden (default 40).
avoid_overlap (bool, optional) – Enable label-label overlap avoidance (default True).
allow_hide (bool, optional) – Allow hiding labels that cannot be placed (default True). A label that still covers a map symbol after placement is hidden too.
allow_symbol_overlap (bool, optional) – Keep labels that cover a map symbol instead of hiding them (default False). Useful on dense maps where most labels would be hidden.
leader_lines (bool, optional) – Draw leader lines for displaced labels (default True).
leader_threshold (float, optional) – Displacement (in label heights) that triggers a leader line.
leader_color (str, optional) – Leader line colour (default "#666666").
leader_width (float, optional) – Leader line width (default 0.5).
wrap (bool, optional) – Wrap long labels at dashes (default True).
wrap_max_chars (int, optional) – Maximum characters per line before wrapping (default 12).
numbered_above (int, optional) – Switch to numbered-circle mode past this label count.
numbered_legend_position (dict, optional) – Legend placement {"x": frac, "y": frac} in figure fractions.
numbered_circle_r (float, optional) – Numbered circle radius in pixels (default 5).
numbered_circle_fill (str, optional) – Numbered circle fill colour (default "#ffffff").
numbered_circle_stroke (str, optional) – Numbered circle outline colour (default "#333333").
numbered_legend_bg (str, optional) – Numbered legend background colour (default "white").
numbered_legend_bg_opacity (float, optional) – Numbered legend background opacity (default 0.88).
numbered_legend_border (str, optional) – Numbered legend border colour (default "#cccccc").
numbered_legend_title (str, optional) – Numbered legend title text.
n_sweeps (int, optional) – Number of annealing sweeps (default 50).
initial_temperature (float, optional) – Annealing start temperature (default 1.0).
final_temperature (float, optional) – Annealing end temperature (default 0.01).
seed (int, optional) – Random seed for reproducible placement. Defaults to the map seed.
w_LL, w_LO, w_LC, w_LA, w_D, w_OR, w_OOB (float, optional) – Energy weights tuning the placement: label-label, label-obstacle, label-chrome, label-anchor, distance, orientation bias and out-of-bounds penalties.
detail (GeoDataFrame or dict, optional) – Finer geometry used to place the labels of a zoom or cartouche target instead of the generalised one. Text and priority stay those of gdf, carried through detail_join; a unit made of several finer parts is labelled once. A GeoDataFrame applies to a zoom or cartouche target; a dict maps "zoom", "cartouches" or a cartouche index to a GeoDataFrame. Ignored for the main map. See mappyng.detail.
detail_join (str, tuple or None, optional) – Key shared by gdf and detail: a column name present in both, a (gdf_column, detail_column) pair, or None (default) to join on the index.
z_index (int, optional) – Render order (default 0).
visible (bool, optional) – Whether the layer is drawn (default True).

Examples

>>> m.add(Label(gdf, column="name", priority_col="population",
...                  max_labels=20, font_size=9))

__init__(gdf=None, *, column=<unset>, target=<unset>, font_size=<unset>, font_family=<unset>, font_weight=<unset>, color=<unset>, halo_color=<unset>, halo_width=<unset>, priority_col=<unset>, min_priority=<unset>, max_labels=<unset>, initial_position=<unset>, candidate_positions=<unset>, label_offset=<unset>, max_displacement=<unset>, avoid_overlap=<unset>, allow_hide=<unset>, allow_symbol_overlap=<unset>, leader_lines=<unset>, leader_threshold=<unset>, leader_color=<unset>, leader_width=<unset>, wrap=<unset>, wrap_max_chars=<unset>, numbered_above=<unset>, numbered_legend_position=<unset>, numbered_circle_r=<unset>, numbered_circle_fill=<unset>, numbered_circle_stroke=<unset>, numbered_legend_bg=<unset>, numbered_legend_bg_opacity=<unset>, numbered_legend_border=<unset>, numbered_legend_title=<unset>, n_sweeps=<unset>, initial_temperature=<unset>, final_temperature=<unset>, seed=<unset>, w_LL=<unset>, w_LO=<unset>, w_LC=<unset>, w_LA=<unset>, w_D=<unset>, w_OR=<unset>, w_OOB=<unset>, detail=<unset>, detail_join=<unset>, z_index=0, visible=True)[source]¶

kind: str = 'labels'¶: Identifier prefix for this layer family.

render(ctx)[source]¶

Draw the layer into the map carried by ctx.

Called when the map is built. Implementations must set self._rendered = True once drawn.

Return type:: None

requires_gdf: bool = True¶: Whether a non-empty gdf is required at construction.

validate()[source]¶

Check internal consistency. Override in subclasses.

Raises in plain language (see errors.py convention) for structural problems such as a missing required parameter. Semiological advice is emitted as a warning, never an error.

Return type:: None

class mappyng.Vector(gdf=None, *, position=<unset>, z=<unset>, fill=<unset>, stroke=<unset>, stroke_width=<unset>, fill_opacity=<unset>, stroke_opacity=<unset>, stroke_linecap=<unset>, stroke_dasharray=<unset>, detail=<unset>, on_zoom=<unset>, on_cartouches=<unset>, z_index=0, visible=True)[source]¶

Bases: Layer

Raw vector layer drawn with explicit styling.

Parameters:

gdf (GeoDataFrame) – Geometries to draw.
position (str, optional) – "background" (default) or "top" relative to the data. Without position or z, a positive z_index implies "top".
z (int, optional) – Explicit stacking order, overriding position.
fill (str, optional) – Fill colour as #RRGGBB (default "none").
stroke (str, optional) – Stroke colour (default from style).
stroke_width (float, optional) – Stroke width (default from style).
fill_opacity (float, optional) – Fill opacity in [0, 1].
stroke_opacity (float, optional) – Stroke opacity in [0, 1]. A wide faint stroke under a thin bright one fakes a glowing line.
stroke_linecap (str, optional) – "butt", "round" or "square".
stroke_dasharray (str, optional) – SVG dash pattern, e.g. "4 2".
detail (GeoDataFrame or dict, optional) – Finer geometry drawn instead of gdf on the zoom window and the cartouches (see Choropleth). No join is needed: the finer geometries replace gdf’s.
on_zoom (bool, optional) – Draw on the zoom viewport (default False).
on_cartouches (bool, optional) – Draw on cartouche viewports (default True).
z_index (int, optional) – Render order among layers (default 0).
visible (bool, optional) – Whether the layer is drawn (default True).

Examples

>>> m.add(Vector(gdf, stroke="#333", stroke_width=0.4, position="top"))

__init__(gdf=None, *, position=<unset>, z=<unset>, fill=<unset>, stroke=<unset>, stroke_width=<unset>, fill_opacity=<unset>, stroke_opacity=<unset>, stroke_linecap=<unset>, stroke_dasharray=<unset>, detail=<unset>, on_zoom=<unset>, on_cartouches=<unset>, z_index=0, visible=True)[source]¶

kind: str = 'vector'¶: Identifier prefix for this layer family.

render(ctx)[source]¶

Draw the layer into the map carried by ctx.

Called when the map is built. Implementations must set self._rendered = True once drawn.

Return type:: None

requires_gdf: bool = True¶: Whether a non-empty gdf is required at construction.

Reference layers¶

class mappyng.Basemap(gdf=None, *, fill=<unset>, stroke=<unset>, stroke_width=<unset>, detail=<unset>, z_index=0, visible=True)[source]¶

Bases: Layer

Plain background drawn from the map’s main GeoDataFrame.

Parameters:

fill (str, optional) – Fill colour as #RRGGBB (default from style or the map’s basemap colour override).
stroke (str, optional) – Outline colour (default from style).
stroke_width (float, optional) – Outline width (default from style).
detail (GeoDataFrame or dict, optional) – Finer geometry drawn instead of the map’s GeoDataFrame on the zoom window and the cartouches. A GeoDataFrame applies to the zoom and every cartouche; a dict maps "zoom", "cartouches" or a cartouche index to a GeoDataFrame. See mappyng.detail.
z_index (int, optional) – Render order (default 0).
visible (bool, optional) – Whether the layer is drawn (default True).

Examples

>>> m.add(Basemap(fill="#f2efe9", stroke="#999999"))
>>> m.add(Basemap(detail=gdf_fine))  # finer geometry in zoom and cartouches

__init__(gdf=None, *, fill=<unset>, stroke=<unset>, stroke_width=<unset>, detail=<unset>, z_index=0, visible=True)[source]¶

kind: str = 'basemap'¶: Identifier prefix for this layer family.

render(ctx)[source]¶

Draw the layer into the map carried by ctx.

Called when the map is built. Implementations must set self._rendered = True once drawn.

Return type:: None

requires_gdf: bool = False¶: Whether a non-empty gdf is required at construction.

class mappyng.Graticule(gdf=None, *, step=<unset>, stroke=<unset>, opacity=<unset>, stroke_width=<unset>, dash=<unset>, position=<unset>, z=<unset>, z_index=0, visible=True)[source]¶

Bases: Layer

Latitude/longitude grid.

Parameters:

step (float, optional) – Spacing between lines in degrees (default 10).
stroke (str, optional) – Line colour as #RRGGBB (default "#aaaaaa").
opacity (float, optional) – Stroke opacity in [0, 1] (default 0.5).
stroke_width (float, optional) – Line width (default 0.5).
dash (str, optional) – SVG dash pattern (default "4 2").
position (str, optional) – "background" (default) draws the grid above the ocean but below the data; "top" draws it over everything, which suits globe-style maps.
z (int, optional) – Explicit stacking order, overriding position.
z_index (int, optional) – Render order among layers (default 0).
visible (bool, optional) – Whether the layer is drawn (default True).

Examples

>>> m.add(Graticule(step=5.0, stroke="#888888", opacity=0.4))

__init__(gdf=None, *, step=<unset>, stroke=<unset>, opacity=<unset>, stroke_width=<unset>, dash=<unset>, position=<unset>, z=<unset>, z_index=0, visible=True)[source]¶

kind: str = 'graticule'¶: Identifier prefix for this layer family.

render(ctx)[source]¶

Draw the layer into the map carried by ctx.

Called when the map is built. Implementations must set self._rendered = True once drawn.

Return type:: None

requires_gdf: bool = False¶: Whether a non-empty gdf is required at construction.

class mappyng.Tile(gdf=None, *, source=<unset>, zoom=<unset>, zoom_offset=<unset>, opacity=<unset>, z_order=<unset>, timeout=<unset>, cache=<unset>, cache_dir=<unset>, on_cartouches=<unset>, on_zoom=<unset>, max_tiles=<unset>, warp_scale=<unset>, extra_zoom_levels=<unset>, z_index=0, visible=True)[source]¶

Bases: Layer

XYZ raster tile backdrop.

Parameters:

source (str, optional) – Provider alias (e.g. "cartodb_positron", "osm", "satellite") or a URL template with {x}, {y}, {z} placeholders.
zoom (int or str, optional) – Zoom level, or "auto" (default) to derive it from the bbox.
zoom_offset (int, optional) – Added to the auto-calculated zoom (e.g. -1 for lighter tiles).
opacity (float, optional) – Tile opacity in [0, 1] (default 1).
z_order (int, optional) – SVG stacking order (default below the basemap).
timeout (float, optional) – HTTP request timeout in seconds (default 10).
cache (bool, optional) – Cache tiles on disk (default True).
cache_dir (str, optional) – Cache directory (default ~/.cache/mappyng/tiles).
on_cartouches (bool, optional) – Draw on cartouche viewports (default True).
on_zoom (bool, optional) – Draw on the zoom viewport (default True).
max_tiles (int, optional) – Safety cap on tiles downloaded per viewport (default 64).
warp_scale (float, optional) – Output resolution relative to the content area (default 1.5).
extra_zoom_levels (int, optional) – Number of coarser zoom levels to also fetch and blend (default 0).
z_index (int, optional) – Render order among layers (default 0).
visible (bool, optional) – Whether the layer is drawn (default True).

Examples

>>> m.add(Tile())
>>> m.add(Tile(source="satellite", opacity=0.7))

__init__(gdf=None, *, source=<unset>, zoom=<unset>, zoom_offset=<unset>, opacity=<unset>, z_order=<unset>, timeout=<unset>, cache=<unset>, cache_dir=<unset>, on_cartouches=<unset>, on_zoom=<unset>, max_tiles=<unset>, warp_scale=<unset>, extra_zoom_levels=<unset>, z_index=0, visible=True)[source]¶

kind: str = 'tile'¶: Identifier prefix for this layer family.

render(ctx)[source]¶

Draw the layer into the map carried by ctx.

Called when the map is built. Implementations must set self._rendered = True once drawn.

Return type:: None

requires_gdf: bool = False¶: Whether a non-empty gdf is required at construction.

class mappyng.Raster(gdf=None, *, paths=<unset>, opacity=<unset>, on_zoom=<unset>, on_cartouches=<unset>, z=<unset>, z_index=0, visible=True)[source]¶

Bases: Layer

Raster image overlay.

Parameters:

paths (dict or str) – Mapping of region name to GeoTIFF path, or a single path (required). Each viewport picks the raster whose footprint overlaps its bbox. Rasters must be in the map CRS; they are resampled to the viewport resolution and their no-data pixels are transparent.
opacity (float, optional) – Raster opacity in [0, 1] (default 1).
on_zoom (bool, optional) – Draw on the zoom viewport (default True).
on_cartouches (bool, optional) – Draw on cartouche viewports (default True).
z (int, optional) – Stacking depth. By default the raster is drawn behind every other layer; a larger value lifts it above lower layers.
z_index (int, optional) – Render order among layers (default 0).
visible (bool, optional) – Whether the layer is drawn (default True).

Examples

>>> m.add(Raster(paths={"metropole": "data/dem.tif"}, opacity=0.8))

__init__(gdf=None, *, paths=<unset>, opacity=<unset>, on_zoom=<unset>, on_cartouches=<unset>, z=<unset>, z_index=0, visible=True)[source]¶

kind: str = 'raster'¶: Identifier prefix for this layer family.

render(ctx)[source]¶

Draw the layer into the map carried by ctx.

Called when the map is built. Implementations must set self._rendered = True once drawn.

Return type:: None

requires_gdf: bool = False¶: Whether a non-empty gdf is required at construction.

validate()[source]¶

Check internal consistency. Override in subclasses.

Raises in plain language (see errors.py convention) for structural problems such as a missing required parameter. Semiological advice is emitted as a warning, never an error.

Return type:: None

class mappyng.DropShadow(gdf=None, *, query=<unset>, dx=<unset>, dy=<unset>, blur=<unset>, color=<unset>, opacity=<unset>, fill=<unset>, on_cartouches=<unset>, on_zoom=<unset>, z_index=0, visible=True)[source]¶

Bases: Layer

Blurred shadow cast by a set of geometries.

The geometries are dissolved into one outline, drawn below the data with a drop-shadow filter.

Parameters:

gdf (GeoDataFrame) – Geometries casting the shadow.
query (str, optional) – pandas query selecting the rows to shadow, e.g. "code_pays_iso3 == 'FRA'".
dx, dy (float, optional) – Shadow offset in pixels.
blur (float, optional) – Blur radius (SVG stdDeviation).
color (str, optional) – Shadow colour.
opacity (float, optional) – Shadow opacity in [0, 1].
fill (str, optional) – Fill of the shadow shape.
on_cartouches (bool, optional) – Draw on cartouche viewports (default True).
on_zoom (bool, optional) – Draw on the zoom viewport (default False).
z_index (int, optional) – Render order among layers (default 0).
visible (bool, optional) – Whether the layer is drawn (default True).

Examples

>>> m.add(DropShadow(europe, query="code_pays_iso3 == 'FRA'"))

__init__(gdf=None, *, query=<unset>, dx=<unset>, dy=<unset>, blur=<unset>, color=<unset>, opacity=<unset>, fill=<unset>, on_cartouches=<unset>, on_zoom=<unset>, z_index=0, visible=True)[source]¶

kind: str = 'shadow'¶: Identifier prefix for this layer family.

render(ctx)[source]¶

Draw the layer into the map carried by ctx.

Called when the map is built. Implementations must set self._rendered = True once drawn.

Return type:: None

requires_gdf: bool = True¶: Whether a non-empty gdf is required at construction.

class mappyng.OceanGradient(gdf=None, *, query=<unset>, width=<unset>, color=<unset>, opacity=<unset>, steps=<unset>, on_cartouches=<unset>, on_zoom=<unset>, z_index=0, visible=True)[source]¶

Bases: Layer

Gradient on the ocean, fading out from the coastline of a layer.

Drawn above the ocean colour (facecolor) and below everything else. It is built from nested buffers rather than an SVG filter, so PNG and PDF exports match the SVG.

Parameters:

gdf (GeoDataFrame) – Land geometries the gradient starts from, e.g. European countries.
query (str, optional) – pandas query selecting the rows to use.
width (float, optional) – Distance in pixels over which the gradient fades out (default 24).
color (str, optional) – Gradient colour along the coast (default "#ffffff", which lightens the ocean near the land).
opacity (float, optional) – Opacity of the gradient along the coast, in [0, 1] (default 0.45).
steps (int, optional) – Number of bands drawn (default 8). More bands give a smoother gradient and a larger file.
on_cartouches (bool, optional) – Draw on cartouche viewports (default True).
on_zoom (bool, optional) – Draw on the zoom viewport (default True).
z_index (int, optional) – Render order among layers (default 0).
visible (bool, optional) – Whether the layer is drawn (default True).

Examples

>>> m = m + OceanGradient(europe)
>>> m = m + OceanGradient(europe, color="#0b3a57", opacity=0.3)

__init__(gdf=None, *, query=<unset>, width=<unset>, color=<unset>, opacity=<unset>, steps=<unset>, on_cartouches=<unset>, on_zoom=<unset>, z_index=0, visible=True)[source]¶

kind: str = 'ocean_gradient'¶: Identifier prefix for this layer family.

render(ctx)[source]¶

Draw the layer into the map carried by ctx.

Called when the map is built. Implementations must set self._rendered = True once drawn.

Return type:: None

requires_gdf: bool = True¶: Whether a non-empty gdf is required at construction.

validate()[source]¶

Check internal consistency. Override in subclasses.

Raises in plain language (see errors.py convention) for structural problems such as a missing required parameter. Semiological advice is emitted as a warning, never an error.

Return type:: None

Reports¶

class mappyng.ClassificationReport(column, method, requested_classes, applied_classes, bins, counts, n_valid, n_excluded, cmap=None, colors=list(), adjustments=list())[source]¶

Bases: object

What a classification actually did, for inspection after rendering.

Parameters:

column (str) – Classified column.
method (str) – Method really applied ("Custom breaks" for an explicit list).
requested_classes, applied_classes (int) – Class count asked for and class count really produced.
bins (list of float) – Class bounds, minimum first (applied_classes + 1 values).
counts (list of int) – Number of features per class.
n_valid, n_excluded (int) – Features classified, and features left out because the value is NaN.
cmap (str or list of str) – Palette requested (a colormap name, or the explicit colour list).
colors (list of str) – Colour really used for each class, in class order, after any palette adjustment and after reverse.
adjustments (list of str) – Human-readable automatic corrections (snapped class count, merged classes, palette reduced to fewer colours…) with their reason. Empty when nothing was adjusted.

__init__(column, method, requested_classes, applied_classes, bins, counts, n_valid, n_excluded, cmap=None, colors=<factory>, adjustments=<factory>)¶

adjustments: list[str]¶

applied_classes: int¶

bins: list[float]¶

cmap: Any = None¶

colors: list[str]¶

column: str¶

counts: list[int]¶

method: str¶

n_excluded: int¶

n_valid: int¶

requested_classes: int¶

to_dataframe()[source]¶

One row per class: bounds, colour and number of features.

Return type:: Any

to_dict()[source]¶

Return type:: dict[str, Any]

class mappyng.CategoryReport(column, categories, counts, n_valid, n_excluded, unmapped=list())[source]¶

Bases: object

What a Category layer drew: features per category, exclusions.

Parameters:

column (str) – Column holding the categories.
categories (list) – Categories in legend order ("__default__" stands for the values drawn with default_fill).
counts (list of int) – Number of features per category.
n_valid, n_excluded (int) – Features drawn with a category colour, and features left out because the value is missing.
unmapped (list) – Values absent from fill_map that fell back to default_fill.

__init__(column, categories, counts, n_valid, n_excluded, unmapped=<factory>)¶

categories: list[Any]¶

column: str¶

counts: list[int]¶

n_excluded: int¶

n_valid: int¶

to_dataframe()[source]¶

One row per category with its number of features.

Return type:: Any

to_dict()[source]¶

Return type:: dict[str, Any]

unmapped: list[Any]¶