Symbol Cartogram¶

Create cartograms where each geographic region is represented by a single symbol.

Overview¶

The symbol_cartogram module provides tools for creating Dorling-style cartograms, tile maps, and other symbol-based visualizations. Each region is represented by a symbol (circle, square, hexagon, or custom shape) with size proportional to a data value or uniform.

Core Concepts: - Layout: Computation of symbol positions and sizes - Styling: Application of symbol shapes, colors, and transforms - Tiling: Grid-based symbol placement and arrangement

graph TD
    A[Input GeoDataFrame] --> B[Data Preprocessing]
    B --> C[Layout Computation]
    C --> D[LayoutResult]
    D --> E[Styling]
    E --> F[SymbolCartogram]

Main Interface¶

Sub-module	Description
API	Main functions: `create_symbol_cartogram`, `create_layout`
Layouts	Layout algorithms: `CirclePackingLayout`, `FlowDensityLayout`, `GridBasedLayout`, `MosaicLayout`, etc.
LayoutResult	Immutable layout output with transforms
Result	`SymbolCartogram` result container
Styling	Symbol styling configuration

Configuration¶

Sub-module	Description
Options	Configuration options for layouts
Presets	Pre-configured cartogram styles

Symbols and Tiling¶

Sub-module	Description
Symbols	Symbol classes: `CircleSymbol`, `HexagonSymbol`, etc.
Tiling	Tiling classes: `HexagonTiling`, `IsohedralTiling`, etc.

Output¶

Sub-module	Description
Visualization	Plotting functions

Workflow Patterns¶

Basic Usage¶

from carto_flow.symbol_cartogram import create_symbol_cartogram

result = create_symbol_cartogram(gdf, "population")
result.plot(column="population", cmap="Reds")

gdf_result = result.to_geodataframe()
result.save("symbol_cartogram.gpkg")

Layout-Styling Separation¶

from carto_flow.symbol_cartogram import create_layout

# Compute layout once, experiment with different styles
layout_result = create_layout(gdf, "population", layout="packing")

circle_result = layout_result.style(symbol="circle", scale=1.0)
square_result = layout_result.style(symbol="square", scale=0.8)
hexagon_result = layout_result.style(symbol="hexagon", scale=0.9)

Flow Density Layout¶

from carto_flow.symbol_cartogram import create_symbol_cartogram, FlowDensityLayout

# Basic flow density layout
result = create_symbol_cartogram(gdf, "population", layout=FlowDensityLayout())

# Grouped by region: districts cluster within their parent region
result = create_symbol_cartogram(
    gdf,
    "population",
    group_by="region",
    layout=FlowDensityLayout(spacing=0.15, cross_group_pull_scale=0.0),
)

Custom Layout and Styling¶

from carto_flow.symbol_cartogram import (
    create_symbol_cartogram,
    CirclePackingLayout,
    CirclePackingLayoutOptions,
    Styling,
)

layout = CirclePackingLayout(CirclePackingLayoutOptions(
    spacing=0.15,
    max_iterations=2000,
))

styling = Styling(symbol="hexagon", scale=0.85)

result = create_symbol_cartogram(gdf, "population", layout=layout, styling=styling)
result.plot(column="population", facecolor="#ff6b6b")

Using Presets¶

Presets are named entry points that wrap create_symbol_cartogram with a particular algorithmic style and expose only the parameters that matter for it. Each one returns a SymbolCartogram directly.

from carto_flow.symbol_cartogram import tile_map_cartogram

# Uniform hexagons on a grid; no size column — a tile map, not a proportional cartogram
result = tile_map_cartogram(gdf)
result.plot(column="region", cmap="Set3", source_gdf=gdf)

from carto_flow.symbol_cartogram import geographic_grouped_cartogram

# Proportional circles that stay near their geographic position and cluster by group
result = geographic_grouped_cartogram(gdf, "population", group_by="region")
result.plot(column="population", cmap="Reds")

The full set is centroid_cartogram, dorling_cartogram, geographic_cartogram, dorling_grouped_cartogram, geographic_grouped_cartogram, demers_cartogram and tile_map_cartogram; see Presets for the parameters of each.

Tiled and Grouped Layouts¶

from carto_flow.symbol_cartogram import create_symbol_cartogram, CirclePackingLayout

# tile_count: each region gets an integer number of symbols
result = create_symbol_cartogram(gdf, tile_count="seats", layout="grid")
result.plot()

# group_by: group symbols by region (layouts that honor it: centroid,
# flow_density, mosaic, packing)
result = create_symbol_cartogram(
    gdf, size="population", group_by="region", layout=CirclePackingLayout(group_weight=0.5)
)
gdf_regions = result.to_geodataframe(level="group")  # one row per region, union geometry

Group-level Styling¶

from carto_flow.symbol_cartogram import create_layout, Styling

layout_result = create_layout(gdf, tile_count="seats", layout="grid")

styling = (
    Styling(symbol="hexagon")
    .set_group_symbol("circle", group_indices=[0, 3])
    .group_transform(scale=0.7, group_indices=[1])
)
result = layout_result.style(styling)

Error Handling¶

Exception	Description
`ValueError`	Invalid input parameters, missing geometry column
`TypeError`	Incorrect parameter types
`RuntimeError`	Layout computation failed