carto_flow.voronoi_cartogram.visualization

Visualization utilities for Voronoi cartogram results.

Functions:

• plot_cartogram –

  Plot Voronoi cells, optionally colored by a data column.

• plot_comparison –

  Side-by-side comparison of original geometries vs Voronoi cells.

• plot_convergence –

  Plot CV(area) over Lloyd iterations.

• plot_displacement –

  Centroids and displacement arrows on a single axis.

• plot_topology –

  Topology issues (satellites, violated adjacency, misaligned orientation) overlaid on the Voronoi cells.

• plot_topology_repair –

  Before/after comparison of a topology repair operation.

• plot_compactness –

  Per-cell inertia (distance to group centroid) as a choropleth — shows which cells the compactness repair considers outliers.

Examples:

>>> from carto_flow.voronoi_cartogram import create_voronoi_cartogram
>>> from carto_flow.voronoi_cartogram.visualization import plot_comparison, plot_convergence
>>> result = create_voronoi_cartogram(gdf)
>>> plot_comparison(gdf, result)
>>> plot_convergence(result)

plot_cartogram

plot_cartogram(
    result: VoronoiCartogram,
    column: str | None = None,
    cmap: str | None = None,
    show_edges: bool = True,
    legend: bool = False,
    labels: bool | str | list[str] | None = None,
    label_fontsize: int = 8,
    label_color: str = "black",
    label_location: str = "centroid",
    ax: Any | None = None,
    **kwargs: Any,
) -> VoronoiPlotResult

Plot Voronoi cells.

Parameters:

• result (VoronoiCartogram) –

  The cartogram to plot.

• column (str or None, default: None ) –

  Column from the source GeoDataFrame to use for choropleth coloring. None (default) colors each cell with a distinct categorical color derived from its index. Pass "area_error_pct" to plot the signed per-cell area error as a diverging choropleth.

• cmap (str or None, default: None ) –

  Colormap name. Defaults to "tab20" for categorical coloring (column=None), "RdBu_r" for "area_error_pct", and "viridis" for other numeric columns.

• show_edges (bool, default: True ) –

  Draw cell borders. Default True.

• legend (bool, default: False ) –

  Show a legend or colorbar. Default False.

• labels (bool, str, list of str, or None, default: None ) –

  Annotate each cell with a text label.

  • True — use the source GeoDataFrame index values.
  • str — column name in the source GeoDataFrame.
  • list[str] — explicit label strings (length must equal number of cells).
  • None / False — no labels (default).
• label_fontsize (int, default: 8 ) –

  Font size for cell labels. Default 8.

• label_color (str, default: 'black' ) –

  Text color for cell labels. Default "black".

• label_location (str, default: 'centroid' ) –

  Where to place labels within each cell. Default "centroid" (the geometric centroid). Other options are "representative" (a representative point guaranteed to be inside the cell), or "generator" (the Voronoi cell generator point).

• ax (matplotlib Axes or None, default: None ) –

  Axes to draw on. A new figure is created if None.

• **kwargs (Any, default: {} ) –

  Passed to GeoDataFrame.plot().

Returns:

• VoronoiPlotResult –

  Dataclass with ax and collections.

plot_compactness

plot_compactness(
    cartogram: VoronoiCartogram,
    group_by: str,
    *,
    normalize: bool = True,
    cmap: str = "YlOrRd",
    show_centroids: bool = True,
    show_edges: bool = True,
    legend: bool = True,
    ax: Any | None = None,
    figsize: tuple[float, float] = (10, 8),
    title: str = "Compactness",
) -> VoronoiPlotResult

Plot per-cell inertia — the compactness measure used by topology repair.

For each district d in group g the inertia is ||cell_centroid[d] - group_centroid[g]||², matching the internal measure used by _repair_compactness. By default the value is normalized within each group (divided by the group mean) so that cells in different-sized groups can be compared on the same scale: values above 1 are outliers relative to their group, values below 1 are compact.

Parameters:

• cartogram (VoronoiCartogram) –

  The cartogram to analyze.

• group_by (str) –

  Column in the source GeoDataFrame identifying groups (same argument as repair_topology).

• normalize (bool, default: True ) –

  Divide each cell's inertia by the group mean. Default True.

• cmap (str, default: 'YlOrRd' ) –

  Matplotlib colormap name. Default "YlOrRd".

• show_centroids (bool, default: True ) –

  Overlay group centroids as small black markers. Default True.

• show_edges (bool, default: True ) –

  Draw cell borders. Default True.

• legend (bool, default: True ) –

  Show a colorbar. Default True.

• ax (matplotlib Axes or None, default: None ) –

  Axes to draw on. A new figure is created if None.

• figsize (tuple of float, default: (10, 8) ) –

  Figure size when ax is None.

• title (str, default: 'Compactness' ) –

  Axis title.

Returns:

• VoronoiPlotResult –

  Dataclass with ax and collections.

plot_comparison

plot_comparison(
    gdf: GeoDataFrame,
    result: VoronoiCartogram,
    *,
    column: str | None = None,
    cmap: str | None = None,
    axes: Any | None = None,
    figsize: tuple[float, float] = (14, 6),
    title: str | None = None,
) -> VoronoiPlotResult

Side-by-side comparison of original geometries vs Voronoi cells.

Parameters:

• gdf (GeoDataFrame) –

  Original input geometries.

• result (VoronoiCartogram) –

  The cartogram to compare against.

• column (str or None, default: None ) –

  Column to use for choropleth coloring on both panels. None uses categorical index coloring.

• cmap (str or None, default: None ) –

  Colormap name. Defaults to "tab20" (categorical) or "viridis" (numeric).

• axes (sequence of two Axes, or None, default: None ) –

  Existing axes to draw on. A new (1, 2) figure is created when None.

• figsize (tuple of float, default: (14, 6) ) –

  Figure size when axes is None.

• title (str or None, default: None ) –

  Figure suptitle. Defaults to "Original vs Voronoi Cartogram".

Returns:

• VoronoiPlotResult –

  ax is a tuple (ax_original, ax_cartogram).

plot_convergence

plot_convergence(
    result: VoronoiCartogram,
    *,
    ax: Any | None = None,
    figsize: tuple[float, float] = (7, 3),
    title: str = "Lloyd relaxation convergence",
    log_scale: bool = False,
) -> VoronoiPlotResult

Plot CV(area) over Lloyd iterations.

Parameters:

• result (VoronoiCartogram) –

  The cartogram whose :attr:~VoronoiCartogram.convergence_history is plotted.

• ax (matplotlib Axes or None, default: None ) –

  Axes to draw on. A new figure is created if None.

• figsize (tuple of float, default: (7, 3) ) –

  Figure size when ax is None.

• title (str, default: 'Lloyd relaxation convergence' ) –

  Axis title.

• log_scale (bool, default: False ) –

  Use a log scale on the y-axis. Default False.

Returns:

• VoronoiPlotResult –

  Dataclass with ax and collections.

plot_displacement

plot_displacement(
    result: VoronoiCartogram,
    *,
    state: str = "final",
    show_geometries: bool = True,
    show_centroids: bool = True,
    show_adjacency: bool = True,
    show_positions: bool = False,
    show_displacement: bool = True,
    legend: bool = True,
    geometry_style: dict | None = None,
    adjacency_style: dict | None = None,
    centroid_style: dict | None = None,
    position_style: dict | None = None,
    displacement_style: dict | None = None,
    ax: Any | None = None,
    figsize: tuple[float, float] = (10, 8),
    title: str = "Voronoi cartogram — centroid redistribution",
) -> VoronoiPlotResult

Plot centroids and displacement arrows on a single axis.

Parameters:

• result (VoronoiCartogram) –

  The cartogram to visualize.

• state (('original', 'final'), default: "original" ) –

  Which state to visualize. "original" draws the source geometries and their centroids; "final" (default) draws the Voronoi cells and their centroids. Displacement arrows always run original → final regardless of this setting.

• show_geometries (bool, default: True ) –

  Draw geometry polygons behind the centroid scatter. Default True.

• show_centroids (bool, default: True ) –

  Draw centroid scatter markers. Default True.

• show_adjacency (bool, default: True ) –

  Draw adjacency graph edges. Default True.

• show_positions (bool, default: False ) –

  Also scatter result.positions (the Lloyd generator points) as a secondary marker (only used when state="final"). Default False.

• show_displacement (bool, default: True ) –

  Draw colored arrows from original to final cell-centroid positions. Default True.

• legend (bool, default: True ) –

  Show the displacement-magnitude colorbar (and any other legends). Default True.

• geometry_style (dict or None, default: None ) –

  Styling for geometry polygons, merged over defaults {"facecolor": "#e8eef4", "edgecolor": "#9aafc4", "linewidth": 0.4, "alpha": 0.6}. All keys forwarded to GeoDataFrame.plot().

  The "color" key supports multi-type resolution:

  • str matching a column → choropleth; use "cmap" (default "Blues") to set the colormap.
  • any other str → solid fill color.
  • 1-D numeric array → per-geometry values mapped via "cmap".
  • list/array of color strings → per-geometry colors.
• adjacency_style (dict or None, default: None ) –

  Styling for adjacency graph edges, merged over defaults {"color": "#6b8fa8", "linewidth": 0.6, "alpha": 0.5, "zorder": 2}. All keys forwarded to ax.plot().

• centroid_style (dict or None, default: None ) –

  Styling for centroid scatter markers, merged over defaults {"s": 18, "c": "#1a5276", "zorder": 3, "linewidths": 0}. All keys forwarded to ax.scatter().

  The "c" (or "color") key supports the same multi-type resolution as geometry_style["color"]; use "cmap" (default "viridis") for column/numeric cases.

• position_style (dict or None, default: None ) –

  Styling for the result.positions generator-point overlay (only used when show_positions=True), merged over defaults {"s": 14, "marker": "x", "c": "#e74c3c", "zorder": 5, "linewidths": 0.8}. All keys forwarded to ax.scatter().

• displacement_style (dict or None, default: None ) –

  Styling for displacement arrows, merged over defaults {"cmap": "plasma", "lw": 0.9, "mutation_scale": 6, "arrowstyle": "-|>", "min_frac": 0.01}.

  • "cmap" — arrow/colorbar colormap.
  • "min_frac" — skip arrows whose magnitude is below this fraction of the maximum.
  • remaining keys forwarded into arrowprops.
• ax (matplotlib Axes or None, default: None ) –

  Axes to draw on. A new figure is created if None.

• figsize (tuple of float, default: (10, 8) ) –

  Figure size used when ax is None.

• title (str, default: 'Voronoi cartogram — centroid redistribution' ) –

  Axis title.

Returns:

• VoronoiPlotResult –

  Dataclass with ax and collections.

Raises:

• RuntimeError –

  If no source GeoDataFrame is stored on the result.

• ValueError –

  If state is not "original" or "final".

plot_topology

plot_topology(
    analysis: TopologyAnalysis,
    cartogram: VoronoiCartogram,
    *,
    show_base: bool | None = None,
    show_contiguity: bool = True,
    show_adjacency: bool = True,
    show_orientation: bool = True,
    ax: Any | None = None,
    figsize: tuple[float, float] = (10, 8),
    title: str = "Topology Analysis",
) -> VoronoiPlotResult

Plot topology issues overlaid on the Voronoi cells.

Parameters:

• analysis (TopologyAnalysis) –

  The analysis result to visualize.

• cartogram (VoronoiCartogram) –

  The cartogram whose cells provide the spatial context.

• show_base (bool or None, default: None ) –

  Draw all cells as a gray background layer. None (default) draws the base only when ax is None (i.e. a new figure is created); when an existing ax is supplied the base is skipped so that any prior plot on that axis is not hidden. Pass True or False to override the automatic behavior.

• show_contiguity (bool, default: True ) –

  Highlight satellite cells (stage 1 issues). Default True.

• show_adjacency (bool, default: True ) –

  Draw lines between centroids of violated adjacency pairs (stage 2 issues). Default True.

• show_orientation (bool, default: True ) –

  Draw arrows for misaligned Voronoi-adjacent pairs (stage 3 issues). Default True.

• ax (matplotlib Axes or None, default: None ) –

  Axes to draw on. A new figure is created if None.

• figsize (tuple of float, default: (10, 8) ) –

  Figure size when ax is None.

• title (str, default: 'Topology Analysis' ) –

  Axis title.

Returns:

• VoronoiPlotResult –

  Dataclass with ax and collections.

plot_topology_repair

plot_topology_repair(
    report: TopologyRepairReport,
    *,
    show_base: bool | None = None,
    show_issues: bool = True,
    show_reassigned: bool = True,
    axes: Any | None = None,
    figsize: tuple[float, float] = (16, 8),
    title: str | None = None,
) -> VoronoiPlotResult

Plot a before/after comparison of the topology repair.

Parameters:

• report (TopologyRepairReport) –

  The repair report to visualize.

• show_base (bool or None, default: None ) –

  Draw all cells as a gray background layer in each panel. None (default) draws the base only when axes is None (new figure); when existing axes are supplied the base is skipped so prior content is not hidden. Pass True or False to override.

• show_issues (bool, default: True ) –

  Overlay topology-issue highlights (satellite cells, violated adjacency lines, misaligned orientation arrows) on both panels. Default True.

• show_reassigned (bool, default: True ) –

  Highlight reassigned cells in the after panel with a thick green border. Default True.

• axes (sequence of two Axes, or None, default: None ) –

  Existing axes to draw on. A new (1, 2) figure is created when None.

• figsize (tuple of float, default: (16, 8) ) –

  Figure size when axes is None. Default (16, 8).

• title (str or None, default: None ) –

  Figure suptitle. Defaults to "Topology Repair — {stages_run}".

Returns:

• VoronoiPlotResult –

  ax is a tuple (ax_before, ax_after).

Notes

When :attr:~TopologyRepairReport._original_cartogram is None (e.g., the report was reconstructed from disk), only the after panel is rendered and a UserWarning is emitted.