carto_flow.proportional_cartogram.visualization

Visualization utilities for proportional_cartogram results.

Plotting utilities for visualizing partitioned geometries from shrink, split, and partition_geometries operations.

Main Components

• plot_partitions: Plot partitioned geometries as a choropleth map

Example

from carto_flow.proportional_cartogram import partition_geometries from carto_flow.proportional_cartogram.visualization import plot_partitions

result = partition_geometries(gdf, ['agriculture', 'industry'], method='split') plot_partitions(result)

Functions:

• plot_partitions –

  Plot partitioned geometries as a choropleth map.

plot_partitions

plot_partitions(
    gdf: GeoDataFrame,
    columns: list[str] | None = None,
    color_by: Literal["area", "category"]
    | list[str] = "area",
    cmap: str | None = None,
    palette: dict[str, str] | None = None,
    vmin: float | None = None,
    vmax: float | None = None,
    edgecolor: str = "white",
    linewidth: float = 0.5,
    highlight: str | list[str] | None = None,
    background_alpha: float | None = None,
    background_color: str | None = None,
    background_saturation: float | None = None,
    background_lightness: float | None = None,
    background_edgecolor: str | None = None,
    background_linewidth: float | None = None,
    include_complement: bool = True,
    complement_color_by: str | None = None,
    complement_color: str = "#e0e0e0",
    complement_alpha: float = 1.0,
    complement_edgecolor: str | None = None,
    complement_linewidth: float | None = None,
    ax: Axes | None = None,
    legend: bool = True,
    **kwargs: Any,
) -> PartitionsPlotResult

Plot partitioned geometries as a choropleth map.

Takes the output of partition_geometries() and plots all partition geometries together, with coloring based on area, category, or data values.

Parameters:

• gdf (GeoDataFrame) –

  Output from partition_geometries() containing geometry columns named geometry_{column} for each input column.

• columns (list[str], default: None ) –

  Original column names used in partition_geometries(). If None, auto-detects from geometry column names (geometry_* pattern).

• color_by (('area', 'category'), default: 'area' ) –

  How to color the partitions:

  • 'area': Color by partition area (continuous colormap)
  • 'category': Color by partition category/column name (categorical)
  • list[str]: Data column names for each partition. Length must match number of partitions. Single-element list colors all partitions by that column.
• cmap (str, default: None ) –

  Colormap name for continuous data. Defaults to 'viridis'.

• palette (dict[str, str], default: None ) –

  Color mapping for categorical data. Keys are category values, values are colors. If not provided, uses cmap or 'tab10'.

• vmin (float, default: None ) –

  Value range for continuous colormap normalization.

• vmax (float, default: None ) –

  Value range for continuous colormap normalization.

• edgecolor (str, default: 'white' ) –

  Edge color for partition boundaries.

• linewidth (float, default: 0.5 ) –

  Line width for partition boundaries.

• highlight (str or list[str], default: None ) –

  Partition category/categories to highlight. Other partitions are styled according to background_* parameters.

• background_alpha (float, default: None ) –

  Alpha (transparency) for non-highlighted partitions.

• background_color (str, default: None ) –

  Fixed color for non-highlighted partitions. Overrides data coloring.

• background_saturation (float, default: None ) –

  Saturation multiplier (0-1) for non-highlighted partitions. 0 = grayscale, 1 = original saturation.

• background_lightness (float, default: None ) –

  Lightness multiplier for non-highlighted partitions. 0 = black, 1 = original, 2 = white.

• background_edgecolor (str, default: None ) –

  Edge color for non-highlighted partitions. Defaults to edgecolor.

• background_linewidth (float, default: None ) –

  Line width for non-highlighted partitions. Defaults to linewidth.

• include_complement (bool, default: True ) –

  Whether to include the complement geometry (remainder) in the plot.

• complement_color_by (str, default: None ) –

  Data column to use for complement coloring. If None, uses complement_color.

• complement_color (str, default: '#e0e0e0' ) –

  Fixed color for complement when complement_color_by is None.

• complement_alpha (float, default: 1.0 ) –

  Alpha for complement partitions.

• complement_edgecolor (str, default: None ) –

  Edge color for complement. Defaults to edgecolor.

• complement_linewidth (float, default: None ) –

  Line width for complement. Defaults to linewidth.

• ax (Axes, default: None ) –

  Axes to plot on. If None, creates a new figure.

• legend (bool, default: True ) –

  Whether to show a legend or colorbar.

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

  Additional arguments passed to GeoDataFrame.plot().

Returns:

• PartitionsPlotResult –

  Result with the axes and named artist references.

Raises:

• ValueError –

  If color_by list length doesn't match partition count, or if specified columns don't exist.

Examples:

Plot partitions colored by area:

>>> result = partition_geometries(gdf, ['pop_a', 'pop_b'], method='split')
>>> plot_partitions(result)

Plot partitions colored by category:

>>> plot_partitions(result, color_by='category')

Color each partition by its corresponding data column:

>>> plot_partitions(result, color_by=['pop_a', 'pop_b'])

Highlight specific partition with others faded:

>>> plot_partitions(result, highlight='pop_a', background_alpha=0.3)

Highlight with desaturated background:

>>> plot_partitions(result, highlight='pop_a', background_saturation=0.2)

Custom complement styling:

>>> plot_partitions(result, complement_color_by='remainder_value')