Skip to content

carto_flow.symbol_cartogram.api

Symbol cartogram creation function and helpers.

This module contains the create_symbol_cartogram entry point and its private helpers. The __init__ module re-exports the public function.

Functions:

create_layout 

create_layout(
    gdf: GeoDataFrame,
    size: str | None = None,
    *,
    tile_count: str | None = None,
    group_by: str | None = None,
    layout: Layout | str = "packing",
    size_scale: Literal["sqrt", "linear", "log"] = "sqrt",
    size_max_value: float | None = None,
    size_clip: bool = True,
    size_normalization: Literal["max", "total"]
    | None = None,
    tile_size_expansion: Literal[
        "shared", "copied"
    ] = "copied",
    collapse_group: float = 0.0,
    adjacency_mode: AdjacencyMode = AdjacencyMode.BINARY,
    adjacency: NDArray | None = None,
    distance_tolerance: float | None = None,
    pre_scale: bool = False,
    show_progress: bool = True,
    save_history: bool = False,
) -> LayoutResult

Create a layout with preprocessing and algorithm execution.

This is the first step in the layout-styling separation pattern. The returned LayoutResult can be styled multiple times without re-running the expensive layout computation.

Parameters:

  • gdf (GeoDataFrame) –

    Input GeoDataFrame with polygon geometries.

  • size (str, default: None ) –

    Column for proportional sizing.

  • tile_count (str, default: None ) –

    Column with integer tile counts. Cannot be combined with group_by.

  • group_by (str, default: None ) –

    Column for grouping symbols. Cannot be combined with tile_count. Raises ValueError for layouts whose placement ignores the grouping (see Layout.supports_group_by).

  • layout (Layout or str, default: 'packing' ) –

    Layout instance or string shorthand, e.g. "packing", "grid", or "mosaic". Defaults to "packing".

  • size_scale (str, default: 'sqrt' ) –

    Scaling method for proportional sizing: "sqrt", "linear", or "log".

  • size_max_value (float, default: None ) –

    Reference max value for consistent scaling across cartograms.

  • size_clip (bool, default: True ) –

    Whether to clip values exceeding size_max_value.

  • size_normalization (('max', 'total'), default: "max" ) –

    How to normalize symbol sizes relative to original geometry areas:

    • "total": all sizes are scaled so that the total symbol area equals the total original geometry area (standard for Dorling cartograms).
    • "max": the largest symbol has area equal to the mean geometry area. With the default sqrt scale this makes the covered fraction of the map equal mean(value) / max(value), so it depends on how skewed the sizing column is.

    When omitted, each layout picks its own default: "total" for the layouts that place symbols by their radii, "max" for the grid layout, whose tile lattice is calibrated from the largest symbol.

  • collapse_group (float, default: 0.0 ) –

    Pre-collapse starting positions toward each group's centroid (0-1). At 1.0 all items in a group start coincident at the group centroid, matching tile_count behavior. Only has effect when group_by or tile_count is set. Default: 0.0.

  • adjacency_mode (AdjacencyMode, default: BINARY ) –

    How to compute adjacency: BINARY, WEIGHTED, or AREA_WEIGHTED.

  • adjacency (ndarray, default: None ) –

    Pre-computed adjacency matrix. If provided, adjacency_mode is ignored.

  • distance_tolerance (float, default: None ) –

    Buffer distance for adjacency detection.

  • pre_scale (bool, default: False ) –

    Uniformly scale each geographically connected component of the input so its area matches its share of the data before layout. Useful for multi-component inputs (e.g. mainland plus islands). Default False.

  • show_progress (bool, default: True ) –

    Display progress feedback during placement.

  • save_history (bool, default: False ) –

    Record position snapshots per iteration.

Returns:

  • LayoutResult –

    Immutable layout result ready for styling.

Examples:

>>> # Simple usage - default circle packing layout
>>> result = create_layout(gdf, "population")

>>> # String lookup with preprocessing options
>>> result = create_layout(gdf, "population", layout="grid", size_scale="linear")

>>> # Explicit Layout instance
>>> from carto_flow.symbol_cartogram import CirclePackingLayout, CirclePackingLayoutOptions
>>> layout = CirclePackingLayout(CirclePackingLayoutOptions(spacing=0.1))
>>> result = create_layout(gdf, "population", layout=layout)

>>> # Then style the result
>>> cartogram = result.style(symbol="hexagon", scale=0.9)

create_symbol_cartogram 

create_symbol_cartogram(
    gdf: GeoDataFrame,
    size: str | None = None,
    *,
    tile_count: str | None = None,
    group_by: str | None = None,
    layout: Layout | str = "packing",
    size_scale: Literal["sqrt", "linear", "log"] = "sqrt",
    size_max_value: float | None = None,
    size_clip: bool = True,
    size_normalization: Literal["max", "total"]
    | None = None,
    tile_size_expansion: Literal[
        "shared", "copied"
    ] = "copied",
    collapse_group: float = 0.0,
    adjacency_mode: AdjacencyMode = AdjacencyMode.BINARY,
    adjacency: NDArray | None = None,
    distance_tolerance: float | None = None,
    pre_scale: bool = False,
    show_progress: bool = True,
    save_history: bool = False,
    styling: Styling | None = None,
) -> SymbolCartogram

Create a symbol cartogram from a GeoDataFrame.

Each region is represented by a single symbol (circle, square, or hexagon). Symbol size is proportional to a data value when size is provided, or uniform when it is omitted.

This is a convenience function that combines layout computation and styling in a single call. For more control, use create_layout and then apply styling via LayoutResult.style() or Styling.apply().

Parameters:

  • gdf (GeoDataFrame) –

    Input GeoDataFrame with polygon geometries.

  • size (str, default: None ) –

    Column for proportional sizing. When provided, symbols are sized proportionally to values. When absent, all symbols have uniform size.

  • tile_count (str, default: None ) –

    Column with integer tile counts. When provided, each region is represented by that many symbols. Cannot be combined with group_by.

  • group_by (str, default: None ) –

    Column for grouping symbols. When provided, group_index is stored on the result for group-level styling and export. Cannot be combined with tile_count. Raises ValueError for layouts whose placement ignores the grouping (see Layout.supports_group_by).

  • layout (Layout or str, default: 'packing' ) –

    Layout instance or string shorthand, e.g. "packing", "grid", or "mosaic". Defaults to "packing". Pass a Layout instance for full control over algorithm options.

  • size_scale (str, default: 'sqrt' ) –

    Scaling method for proportional sizing: "sqrt", "linear", or "log".

  • size_max_value (float, default: None ) –

    Reference max value for consistent scaling across cartograms.

  • size_clip (bool, default: True ) –

    Whether to clip values exceeding size_max_value.

  • size_normalization (('max', 'total'), default: "max" ) –

    How to normalize symbol sizes relative to original geometry areas:

    • "total": all sizes are scaled so that the total symbol area equals the total original geometry area (standard for Dorling cartograms).
    • "max": the largest symbol has area equal to the mean geometry area. With the default sqrt scale this makes the covered fraction of the map equal mean(value) / max(value), so it depends on how skewed the sizing column is.

    When omitted, each layout picks its own default: "total" for the layouts that place symbols by their radii, "max" for the grid layout, whose tile lattice is calibrated from the largest symbol.

  • collapse_group (float, default: 0.0 ) –

    Pre-collapse starting positions toward each group's centroid (0-1). At 1.0 all items in a group start coincident at the group centroid, matching tile_count behavior. Only has effect when group_by or tile_count is set. Default: 0.0.

  • adjacency_mode (AdjacencyMode, default: BINARY ) –

    How to compute adjacency: BINARY, WEIGHTED, or AREA_WEIGHTED.

  • adjacency (ndarray, default: None ) –

    Pre-computed adjacency matrix. If provided, adjacency_mode is ignored.

  • distance_tolerance (float, default: None ) –

    Buffer distance for adjacency detection.

  • pre_scale (bool, default: False ) –

    Uniformly scale each geographically connected component of the input so its area matches its share of the data before layout. Useful for multi-component inputs (e.g. mainland plus islands). Default False.

  • show_progress (bool, default: True ) –

    Display progress feedback during placement.

  • save_history (bool, default: False ) –

    Record position snapshots per iteration.

  • styling (Styling or None, default: None ) –

    Styling configuration. If None, uses defaults (circle symbol, scale=1.0).

Returns:

  • SymbolCartogram –

    Result object containing symbol geometries and metrics.

Examples:

Proportional sizing (Dorling-style):

>>> result = create_symbol_cartogram(gdf, "population")

With layout options:

>>> from carto_flow.symbol_cartogram import CirclePackingLayout, CirclePackingLayoutOptions
>>> layout = CirclePackingLayout(CirclePackingLayoutOptions(spacing=0.1, max_iterations=1000))
>>> result = create_symbol_cartogram(gdf, "population", layout=layout)

With styling:

>>> from carto_flow.symbol_cartogram import Styling
>>> styling = Styling(symbol="hexagon", scale=0.9)
>>> result = create_symbol_cartogram(gdf, "population", styling=styling)

Grid layout with preprocessing options:

>>> result = create_symbol_cartogram(
...     gdf, "population",
...     layout="grid",
...     size_scale="linear",
...     adjacency_mode=AdjacencyMode.WEIGHTED,
... )