Skip to content

carto_flow.flow_cartogram.metrics

Quality metrics and validation for cartogram results.

Validation utilities to assess cartogram quality and detect issues.

Classes:

Functions:

Examples:

>>> from carto_flow.flow_cartogram import morph_gdf, MorphOptions
>>> from carto_flow.flow_cartogram.metrics import validate_result
>>>
>>> result = morph_gdf(gdf, 'population', options=MorphOptions.preset_fast())
>>> report = validate_result(result)
>>> print(f"Valid: {report.is_valid}, Mean error: {report.mean_error:.1%}")

QualityReport dataclass 

QualityReport(
    is_valid: bool,
    has_self_intersections: bool,
    topology_preserved: bool,
    invalid_geometry_indices: list[int] = list(),
    mean_error: float = 0.0,
    max_error: float = 0.0,
    warnings: list[str] = list(),
)

Quality assessment report for cartogram results.

Attributes:

  • is_valid (bool) –

    True if all geometries are valid (no self-intersections)

  • has_self_intersections (bool) –

    True if any geometry has self-intersections

  • topology_preserved (bool) –

    True if no geometries became invalid during morphing

  • invalid_geometry_indices (list[int]) –

    Indices of geometries that are invalid

  • mean_error (float) –

    Mean area error across all geometries (from result)

  • max_error (float) –

    Maximum area error (from result)

  • warnings (list[str]) –

    List of warning messages about potential issues

check_topology 

check_topology(geometries: Any) -> tuple[bool, list[int]]

Check for self-intersections and invalid geometries.

Parameters:

  • geometries (GeoDataFrame or array - like) –

    Geometries to check

Returns:

  • tuple[bool, list[int]] –

    (all_valid, invalid_indices) where: - all_valid: True if all geometries are valid - invalid_indices: List of indices with invalid geometries

Examples:

>>> is_valid, invalid = check_topology(result.get_geometry())
>>> if not is_valid:
...     print(f"Found {len(invalid)} invalid geometries")

validate_result 

validate_result(result: Cartogram) -> QualityReport

Comprehensive validation of morphing result.

Checks topology (self-intersections) and reports area errors from the result. Area errors are computed during morphing and accessed via result.get_errors() which returns a MorphErrors object with mean_error_pct and max_error_pct attributes.

Parameters:

  • result (Cartogram) –

    Cartogram result to validate

Returns:

Examples:

>>> report = validate_result(result)
>>> if not report.is_valid:
...     print(f"Invalid geometries: {report.invalid_geometry_indices}")
>>> print(f"Mean error: {report.mean_error:.1%}")
>>> print(f"Max error: {report.max_error:.1%}")