carto_flow.flow_cartogram.serialization¶

Serialization utilities for cartogram results.

Export, save, and load utilities for Cartogram and CartogramWorkflow.

Functions:

save_cartogram –

Save a Cartogram to JSON format.
load_cartogram –

Load a Cartogram from JSON format.
save_workflow –

Serialize CartogramWorkflow state to file.
load_workflow –

Load CartogramWorkflow state from file.
export_history –

Export convergence history to CSV or JSON.

Examples:

>>> from carto_flow.flow_cartogram import morph_gdf, MorphOptions
>>> from carto_flow.flow_cartogram.serialization import save_cartogram
>>>
>>> cartogram = morph_gdf(gdf, 'population', options=MorphOptions.preset_fast())
>>> save_cartogram(cartogram, 'cartogram.json')
>>> cartogram.save('cartogram.gpkg')  # Or use the Cartogram.save() method

export_history ¶

export_history(
    history: Union[History, ConvergenceHistory],
    path: str | Path,
    output_format: str = "csv",
) -> None

Export convergence history to CSV or JSON format.

Parameters:

history (History or ConvergenceHistory) –

History object containing iteration snapshots, OR ConvergenceHistory with scalar error metrics for all iterations.
path (str or Path) –

Output file path
output_format (str, default: 'csv' ) –

Output format: 'csv' or 'json'

Examples:

>>> export_history(cartogram.convergence, 'convergence.csv')
>>> export_history(cartogram.snapshots, 'convergence.json', output_format='json')

load_cartogram ¶

load_cartogram(path: str | Path) -> Cartogram

Load a Cartogram from JSON format.

Restores a Cartogram saved by save_cartogram() / Cartogram.save(), including morphed geometries, source GeoDataFrame, error metrics, and convergence history.

Parameters:

path (str or Path) –

Path to saved JSON file

Returns:

Cartogram –

Fully restored Cartogram with one snapshot (the final result). Supports to_geodataframe() and plot() immediately after loading.

Raises:

ValueError –

If the file was saved without geometries (old metadata-only format).

load_workflow ¶

load_workflow(path: str | Path) -> CartogramWorkflow

Load CartogramWorkflow state from a pickle file.

Parameters:

path (str or Path) –

Path to saved state file

Returns:

CartogramWorkflow –

Restored CartogramWorkflow instance with full state

Examples:

>>> workflow = load_workflow('checkpoint.pkl')
>>> workflow.morph()  # Continue refinement

save_cartogram ¶

save_cartogram(
    cartogram: Cartogram, path: str | Path
) -> None

Save a Cartogram to JSON format.

Saves geometries, source data, error metrics, and convergence history so the Cartogram can be fully restored with load_cartogram() / Cartogram.load().

Parameters:

cartogram (Cartogram) –

Cartogram instance to save
path (str or Path) –

Output file path (typically .json extension)

Examples:

>>> save_cartogram(cartogram, 'result.json')
>>> loaded = load_cartogram('result.json')

save_workflow ¶

save_workflow(
    workflow: CartogramWorkflow, path: str | Path
) -> None

Serialize CartogramWorkflow state to a pickle file.

Saves the complete state including original data, all results, and options for later resumption.

Parameters:

workflow (CartogramWorkflow) –

CartogramWorkflow instance to save
path (str or Path) –

Output file path (typically .pkl extension)

Examples:

>>> workflow = CartogramWorkflow(gdf, 'population')
>>> workflow.morph()
>>> save_workflow(workflow, 'checkpoint.pkl')