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,
    value_column: str | None = None,
    *,
    layout: Layout | str = "physics",
    size_scale: Literal["sqrt", "linear", "log"] = "sqrt",
    size_max_value: float | None = None,
    size_clip: bool = True,
    size_normalization: Literal["max", "total"] = "max",
    adjacency_mode: AdjacencyMode = AdjacencyMode.BINARY,
    adjacency: NDArray | None = None,
    distance_tolerance: float | None = None,
    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.

  • value_column (str, default: None ) –

    Column for proportional sizing.

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

    Layout instance or string shorthand ("physics", "topology", "grid").

  • 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 (str, default: 'max' ) –

    How to normalise symbol sizes relative to original geometry areas:

    • "max" (default): the largest symbol has area equal to the mean geometry area.
    • "total": all sizes are scaled so that the total symbol area equals the total original geometry area.
  • 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.

  • 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 physics 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 PhysicsBasedLayout, TopologySimulatorOptions
>>> layout = PhysicsBasedLayout(TopologySimulatorOptions(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,
    value_column: str | None = None,
    *,
    layout: Layout | str = "physics",
    size_scale: Literal["sqrt", "linear", "log"] = "sqrt",
    size_max_value: float | None = None,
    size_clip: bool = True,
    size_normalization: Literal["max", "total"] = "max",
    adjacency_mode: AdjacencyMode = AdjacencyMode.BINARY,
    adjacency: NDArray | None = None,
    distance_tolerance: float | None = None,
    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 value_column 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.

  • value_column (str, default: None ) –

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

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

    Layout instance or string shorthand ("physics", "topology", "grid"). 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 (str, default: 'max' ) –

    How to normalise symbol sizes relative to original geometry areas:

    • "max" (default): the largest symbol has area equal to the mean geometry area.
    • "total": all sizes are scaled so that the total symbol area equals the total original geometry area. Useful when you want circle area-sum to match the geographic area-sum (standard for Dorling cartograms).
  • 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.

  • 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 PhysicsBasedLayout, TopologySimulatorOptions
>>> layout = PhysicsBasedLayout(TopologySimulatorOptions(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,
... )