carto_flow.flow_cartogram.comparison

Comparison utilities for cartogram results.

Utilities for comparing original and morphed geometries.

Classes:

• ComparisonResult –

  Dataclass containing comparison metrics.

Functions:

• compare_results –

  Compare two morphing results statistically.

• compute_displacement_vectors –

  Compute centroid displacement vectors.

Examples:

>>> from carto_flow.flow_cartogram import morph_gdf
>>> from carto_flow.flow_cartogram.comparison import compare_results
>>>
>>> # Compare original to morphed
>>> result = morph_gdf(gdf, 'population')
>>> comparison = compare_results(gdf, result)
>>> print(f"Mean displacement: {comparison.mean_displacement:.2f}")

ComparisonResult dataclass

ComparisonResult(
    centroid_shifts: ndarray,
    mean_displacement: float,
    max_displacement: float,
    area_changes: ndarray,
    mean_area_change: float,
)

Result of comparing original geometries to morphed geometries.

Attributes:

• centroid_shifts (ndarray) –

  Array of (dx, dy) shifts for each geometry's centroid. Positive dx means the centroid moved right (east). Positive dy means the centroid moved up (north).

• mean_displacement (float) –

  Mean displacement distance across all geometries.

• max_displacement (float) –

  Maximum displacement distance.

• area_changes (ndarray) –

  Relative area change for each geometry (morphed_area / original_area). Values > 1 indicate the geometry grew; values < 1 indicate shrinkage.

• mean_area_change (float) –

  Mean relative area change across all geometries.

Examples:

>>> comparison = compare_results(gdf, result)
>>> print(f"Mean displacement: {comparison.mean_displacement:.2f}")
>>> df = comparison.to_dataframe()
>>> df.sort_values('displacement', ascending=False).head(10)

Methods:

• to_dataframe –

  Convert per-geometry metrics to a DataFrame.

to_dataframe

to_dataframe() -> pd.DataFrame

Convert per-geometry metrics to a DataFrame.

Returns:

• DataFrame –

  DataFrame with columns: - dx: X-component of centroid shift - dy: Y-component of centroid shift - displacement: Euclidean distance moved - area_change: Relative area change (morphed/original)

Examples:

>>> df = comparison.to_dataframe()
>>> # Find geometries that moved the most
>>> df.nlargest(5, 'displacement')
>>> # Find geometries that grew the most
>>> df.nlargest(5, 'area_change')

Join with original GeoDataFrame to see which regions changed:

>>> comparison = compare_results(gdf, result)
>>> df = comparison.to_dataframe()
>>> # Join metrics with original data (same row order)
>>> gdf_with_metrics = gdf.join(df)
>>> # Now filter/sort by any column
>>> gdf_with_metrics.nlargest(5, 'displacement')[['name', 'population', 'displacement']]

compare_results

compare_results(
    original: Any, morphed: Cartogram
) -> ComparisonResult

Compare original geometries to a morphing result.

Parameters:

• original (GeoDataFrame or Cartogram) –

  Original geometries (GeoDataFrame) or a Cartogram to compare against

• morphed (Cartogram) –

  Cartogram result containing transformed geometries

Returns:

• ComparisonResult –

  Statistical comparison of the two geometry sets

Examples:

Compare original GeoDataFrame to morphed result:

>>> result = morph_gdf(gdf, 'population')
>>> comparison = compare_results(gdf, result)
>>> print(f"Mean displacement: {comparison.mean_displacement:.2f}")

Compare two different morphing results:

>>> result1 = morph_gdf(gdf, 'population', options=MorphOptions.preset_fast())
>>> result2 = morph_gdf(gdf, 'population', options=MorphOptions.preset_high_quality())
>>> comparison = compare_results(result1, result2)

compute_centroid_shifts

compute_centroid_shifts(
    geom1: Any, geom2: Any
) -> np.ndarray

Compute centroid shifts between two geometry collections.

Parameters:

• geom1 (GeoDataFrame or geometry array) –

  First set of geometries

• geom2 (GeoDataFrame or geometry array) –

  Second set of geometries

Returns:

• ndarray –

  Array of shape (n_geometries, 2) containing (dx, dy) shifts

compute_displacement_vectors

compute_displacement_vectors(
    original: Any, morphed: Cartogram
) -> np.ndarray

Compute displacement vectors between original and morphed centroids.

Parameters:

• original (GeoDataFrame) –

  Original GeoDataFrame before morphing

• morphed (Cartogram) –

  Cartogram result containing transformed geometries

Returns:

• ndarray –

  Array of shape (n_geometries, 2) containing (dx, dy) displacement vectors

Examples:

>>> vectors = compute_displacement_vectors(gdf, result)
>>> for i, (dx, dy) in enumerate(vectors):
...     print(f"Geometry {i}: moved ({dx:.2f}, {dy:.2f})")