Skip to content

carto_flow.flow_cartogram.workflow

Workflow class for iterative cartogram refinement.

This module provides the CartogramWorkflow class for managing iterative cartogram refinement workflows. It stores a sequence of Cartogram objects and provides methods for morphing, multi-resolution morphing, and state management.

Classes:

Examples:

>>> from carto_flow import CartogramWorkflow, MorphOptions
>>>
>>> workflow = CartogramWorkflow(gdf, 'population')
>>> workflow.morph()                      # Initial morph
>>> workflow.morph(mean_tol=0.01)         # Refine with tighter tolerance
>>>
>>> # Access results
>>> workflow.original                     # Initial unmorphed state
>>> workflow.latest                       # Most recent result
>>> workflow[1]                           # First morph result
>>>
>>> # Export
>>> gdf_result = workflow.to_geodataframe()

CartogramWorkflow 

CartogramWorkflow(
    gdf: Any,
    column: str,
    landmarks: Any = None,
    coords: Any = None,
    options: MorphOptions | None = None,
    density_per: Literal[
        "m2", "km2", "ha", "acre", "sqft", "sqmi"
    ]
    | None = None,
)

Workflow for iterative cartogram refinement.

Manages a sequence of Cartogram objects where index 0 is the original (unmorphed) state. Provides methods for morphing, multi-resolution morphing, and state management.

Parameters:

  • gdf (GeoDataFrame) –

    GeoDataFrame containing polygon geometries and data values.

  • column (str) –

    Name of the column containing data values for cartogram generation.

  • landmarks (GeoDataFrame, default: None ) –

    Optional landmarks GeoDataFrame for tracking reference points.

  • coords (array - like, default: None ) –

    Coordinates for displacement field computation.

  • options (MorphOptions, default: None ) –

    Base options for morphing.

  • density_per ((m2, km2, ha, acre, sqft, sqmi), default: 'm2' ) –

    Unit for density calculations. If specified, automatically computes the appropriate area_scale based on the GeoDataFrame's CRS units.

Examples:

>>> workflow = CartogramWorkflow(gdf, 'population')
>>> workflow.morph()                      # Initial morph
>>> workflow.morph(mean_tol=0.01)         # Refine
>>>
>>> # With density in people per km²
>>> workflow = CartogramWorkflow(gdf, 'population', density_per='km2')
>>>
>>> # Access results
>>> workflow.original                     # Initial state
>>> workflow.latest                       # Most recent
>>> workflow[1]                           # First morph result
>>>
>>> # Export
>>> gdf_result = workflow.to_geodataframe()

Methods:

  • __getitem__ –

    Get result by index (0 = original).

  • __iter__ –

    Iterate over all results.

  • __len__ –

    Number of results (including original).

  • __repr__ –

    Concise string representation.

  • morph –

    Morph geometries (initial or refinement).

  • morph_multiresolution –

    Multi-resolution morphing with progressive refinement.

  • pop –

    Remove and return the last n results.

  • reset –

    Remove all morph results, keeping only original.

  • to_geodataframe –

    Export a cartogram result as GeoDataFrame.

Attributes:

is_morphed property 

is_morphed: bool

Whether any morphing has been performed.

latest property 

latest: Cartogram

The most recent result.

original property 

original: Cartogram

The original (unmorphed) state.

results property 

results: list[Cartogram]

All results (copy of list).

__getitem__ 

__getitem__(idx: int) -> Cartogram

Get result by index (0 = original).

__iter__ 

__iter__() -> Iterator[Cartogram]

Iterate over all results.

__len__ 

__len__() -> int

Number of results (including original).

__repr__ 

__repr__() -> str

Concise string representation.

morph 

morph(
    options: MorphOptions | None = None, **overrides
) -> Cartogram

Morph geometries (initial or refinement).

Parameters:

  • options (MorphOptions, default: None ) –

    Complete options replacement. If None, uses previous options.

  • **overrides –

    Individual option overrides applied to previous options. Example: mean_tol=0.01, dt=0.3

Returns:

  • Cartogram –

    The morphing result (also appended to workflow).

Examples:

>>> workflow.morph()  # Use default/previous options
>>> workflow.morph(options=MorphOptions.preset_fast())
>>> workflow.morph(mean_tol=0.01, n_iter=200)

morph_multiresolution 

morph_multiresolution(
    min_resolution: int = 128,
    levels: int = 3,
    margin: float = 0.5,
    square: bool = True,
    options: MorphOptions
    | list[MorphOptions]
    | None = None,
) -> Cartogram

Multi-resolution morphing with progressive refinement.

Each level is stored as a separate Cartogram in the workflow.

Parameters:

  • min_resolution (int, default: 128 ) –

    Resolution of the coarsest (first) grid level. Each subsequent level doubles this, up to min_resolution * 2^(levels-1).

  • levels (int, default: 3 ) –

    Number of resolution levels.

  • margin (float, default: 0.5 ) –

    Margin around data bounds for grid creation.

  • square (bool, default: True ) –

    Whether to create square grids.

  • options (MorphOptions, list[MorphOptions], or None, default: None ) –

    Options for each level. When a single MorphOptions is provided (or None), the same options are used at every level. When a list is provided, each entry maps directly to a level.

Returns:

  • Cartogram –

    Final level result (also accessible via self.latest).

Examples:

>>> workflow.morph_multiresolution(min_resolution=128, levels=3)
>>> for cartogram in workflow:
...     print(cartogram.status, cartogram.get_errors().mean_error_pct)

pop 

pop(n: int = 1) -> list[Cartogram]

Remove and return the last n results.

Cannot remove the original (index 0).

Parameters:

  • n (int, default: 1 ) –

    Number of results to remove.

Returns:

  • list[Cartogram] –

    The removed cartograms.

Raises:

  • ValueError –

    If attempting to remove the original state.

reset 

reset() -> None

Remove all morph results, keeping only original.

to_geodataframe 

to_geodataframe(
    run_id: int | None = None,
    iteration: int | None = None,
    include_errors: bool = True,
    include_density: bool = True,
) -> Any

Export a cartogram result as GeoDataFrame.

Parameters:

  • run_id (int, default: None ) –

    Which result to export (default: latest).

  • iteration (int, default: None ) –

    Which iteration snapshot (default: latest in result).

  • include_errors (bool, default: True ) –

    Add '_morph_error_pct' column.

  • include_density (bool, default: True ) –

    Add '_morph_density' column.

Returns:

  • GeoDataFrame –

    Copy of original with morphed geometry and optional metrics.