How-to Guides

Practical notebooks showing how to accomplish specific tasks with carto-flow. Each guide answers one focused question.

Flow Cartogram

Diagnose and Improve Convergence

Understand what CONVERGED, COMPLETED, and STALLED status mean, read error metrics, and apply the right fix — from iterative refinement with CartogramWorkflow to multi-resolution morphing.

Save and Export Results

Save a cartogram to disk and reload it, or export the morphed geometries to a GeoDataFrame / GeoPackage for use in GIS tools.

Reduce Boundary Distortion

Use prescale_components, DensityBorderExtension, anisotropy fields, and velocity modifiers like BoundaryDecay to control distortion at the edges of your cartogram.

Animate the Morphing Process

Capture intermediate frames with snapshot_every, build an animation with animate_morph_history(), and save to GIF or MP4.

Co-Morph Landmarks and Coordinates

Displace cities, annotations, or point coordinates consistently with the cartogram using landmarks (GeoDataFrames) or displacement_coords (NumPy arrays).

Proportional Cartogram

Apply Partitions to a Flow Cartogram

Combine the two modules: morph geometries with the flow cartogram, then apply proportional splits or shrinks to show a second variable within each region.

Symbol Cartogram

Style Symbols by Category

Separate layout computation from styling: map data columns to colors, shapes, opacity, hatching, and labels using plot() keyword arguments.

Create a Tile-Count Map

Use tile_count with the mosaic layout to give each region an integer number of tiles (e.g. parliamentary seats), place regions on a land mass too small to win a tile with min_one_tile_per_region, and hold a group's tiles together with group_by.

Choose Between the Grid and Mosaic Layouts

Run both tile-lattice layouts on the same input and compare what each preserves — neighbor relationships, contiguity of a region's tiles, the outline of the whole tilegram — with a decision table and the capability differences (group_by, tile_count, morph, presets).

Voronoi Cartogram

Choose the Right Backend

Compare RasterBackend (fast, pixel-based) and ExactBackend (exact Voronoi geometry, no weights support) with a timing and accuracy comparison and a decision table.

Coastal and Peninsula Regions

Prevent pixel labels from crossing bays and straits by switching to distance_mode="geodesic" — a BFS that propagates only through active (land) pixels.

Inspect and Improve Convergence

Read metrics, plot convergence curves and area errors, visualize displacement, and tune n_iter, area_cv_tol, prescale_components, and the relaxation schedule.

Analyze and Fix Topology

Detect satellite cells in grouped datasets with plot_topology(), and repair them post-hoc with repair_topology() or automatically via TopologyRepair in VoronoiOptions.

Customize the Boundary

Change the outer clipping shape ("union", "bbox", "circle", custom geometry) and choose between fixed, AdhesiveBoundary, and ElasticBoundary generator behavior.