DGGS Statistics

Statistics module for vgrid.

This module provides functions to calculate and display statistics for various discrete global grid systems (DGGS), including cell counts, areas, and edge lengths.

a5_segments_cli()

Command-line interface for A5 segments analysis.

Source code in vgrid/stats/a5_segments.py

def a5_segments_cli():
    """Command-line interface for A5 segments analysis."""
    parser = argparse.ArgumentParser(
        description="Evaluate A5 cell_area across a52geo segments values"
    )
    parser.add_argument(
        "-a5",
        "--a5_id",
        type=str,
        default=DEFAULT_A5_ID,
        help=f"A5 cell ID (default: {DEFAULT_A5_ID})",
    )
    parser.add_argument(
        "-s",
        "--segments",
        type=int,
        nargs="+",
        default=list(DEFAULT_SEGMENTS),
        help="Segment counts to evaluate (default: 1 10 100 ... 1000000)",
    )
    parser.add_argument(
        "-o",
        "--output",
        type=str,
        default=None,
        help="Output GeoParquet path",
    )
    parser.add_argument(
        "-split",
        "--split_antimeridian",
        action="store_true",
        default=False,
        help="Enable antimeridian splitting",
    )
    add_verbose_argument(parser)
    args = parser.parse_args()
    a5_segments(
        a5_id=args.a5_id,
        segments=args.segments,
        output=args.output,
        split_antimeridian=args.split_antimeridian,
        verbose=args.verbose,
    )

a5inspect(resolution, options={'segments': 100}, split_antimeridian=False, verbose=True)

Generate comprehensive inspection data for A5 DGGS cells at a given resolution.

This function creates a detailed analysis of A5 cells including area variations, compactness measures, and Antimeridian crossing detection.

Parameters:

Name	Type	Description	Default
resolution	int	A5 resolution level (0-29)	required
options		Optional dictionary of options for grid generation	{'segments': 100}
split_antimeridian	bool	When True, apply antimeridian splitting to the resulting polygons. Defaults to False when None or omitted.	False
verbose		Show progress bars. Defaults to True.	True

Returns:

Type

Description

geopandas.GeoDataFrame: DataFrame containing A5 cell inspection data with columns: - a5: A5 cell ID - resolution: Resolution level - geometry: Cell geometry - cell_area: Cell area in square meters - cell_perimeter: Cell perimeter in meters - crossed: Whether cell crosses the Antimeridian - norm_area: Normalized area (cell_area / mean_area) - ipq: Isoperimetric Quotient compactness - zsc: Zonal Standardized Compactness

Source code in vgrid/stats/a5stats.py

def a5inspect(
    resolution: int,
    options={"segments": 100},
    split_antimeridian: bool = False,
    verbose=True,
):
    """
    Generate comprehensive inspection data for A5 DGGS cells at a given resolution.

    This function creates a detailed analysis of A5 cells including area variations,
    compactness measures, and Antimeridian crossing detection.

    Args:
        resolution: A5 resolution level (0-29)
        options: Optional dictionary of options for grid generation
        split_antimeridian: When True, apply antimeridian splitting to the resulting polygons.
            Defaults to False when None or omitted.
        verbose: Show progress bars. Defaults to True.

    Returns:
        geopandas.GeoDataFrame: DataFrame containing A5 cell inspection data with columns:
            - a5: A5 cell ID
            - resolution: Resolution level
            - geometry: Cell geometry
            - cell_area: Cell area in square meters
            - cell_perimeter: Cell perimeter in meters
            - crossed: Whether cell crosses the Antimeridian
            - norm_area: Normalized area (cell_area / mean_area)
            - ipq: Isoperimetric Quotient compactness
            - zsc: Zonal Standardized Compactness
    """
    a5_gdf = a5grid(
        resolution,
        output_format="gpd",
        options=options,
        split_antimeridian=split_antimeridian,
        verbose=verbose,
    )
    a5_gdf["crossed"] = a5_gdf["geometry"].apply(check_crossing_geom)
    a5_gdf = a5_gdf[~a5_gdf["crossed"]]  # remove cells that cross the Antimeridian

    # mean_area = a5_gdf["cell_area"].mean()
    mean_area = AUTHALIC_AREA / get_num_cells(resolution)

    # Calculate normalized area
    a5_gdf["norm_area"] = a5_gdf["cell_area"] / mean_area
    # Calculate IPQ compactness using the standard formula: CI = 4πA/P²
    a5_gdf["ipq"] = 4 * np.pi * a5_gdf["cell_area"] / (a5_gdf["cell_perimeter"] ** 2)
    # Calculate zonal standardized compactness
    a5_gdf["zsc"] = (
        np.sqrt(
            4 * np.pi * a5_gdf["cell_area"]
            - np.power(a5_gdf["cell_area"], 2) / np.power(6378137, 2)
        )
        / a5_gdf["cell_perimeter"]
    )

    # Compute convex hull using Lambert Azimuthal Equal Area projection
    convex_hull = a5_gdf["geometry"].apply(convexhull_from_lambert)
    # Calculate convex hull area using Lambert projection
    convex_hull_area = convex_hull.apply(
        lambda g: get_area_perimeter_from_lambert(g)[0] if g is not None else np.nan
    )
    # Calculate cell area using Lambert projection for consistent cvh calculation
    a5_gdf_lambert = get_cells_area(a5_gdf.copy(), "LAEA")
    # Compute CVH safely; set to NaN where convex hull area is non-positive or invalid
    a5_gdf["cvh"] = np.where(
        (convex_hull_area > 0) & np.isfinite(convex_hull_area),
        a5_gdf_lambert["area"] / convex_hull_area,
        np.nan,
    )
    # Replace any accidental inf values with NaN
    a5_gdf["cvh"] = a5_gdf["cvh"].replace([np.inf, -np.inf], np.nan)
    return a5_gdf

a5inspect_cli()

Command-line interface for A5 cell inspection.

CLI options

-r, --resolution: A5 resolution level (0-29) -split, --split_antimeridian: Enable antimeridian splitting (default: enabled)

Source code in vgrid/stats/a5stats.py

def a5inspect_cli():
    """
    Command-line interface for A5 cell inspection.

    CLI options:
      -r, --resolution: A5 resolution level (0-29)
      -split, --split_antimeridian: Enable antimeridian splitting (default: enabled)
    """
    parser = argparse.ArgumentParser(add_help=False)
    parser.add_argument("-r", "--resolution", dest="resolution", type=int, default=0)
    parser.add_argument(
        "-split",
        "--split_antimeridian",
        action="store_true",
        default=False,  # default is False to avoid splitting the Antimeridian by default
        help="Enable antimeridian splitting",
    )
    parser.add_argument(
        "-options",
        "--options",
        type=str,
        default=None,
        help="JSON string of options to pass to a52geo. "
        "Example: '{\"segments\": 1000}'",
    )
    add_verbose_argument(parser)
    args = parser.parse_args()
    resolution = args.resolution

    # Parse options JSON if provided
    options = None
    if args.options:
        try:
            options = json.loads(args.options)
        except json.JSONDecodeError as e:
            print(f"Error: Invalid JSON in options: {str(e)}")
            return

    print(
        a5inspect(
            resolution,
            options=options,
            split_antimeridian=args.split_antimeridian,
            verbose=args.verbose,
        )
    )

a5stats_cli()

Command-line interface for generating A5 DGGS statistics.

CLI options

-unit, --unit {m,km}

Source code in vgrid/stats/a5stats.py

def a5stats_cli():
    """
    Command-line interface for generating A5 DGGS statistics.

    CLI options:
      -unit, --unit {m,km}
    """
    parser = argparse.ArgumentParser(add_help=False)
    parser.add_argument(
        "-unit", "--unit", dest="unit", choices=["m", "km"], default="m"
    )
    args = parser.parse_args()
    unit = args.unit
    # Get the DataFrame
    df = a5stats(unit=unit)
    # Display the DataFrame
    print(df)

dggalinspect(dggs_type, resolution, split_antimeridian=False, verbose=True)

Generate detailed inspection data for a DGGAL DGGS type at a given resolution.

Parameters:

Name	Type	Description	Default
dggs_type	str	DGGS type supported by DGGAL	required
resolution	int	Resolution level	required
split_antimeridian	bool	When True, apply antimeridian splitting to the resulting polygons. Defaults to True when None or omitted.	False
verbose		Show progress bars. Defaults to True.	True

Returns:

Type	Description
GeoDataFrame	geopandas.GeoDataFrame with columns: - ZoneID (as provided by DGGAL output; no renaming is performed) - resolution - geometry - cell_area (m^2) - cell_perimeter (m) - crossed (bool) - norm_area (area/mean_area) - ipq (4πA/P²) - zsc (sqrt(4πA - A²/R²)/P), with R=WGS84 a

Source code in vgrid/stats/dggalstats.py

def dggalinspect(
    dggs_type: str, resolution: int, split_antimeridian: bool = False, verbose=True
) -> gpd.GeoDataFrame:
    """
    Generate detailed inspection data for a DGGAL DGGS type at a given resolution.

    Args:
        dggs_type: DGGS type supported by DGGAL
        resolution: Resolution level
        split_antimeridian: When True, apply antimeridian splitting to the resulting polygons.
            Defaults to True when None or omitted.
        verbose: Show progress bars. Defaults to True.

    Returns:
        geopandas.GeoDataFrame with columns:
          - ZoneID (as provided by DGGAL output; no renaming is performed)
          - resolution
          - geometry
          - cell_area (m^2)
          - cell_perimeter (m)
          - crossed (bool)
          - norm_area (area/mean_area)
          - ipq (4πA/P²)
          - zsc (sqrt(4πA - A²/R²)/P), with R=WGS84 a
    """
    dggal_gdf = dggalgen(
        dggs_type,
        resolution,
        output_format="gpd",
        split_antimeridian=split_antimeridian,
        verbose=verbose,
    )

    # Determine whether current CRS is geographic; compute metrics accordingly
    if dggal_gdf.crs.is_geographic:
        def _geod_area_perimeter(g):
            cell_area_perimeter = geod.geometry_area_perimeter(g)
            return pd.Series(
                {
                    "cell_area": abs(cell_area_perimeter[0]),
                    "cell_perimeter": abs(cell_area_perimeter[1]),
                }
            )

        metrics = dggal_gdf.geometry.apply(_geod_area_perimeter)
        dggal_gdf["cell_area"] = metrics["cell_area"]
        dggal_gdf["cell_perimeter"] = metrics["cell_perimeter"]
        dggal_gdf["crossed"] = dggal_gdf.geometry.apply(check_crossing_geom)
    else:
        dggal_gdf["cell_area"] = dggal_gdf.geometry.area
        dggal_gdf["cell_perimeter"] = dggal_gdf.geometry.length
        dggal_gdf["crossed"] = False

    dggal_gdf = dggal_gdf[
        ~dggal_gdf["crossed"]
    ]  # remove cells that cross the Antimeridian
    # mean_area = dggal_gdf["cell_area"].mean()
    num_cells, _, _, _ = dggal_metrics(dggs_type, resolution)
    mean_area = AUTHALIC_AREA / num_cells

    dggal_gdf["norm_area"] = (
        dggal_gdf["cell_area"] / mean_area if mean_area and mean_area != 0 else np.nan
    )
    # Robust formulas avoiding division by zero
    dggal_gdf["ipq"] = (
        4 * np.pi * dggal_gdf["cell_area"] / (dggal_gdf["cell_perimeter"] ** 2)
    )

    dggal_gdf["zsc"] = (
        np.sqrt(
            4 * np.pi * dggal_gdf["cell_area"]
            - np.power(dggal_gdf["cell_area"], 2) / np.power(6378137, 2)
        )
        / dggal_gdf["cell_perimeter"]
    )

    # Compute convex hull using Lambert Azimuthal Equal Area projection
    convex_hull = dggal_gdf["geometry"].apply(convexhull_from_lambert)
    # Calculate convex hull area using Lambert projection
    convex_hull_area = convex_hull.apply(
        lambda g: get_area_perimeter_from_lambert(g)[0] if g is not None else np.nan
    )
    # Calculate cell area using Lambert projection for consistent cvh calculation
    dggal_gdf_lambert = get_cells_area(dggal_gdf.copy(), "LAEA")
    # Compute CVH safely; set to NaN where convex hull area is non-positive or invalid
    dggal_gdf["cvh"] = np.where(
        (convex_hull_area > 0) & np.isfinite(convex_hull_area),
        dggal_gdf_lambert["area"] / convex_hull_area,
        np.nan,
    )
    # Replace any accidental inf values with NaN
    dggal_gdf["cvh"] = dggal_gdf["cvh"].replace([np.inf, -np.inf], np.nan)
    return dggal_gdf

dggalinspect_cli()

Command-line interface for DGGAL cell inspection.

CLI options

-t, --dggs_type -r, --resolution -split, --split_antimeridian: Enable antimeridian splitting (default: enabled)

Source code in vgrid/stats/dggalstats.py

def dggalinspect_cli():
    """
    Command-line interface for DGGAL cell inspection.

    CLI options:
      -t, --dggs_type
      -r, --resolution
      -split, --split_antimeridian: Enable antimeridian splitting (default: enabled)
    """
    parser = argparse.ArgumentParser(add_help=False)
    parser.add_argument(
        "-t", "--dggs_type", dest="dggs_type", choices=DGGAL_TYPES.keys(), required=True
    )
    parser.add_argument("-r", "--resolution", dest="resolution", type=int, default=0)
    parser.add_argument(
        "-split",
        "--split_antimeridian",
        action="store_true",
        default=False,  # default is False to avoid splitting the Antimeridian by default
        help="Enable antimeridian splitting",
    )
    add_verbose_argument(parser)
    args = parser.parse_args()
    dggs_type = args.dggs_type
    resolution = args.resolution
    print(
        dggalinspect(
            dggs_type,
            resolution,
            split_antimeridian=args.split_antimeridian,
            verbose=args.verbose,
        )
    )

dggalstats_cli()

Command-line interface for generating DGGAL DGGS statistics.

CLI options

-dggs, --dggs_type {gnosis, isea3h, isea9r, ivea3h, ivea9r, rtea3h, rtea9r, rhealpix} -unit, --unit {m,km} --minres, --maxres

Source code in vgrid/stats/dggalstats.py

def dggalstats_cli():
    """
    Command-line interface for generating DGGAL DGGS statistics.

    CLI options:
      -dggs, --dggs_type {gnosis, isea3h, isea9r, ivea3h, ivea9r, rtea3h, rtea9r, rhealpix}
      -unit, --unit {m,km}
      --minres, --maxres
    """
    parser = argparse.ArgumentParser(add_help=False)
    parser.add_argument(
        "-dggs", "--dggs_type", dest="dggs_type", choices=DGGAL_TYPES.keys()
    )
    parser.add_argument(
        "-unit", "--unit", dest="unit", choices=["m", "km"], default="m"
    )
    args = parser.parse_args()

    dggs_type = args.dggs_type
    unit = args.unit

    result = dggalstats(dggs_type, unit)
    if result is not None:
        print(result)

dggridinspect(dggrid_instance, dggs_type, resolution, split_antimeridian=False, aggregate=False, options={'densification': 30}, verbose=True)

Generate detailed inspection data for a DGGRID DGGS type at a given resolution.

Parameters:

Name	Type	Description	Default
dggrid_instance		DGGRID instance for grid operations	required
dggs_type	str	DGGS type supported by DGGRID (see dggs_types)	required
resolution	int	Resolution level	required
split_antimeridian	bool	When True, apply antimeridian fixing to the resulting polygons.	False
aggregate	bool	When True, aggregate the resulting polygons. Defaults to False to avoid aggregation by default.	False
options	dict	Options to pass to grid_cell_polygons_for_extent. For example: {"densification": 2} to add densification points. Defaults to None.	{'densification': 30}
verbose		Show progress bars. Defaults to True.	True

Source code in vgrid/stats/dggridstats.py

def dggridinspect(
    dggrid_instance,
    dggs_type: str,
    resolution: int,
    split_antimeridian: bool = False,
    aggregate: bool = False,
    options={"densification": 30},
    verbose=True,
) -> gpd.GeoDataFrame:
    """
    Generate detailed inspection data for a DGGRID DGGS type at a given resolution.

    Args:
        dggrid_instance: DGGRID instance for grid operations
        dggs_type: DGGS type supported by DGGRID (see dggs_types)
        resolution: Resolution level
        split_antimeridian: When True, apply antimeridian fixing to the resulting polygons.
        Defaults to False to avoid splitting the Antimeridian by default.
        aggregate: When True, aggregate the resulting polygons. Defaults to False to avoid aggregation by default.
        options (dict, optional): Options to pass to grid_cell_polygons_for_extent.
            For example: {"densification": 2} to add densification points.
            Defaults to None.
        verbose: Show progress bars. Defaults to True.
    Returns:
        geopandas.GeoDataFrame: DataFrame containing inspection data with columns:
          - name (cell identifier from DGGRID)
          - resolution
          - geometry
          - cell_area (m^2)
          - cell_perimeter (m)
          - crossed (bool)
          - norm_area (area/mean_area)
          - ipq (4πA/P²)
          - zsc (sqrt(4πA - A²/R²)/P), with R=WGS84 a
    """

    # Generate grid using dggridgen
    dggrid_gdf = dggridgen(
        dggrid_instance,
        dggs_type,
        resolution,
        output_format="gpd",
        split_antimeridian=split_antimeridian,
        aggregate=aggregate,
        options=options,
        verbose=verbose,
    )

    # Remove cells with null or invalid geometry
    dggrid_gdf = dggrid_gdf.dropna(subset=["geometry"])
    dggrid_gdf = dggrid_gdf[dggrid_gdf.geometry.is_valid]

    # Add dggs_type column
    dggrid_gdf["dggs_type"] = f"dggrid_{dggs_type.lower()}"

    # Rename global_id to cell_id
    if "global_id" in dggrid_gdf.columns:
        dggrid_gdf = dggrid_gdf.rename(columns={"global_id": "cell_id"})

    # Determine whether current CRS is geographic; compute metrics accordingly
    if dggrid_gdf.crs.is_geographic:
        def _geod_area_perimeter(g):
            cell_area_perimeter = geod.geometry_area_perimeter(g)
            return pd.Series(
                {
                    "cell_area": abs(cell_area_perimeter[0]),
                    "cell_perimeter": abs(cell_area_perimeter[1]),
                }
            )

        metrics = dggrid_gdf.geometry.apply(_geod_area_perimeter)
        dggrid_gdf["cell_area"] = metrics["cell_area"]
        dggrid_gdf["cell_perimeter"] = metrics["cell_perimeter"]
        dggrid_gdf["crossed"] = dggrid_gdf.geometry.apply(check_crossing_geom)
    else:
        dggrid_gdf["cell_area"] = dggrid_gdf.geometry.area
        dggrid_gdf["cell_perimeter"] = dggrid_gdf.geometry.length
        dggrid_gdf["crossed"] = False

    # Add resolution column
    dggrid_gdf["resolution"] = resolution

    dggrid_gdf = dggrid_gdf[
        ~dggrid_gdf["crossed"]
    ]  # remove cells that cross the Antimeridian
    # Calculate normalized area
    # mean_area = dggrid_gdf["cell_area"].mean()
    num_cells, _, _, _ = dggrid_metrics(dggrid_instance, dggs_type, resolution)
    mean_area = AUTHALIC_AREA / num_cells
    dggrid_gdf["norm_area"] = (
        dggrid_gdf["cell_area"] / mean_area if mean_area and mean_area != 0 else np.nan
    )

    # Calculate compactness metrics (robust formulas avoiding division by zero)
    dggrid_gdf["ipq"] = (
        4 * np.pi * dggrid_gdf["cell_area"] / (dggrid_gdf["cell_perimeter"] ** 2)
    )
    dggrid_gdf["zsc"] = (
        np.sqrt(
            4 * np.pi * dggrid_gdf["cell_area"]
            - np.power(dggrid_gdf["cell_area"], 2) / np.power(6378137, 2)
        )
        / dggrid_gdf["cell_perimeter"]
    )

    # Compute convex hull using Lambert Azimuthal Equal Area projection
    convex_hull = dggrid_gdf["geometry"].apply(convexhull_from_lambert)
    # Calculate convex hull area using Lambert projection
    convex_hull_area = convex_hull.apply(
        lambda g: get_area_perimeter_from_lambert(g)[0] if g is not None else np.nan
    )
    # Calculate cell area using Lambert projection for consistent cvh calculation
    dggrid_gdf_lambert = get_cells_area(dggrid_gdf.copy(), "LAEA")
    # Compute CVH safely; set to NaN where convex hull area is non-positive or invalid
    dggrid_gdf["cvh"] = np.where(
        (convex_hull_area > 0) & np.isfinite(convex_hull_area),
        dggrid_gdf_lambert["area"] / convex_hull_area,
        np.nan,
    )
    # Replace any accidental inf values with NaN
    dggrid_gdf["cvh"] = dggrid_gdf["cvh"].replace([np.inf, -np.inf], np.nan)

    return dggrid_gdf

dggridinspect_cli()

Command-line interface for DGGRID cell inspection.

CLI options

-dggs, --dggs_type: DGGS type from dggs_types -r, --resolution: Resolution level --no-split_antimeridian: Disable antimeridian fixing (default: enabled) --no-aggregate: Disable aggregation (default: enabled)

Source code in vgrid/stats/dggridstats.py

def dggridinspect_cli():
    """
    Command-line interface for DGGRID cell inspection.

    CLI options:
      -dggs, --dggs_type: DGGS type from dggs_types
      -r, --resolution: Resolution level
      --no-split_antimeridian: Disable antimeridian fixing (default: enabled)
      --no-aggregate: Disable aggregation (default: enabled)
    """
    parser = argparse.ArgumentParser()
    parser.add_argument(
        "-dggs", "--dggs_type", dest="dggs_type", choices=dggs_types, required=True
    )
    parser.add_argument("-r", "--resolution", dest="resolution", type=int, default=0)
    parser.add_argument(
        "-split",
        "--split_antimeridian",
        action="store_true",
        default=False,  # default is False to avoid splitting the Antimeridian by default
        help="Enable antimeridian fixing",
    )
    parser.add_argument(
        "-aggregate",
        "--aggregate",
        action="store_true",
        default=False,  # default is False to avoid aggregation by default
        help="Enable aggregation",
    )
    parser.add_argument(
        "-options",
        "--options",
        type=str,
        default=None,
        help="JSON string of options to pass to grid_cell_polygons_for_extent. "
        "Example: '{\"densification\": 2}'",
    )
    add_verbose_argument(parser)
    args = parser.parse_args()
    dggrid_instance = create_dggrid_instance()
    dggs_type = args.dggs_type
    resolution = args.resolution

    # Parse options JSON if provided
    options = None
    if args.options:
        try:
            options = json.loads(args.options)
        except json.JSONDecodeError as e:
            print(f"Error: Invalid JSON in options: {str(e)}")
            return

    print(
        dggridinspect(
            dggrid_instance,
            dggs_type,
            resolution,
            split_antimeridian=args.split_antimeridian,
            aggregate=args.aggregate,
            options=options,
            verbose=args.verbose,
        )
    )

dggridstats_cli()

Command-line interface for generating DGGAL DGGS statistics.

CLI options

-dggs, --dggs_type {gnosis, isea3h, isea9r, ivea3h, ivea9r, rtea3h, rtea9r, rhealpix} -unit, --unit {m,km} --minres, --maxres

Source code in vgrid/stats/dggridstats.py

def dggridstats_cli():
    """
    Command-line interface for generating DGGAL DGGS statistics.

    CLI options:
      -dggs, --dggs_type {gnosis, isea3h, isea9r, ivea3h, ivea9r, rtea3h, rtea9r, rhealpix}
      -unit, --unit {m,km}
      --minres, --maxres
    """
    parser = argparse.ArgumentParser(add_help=False)
    parser.add_argument(
        "-dggs", "--dggs_type", dest="dggs_type", choices=DGGRID_TYPES.keys()
    )
    parser.add_argument(
        "-unit", "--unit", dest="unit", choices=["m", "km"], default="m"
    )
    args = parser.parse_args()

    dggs_type = args.dggs_type
    unit = args.unit

    dggrid_instance = create_dggrid_instance()
    result = dggridstats(dggrid_instance, dggs_type, unit)
    if result is not None:
        print(result)

digipininspect(resolution, verbose=True)

Generate comprehensive inspection data for DIGIPIN DGGS cells at a given resolution.

This function creates a detailed analysis of DIGIPIN cells including area variations, compactness measures, and Antimeridian crossing detection.

Parameters:

Name	Type	Description	Default
resolution		DIGIPIN resolution level (1-10)	required
verbose		Show progress bars. Defaults to True.	True

Source code in vgrid/stats/digipinstats.py

def digipininspect(resolution, verbose=True):
    """
    Generate comprehensive inspection data for DIGIPIN DGGS cells at a given resolution.

    This function creates a detailed analysis of DIGIPIN cells including area variations,
    compactness measures, and Antimeridian crossing detection.

    Args:
        resolution: DIGIPIN resolution level (1-10)

        verbose: Show progress bars. Defaults to True.
    Returns:
        geopandas.GeoDataFrame: DataFrame containing DIGIPIN cell inspection data with columns:
            - digipin: DIGIPIN cell ID
            - resolution: Resolution level
            - geometry: Cell geometry
            - cell_area: Cell area in square meters
            - cell_perimeter: Cell perimeter in meters
            - crossed: Whether cell crosses the Antimeridian
            - norm_area: Normalized area (cell_area / mean_area)
            - ipq: Isoperimetric Quotient compactness
            - zsc: Zonal Standardized Compactness
            - cvh: Convex Hull compactness
    """
    resolution = validate_digipin_resolution(resolution)
    digipin_gdf = digipingrid(resolution, output_format="gpd", verbose=verbose)
    digipin_gdf["crossed"] = digipin_gdf["geometry"].apply(check_crossing_geom)
    # mean_area = digipin_gdf["cell_area"].mean()
    num_cells = 16**resolution
    mean_area = DIGIPIN_AREA / num_cells
    # Calculate normalized area
    digipin_gdf["norm_area"] = digipin_gdf["cell_area"] / mean_area
    # Calculate IPQ compactness using the standard formula: CI = 4πA/P²
    digipin_gdf["ipq"] = (
        4 * np.pi * digipin_gdf["cell_area"] / (digipin_gdf["cell_perimeter"] ** 2)
    )
    # Calculate zonal standardized compactness
    digipin_gdf["zsc"] = (
        np.sqrt(
            4 * np.pi * digipin_gdf["cell_area"]
            - np.power(digipin_gdf["cell_area"], 2) / np.power(6378137, 2)
        )
        / digipin_gdf["cell_perimeter"]
    )

    # Compute convex hull using Lambert Azimuthal Equal Area projection
    convex_hull = digipin_gdf["geometry"].apply(convexhull_from_lambert)
    # Calculate convex hull area using Lambert projection
    convex_hull_area = convex_hull.apply(
        lambda g: get_area_perimeter_from_lambert(g)[0] if g is not None else np.nan
    )
    # Calculate cell area using Lambert projection for consistent cvh calculation
    digipin_gdf_lambert = get_cells_area(digipin_gdf.copy(), "LAEA")
    # Compute CVH safely; set to NaN where convex hull area is non-positive or invalid
    digipin_gdf["cvh"] = np.where(
        (convex_hull_area > 0) & np.isfinite(convex_hull_area),
        digipin_gdf_lambert["area"] / convex_hull_area,
        np.nan,
    )
    # Replace any accidental inf values with NaN
    digipin_gdf["cvh"] = digipin_gdf["cvh"].replace([np.inf, -np.inf], np.nan)

    return digipin_gdf

digipininspect_cli()

Command-line interface for DIGIPIN cell inspection.

CLI options

-r, --resolution: DIGIPIN resolution level (1-10)

Source code in vgrid/stats/digipinstats.py

def digipininspect_cli():
    """
    Command-line interface for DIGIPIN cell inspection.

    CLI options:
      -r, --resolution: DIGIPIN resolution level (1-10)
    """
    parser = argparse.ArgumentParser(add_help=False)
    parser.add_argument("-r", "--resolution", dest="resolution", type=int, default=1)
    add_verbose_argument(parser)
    args, _ = parser.parse_known_args()  # type: ignore
    resolution = args.resolution
    print(digipininspect(resolution, verbose=args.verbose))

digipinstats_cli()

Command-line interface for generating DIGIPIN DGGS statistics.

CLI options

-unit, --unit {m,km}

Source code in vgrid/stats/digipinstats.py

def digipinstats_cli():
    """
    Command-line interface for generating DIGIPIN DGGS statistics.

    CLI options:
      -unit, --unit {m,km}
    """
    parser = argparse.ArgumentParser(add_help=False)
    parser.add_argument(
        "-unit", "--unit", dest="unit", choices=["m", "km"], default="m"
    )
    args, _ = parser.parse_known_args()  # type: ignore

    unit = args.unit

    # Get the DataFrame
    df = digipinstats(unit=unit)

    # Display the DataFrame
    print(df)

easeinspect(resolution, verbose=True)

Generate comprehensive inspection data for EASE-DGGS cells at a given resolution.

This function creates a detailed analysis of EASE cells including area variations, compactness measures, and Antimeridian crossing detection.

Parameters:

Name	Type	Description	Default
resolution	int	EASE-DGGS resolution level (0-6)	required
verbose		Show progress bars. Defaults to True.	True

Source code in vgrid/stats/easestats.py

def easeinspect(resolution: int, verbose=True):  # length unit is m, area unit is m2
    """
    Generate comprehensive inspection data for EASE-DGGS cells at a given resolution.

    This function creates a detailed analysis of EASE cells including area variations,
    compactness measures, and Antimeridian crossing detection.

    Args:
        resolution: EASE-DGGS resolution level (0-6)

        verbose: Show progress bars. Defaults to True.
    Returns:
        geopandas.GeoDataFrame: DataFrame containing EASE cell inspection data with columns:
            - ease: EASE cell ID
            - resolution: Resolution level
            - geometry: Cell geometry
            - cell_area: Cell area in square meters
            - cell_perimeter: Cell perimeter in meters
            - crossed: Whether cell crosses the dateline
            - norm_area: Normalized area (cell_area / mean_area)
            - ipq: Isoperimetric Quotient compactness
            - zsc: Zonal Standardized Compactness
    """
    ease_gdf = easegrid(resolution, output_format="gpd", verbose=verbose)
    ease_gdf["crossed"] = ease_gdf["geometry"].apply(check_crossing_geom)
    # ease_gdf = ease_gdf[~ease_gdf["crossed"]]  # remove cells that cross the Antimeridian

    # mean_area = ease_gdf["cell_area"].mean()
    num_cells = levels_specs[resolution]["n_row"] * levels_specs[resolution]["n_col"]
    mean_area = AUTHALIC_AREA / num_cells
    # Calculate normalized area
    ease_gdf["norm_area"] = ease_gdf["cell_area"] / mean_area
    # Calculate IPQ compactness using the standard formula: CI = 4πA/P²
    ease_gdf["ipq"] = (
        4 * np.pi * ease_gdf["cell_area"] / (ease_gdf["cell_perimeter"] ** 2)
    )
    # Calculate zonal standardized compactness
    ease_gdf["zsc"] = (
        np.sqrt(
            4 * np.pi * ease_gdf["cell_area"]
            - np.power(ease_gdf["cell_area"], 2) / np.power(6378137, 2)
        )
        / ease_gdf["cell_perimeter"]
    )

    # Compute convex hull using Lambert Azimuthal Equal Area projection
    convex_hull = ease_gdf["geometry"].apply(convexhull_from_lambert)
    # Calculate convex hull area using Lambert projection
    convex_hull_area = convex_hull.apply(
        lambda g: get_area_perimeter_from_lambert(g)[0] if g is not None else np.nan
    )
    # Calculate cell area using Lambert projection for consistent cvh calculation
    ease_gdf_lambert = get_cells_area(ease_gdf.copy(), "LAEA")
    # Compute CVH safely; set to NaN where convex hull area is non-positive or invalid
    ease_gdf["cvh"] = np.where(
        (convex_hull_area > 0) & np.isfinite(convex_hull_area),
        ease_gdf_lambert["area"] / convex_hull_area,
        np.nan,
    )
    # Replace any accidental inf values with NaN
    ease_gdf["cvh"] = ease_gdf["cvh"].replace([np.inf, -np.inf], np.nan)
    return ease_gdf

easeinspect_cli()

Command-line interface for EASE cell inspection.

CLI options

-r, --resolution: EASE resolution level (0-6)

Source code in vgrid/stats/easestats.py

def easeinspect_cli():
    """
    Command-line interface for EASE cell inspection.

    CLI options:
      -r, --resolution: EASE resolution level (0-6)
    """
    parser = argparse.ArgumentParser(add_help=False)
    parser.add_argument("-r", "--resolution", dest="resolution", type=int, default=0)
    add_verbose_argument(parser)
    args = parser.parse_args()  # type: ignore
    resolution = args.resolution
    print(easeinspect(resolution, verbose=args.verbose))

easestats_cli()

Command-line interface for generating EASE-DGGS statistics.

CLI options

-unit, --unit {m,km}

Source code in vgrid/stats/easestats.py

def easestats_cli():
    """
    Command-line interface for generating EASE-DGGS statistics.

    CLI options:
      -unit, --unit {m,km}
    """
    parser = argparse.ArgumentParser(add_help=False)
    parser.add_argument(
        "-unit", "--unit", dest="unit", choices=["m", "km"], default="m"
    )

    args = parser.parse_args()  # type: ignore
    unit = args.unit

    # Get the DataFrame
    df = easestats(unit=unit)

    # Display the DataFrame
    print(df)

garsinspect(resolution, verbose=True)

Generate comprehensive inspection data for GARS DGGS cells at a given resolution.

This function creates a detailed analysis of GARS cells including area variations, compactness measures, and Antimeridian crossing detection.

Parameters:

Name	Type	Description	Default
resolution	int	GARS resolution level (0-4)	required
verbose		Show progress bars. Defaults to True.	True

Source code in vgrid/stats/garsstats.py

def garsinspect(resolution: int, verbose=True):  # length unit is km, area unit is km2
    """
    Generate comprehensive inspection data for GARS DGGS cells at a given resolution.

    This function creates a detailed analysis of GARS cells including area variations,
    compactness measures, and Antimeridian crossing detection.

    Args:
        resolution: GARS resolution level (0-4)

        verbose: Show progress bars. Defaults to True.
    Returns:
        geopandas.GeoDataFrame: DataFrame containing GARS cell inspection data with columns:
            - gars: GARS cell ID
            - resolution: Resolution level
            - geometry: Cell geometry
            - cell_area: Cell area in square meters
            - cell_perimeter: Cell perimeter in meters
            - crossed: Whether cell crosses the Antimeridian
            - norm_area: Normalized area (cell_area / mean_area)
            - ipq: Isoperimetric Quotient compactness
            - zsc: Zonal Standardized Compactness
    """
    gars_gdf = garsgrid(resolution, output_format="gpd", verbose=verbose)
    gars_gdf["crossed"] = gars_gdf["geometry"].apply(check_crossing_geom)
    # mean_area = gars_gdf["cell_area"].mean()
    mean_area = AUTHALIC_AREA / gars_num_cells(resolution)
    # Calculate normalized area
    gars_gdf["norm_area"] = gars_gdf["cell_area"] / mean_area
    # Calculate IPQ compactness using the standard formula: CI = 4πA/P²
    gars_gdf["ipq"] = (
        4 * np.pi * gars_gdf["cell_area"] / (gars_gdf["cell_perimeter"] ** 2)
    )
    # Calculate zonal standardized compactness
    gars_gdf["zsc"] = (
        np.sqrt(
            4 * np.pi * gars_gdf["cell_area"]
            - np.power(gars_gdf["cell_area"], 2) / np.power(6378137, 2)
        )
        / gars_gdf["cell_perimeter"]
    )

    # Compute convex hull using Lambert Azimuthal Equal Area projection
    convex_hull = gars_gdf["geometry"].apply(convexhull_from_lambert)
    # Calculate convex hull area using Lambert projection
    convex_hull_area = convex_hull.apply(
        lambda g: get_area_perimeter_from_lambert(g)[0] if g is not None else np.nan
    )
    # Calculate cell area using Lambert projection for consistent cvh calculation
    gars_gdf_lambert = get_cells_area(gars_gdf.copy(), "LAEA")
    # Compute CVH safely; set to NaN where convex hull area is non-positive or invalid
    gars_gdf["cvh"] = np.where(
        (convex_hull_area > 0) & np.isfinite(convex_hull_area),
        gars_gdf_lambert["area"] / convex_hull_area,
        np.nan,
    )
    # Replace any accidental inf values with NaN
    gars_gdf["cvh"] = gars_gdf["cvh"].replace([np.inf, -np.inf], np.nan)

    return gars_gdf

garsinspect_cli()

Command-line interface for GARS cell inspection.

CLI options

-r, --resolution: GARS resolution level (0-4)

Source code in vgrid/stats/garsstats.py

def garsinspect_cli():
    """
    Command-line interface for GARS cell inspection.

    CLI options:
      -r, --resolution: GARS resolution level (0-4)
    """
    parser = argparse.ArgumentParser(add_help=False)
    parser.add_argument("-r", "--resolution", dest="resolution", type=int, default=0)
    add_verbose_argument(parser)
    args = parser.parse_args()  # type: ignore
    resolution = args.resolution
    print(garsinspect(resolution, verbose=args.verbose))

garsstats_cli()

Command-line interface for generating GARS DGGS statistics.

CLI options

-unit, --unit {m,km}

Source code in vgrid/stats/garsstats.py

def garsstats_cli():
    """
    Command-line interface for generating GARS DGGS statistics.

    CLI options:
      -unit, --unit {m,km}
    """
    parser = argparse.ArgumentParser(add_help=False)
    parser.add_argument(
        "-unit", "--unit", dest="unit", choices=["m", "km"], default="m"
    )
    args = parser.parse_args()

    unit = args.unit

    # Get the DataFrame
    df = garsstats(unit=unit)

    # Display the DataFrame
    print(df)

geohashinspect(resolution, verbose=True)

Generate comprehensive inspection data for Geohash DGGS cells at a given resolution.

This function creates a detailed analysis of Geohash cells including area variations, compactness measures, and Antimeridian crossing detection.

Parameters:

Name	Type	Description	Default
resolution	int	Geohash resolution level (0-12)	required
verbose		Show progress bars. Defaults to True.	True

Source code in vgrid/stats/geohashstats.py

def geohashinspect(resolution: int, verbose=True):
    """
    Generate comprehensive inspection data for Geohash DGGS cells at a given resolution.

    This function creates a detailed analysis of Geohash cells including area variations,
    compactness measures, and Antimeridian crossing detection.

    Args:
        resolution: Geohash resolution level (0-12)

        verbose: Show progress bars. Defaults to True.
    Returns:
        geopandas.GeoDataFrame: DataFrame containing Geohash cell inspection data with columns:
            - geohash: Geohash cell ID
            - resolution: Resolution level
            - geometry: Cell geometry
            - cell_area: Cell area in square meters
            - cell_perimeter: Cell perimeter in meters
            - crossed: Whether cell crosses the Antimeridian
            - norm_area: Normalized area (cell_area / mean_area)
            - ipq: Isoperimetric Quotient compactness
            - zsc: Zonal Standardized Compactness
    """
    geohash_gdf = geohashgrid(resolution, output_format="gpd", verbose=verbose)
    geohash_gdf["crossed"] = geohash_gdf["geometry"].apply(check_crossing_geom)
    # mean_area = geohash_gdf["cell_area"].mean()
    num_cells = 32**resolution
    mean_area = AUTHALIC_AREA / num_cells
    # Calculate normalized area
    geohash_gdf["norm_area"] = geohash_gdf["cell_area"] / mean_area
    # Calculate IPQ compactness using the standard formula: CI = 4πA/P²
    geohash_gdf["ipq"] = (
        4 * np.pi * geohash_gdf["cell_area"] / (geohash_gdf["cell_perimeter"] ** 2)
    )
    # Calculate zonal standardized compactness
    geohash_gdf["zsc"] = (
        np.sqrt(
            4 * np.pi * geohash_gdf["cell_area"]
            - np.power(geohash_gdf["cell_area"], 2) / np.power(6378137, 2)
        )
        / geohash_gdf["cell_perimeter"]
    )

    # Compute convex hull using Lambert Azimuthal Equal Area projection
    convex_hull = geohash_gdf["geometry"].apply(convexhull_from_lambert)
    # Calculate convex hull area using Lambert projection
    convex_hull_area = convex_hull.apply(
        lambda g: get_area_perimeter_from_lambert(g)[0] if g is not None else np.nan
    )
    # Calculate cell area using Lambert projection for consistent cvh calculation
    geohash_gdf_lambert = get_cells_area(geohash_gdf.copy(), "LAEA")
    # Compute CVH safely; set to NaN where convex hull area is non-positive or invalid
    geohash_gdf["cvh"] = np.where(
        (convex_hull_area > 0) & np.isfinite(convex_hull_area),
        geohash_gdf_lambert["area"] / convex_hull_area,
        np.nan,
    )
    # Replace any accidental inf values with NaN
    geohash_gdf["cvh"] = geohash_gdf["cvh"].replace([np.inf, -np.inf], np.nan)

    return geohash_gdf

geohashinspect_cli()

Command-line interface for Geohash cell inspection.

CLI options

-r, --resolution: Geohash resolution level (0-12)

Source code in vgrid/stats/geohashstats.py

def geohashinspect_cli():
    """
    Command-line interface for Geohash cell inspection.

    CLI options:
      -r, --resolution: Geohash resolution level (0-12)
    """
    parser = argparse.ArgumentParser(add_help=False)
    parser.add_argument("-r", "--resolution", dest="resolution", type=int, default=0)
    add_verbose_argument(parser)
    args = parser.parse_args()
    resolution = args.resolution
    print(geohashinspect(resolution, verbose=args.verbose))

geohashstats_cli()

Command-line interface for generating Geohash DGGS statistics.

CLI options

-unit, --unit {m,km}

Source code in vgrid/stats/geohashstats.py

def geohashstats_cli():
    """
    Command-line interface for generating Geohash DGGS statistics.

    CLI options:
      -unit, --unit {m,km}
    """
    parser = argparse.ArgumentParser(add_help=False)
    parser.add_argument(
        "-unit", "--unit", dest="unit", choices=["m", "km"], default="m"
    )
    args = parser.parse_args()

    unit = args.unit

    # Get the DataFrame
    df = geohashstats(unit=unit)

    # Display the DataFrame
    print(df)

georefinspect(resolution, verbose=True)

Generate comprehensive inspection data for GEOREF DGGS cells at a given resolution.

This function creates a detailed analysis of GEOREF cells including area variations, compactness measures, and Antimeridian crossing detection.

Parameters:

Name	Type	Description	Default
resolution	int	GEOREF resolution level (0-10)	required
verbose		Show progress bars. Defaults to True.	True

Source code in vgrid/stats/georefstats.py

def georefinspect(resolution: int, verbose=True):
    """
    Generate comprehensive inspection data for GEOREF DGGS cells at a given resolution.

    This function creates a detailed analysis of GEOREF cells including area variations,
    compactness measures, and Antimeridian crossing detection.

    Args:
        resolution: GEOREF resolution level (0-10)

        verbose: Show progress bars. Defaults to True.
    Returns:
        geopandas.GeoDataFrame: DataFrame containing GEOREF cell inspection data with columns:
            - georef: GEOREF cell ID
            - resolution: Resolution level
            - geometry: Cell geometry
            - cell_area: Cell area in square meters
            - cell_perimeter: Cell perimeter in meters
            - crossed: Whether cell crosses the Antimeridian
            - norm_area: Normalized area (cell_area / mean_area)
            - ipq: Isoperimetric Quotient compactness
            - zsc: Zonal Standardized Compactness
    """
    georef_gdf = georefgrid(resolution, output_format="gpd", verbose=verbose)
    georef_gdf["crossed"] = georef_gdf["geometry"].apply(check_crossing_geom)
    # mean_area = georef_gdf["cell_area"].mean()
    grid_size_deg = GEOREF_RESOLUTION_DEGREES.get(resolution)
    num_lon = int(round(360.0 / grid_size_deg))
    num_lat = int(round(180.0 / grid_size_deg))
    num_cells = num_lon * num_lat
    mean_area = AUTHALIC_AREA / num_cells
    # Calculate normalized area
    georef_gdf["norm_area"] = georef_gdf["cell_area"] / mean_area
    # Calculate IPQ compactness using the standard formula: CI = 4πA/P²
    georef_gdf["ipq"] = (
        4 * np.pi * georef_gdf["cell_area"] / (georef_gdf["cell_perimeter"] ** 2)
    )
    # Calculate zonal standardized compactness
    georef_gdf["zsc"] = (
        np.sqrt(
            4 * np.pi * georef_gdf["cell_area"]
            - np.power(georef_gdf["cell_area"], 2) / np.power(6378137, 2)
        )
        / georef_gdf["cell_perimeter"]
    )

    # Compute convex hull using Lambert Azimuthal Equal Area projection
    convex_hull = georef_gdf["geometry"].apply(convexhull_from_lambert)
    # Calculate convex hull area using Lambert projection
    convex_hull_area = convex_hull.apply(
        lambda g: get_area_perimeter_from_lambert(g)[0] if g is not None else np.nan
    )
    # Calculate cell area using Lambert projection for consistent cvh calculation
    georef_gdf_lambert = get_cells_area(georef_gdf.copy(), "LAEA")
    # Compute CVH safely; set to NaN where convex hull area is non-positive or invalid
    georef_gdf["cvh"] = np.where(
        (convex_hull_area > 0) & np.isfinite(convex_hull_area),
        georef_gdf_lambert["area"] / convex_hull_area,
        np.nan,
    )
    # Replace any accidental inf values with NaN
    georef_gdf["cvh"] = georef_gdf["cvh"].replace([np.inf, -np.inf], np.nan)

    return georef_gdf

georefinspect_cli()

Command-line interface for GEOREF cell inspection.

CLI options

-r, --resolution: GEOREF resolution level (0-10)

Source code in vgrid/stats/georefstats.py

def georefinspect_cli():
    """
    Command-line interface for GEOREF cell inspection.

    CLI options:
      -r, --resolution: GEOREF resolution level (0-10)
    """
    parser = argparse.ArgumentParser(add_help=False)
    parser.add_argument("-r", "--resolution", dest="resolution", type=int, default=0)
    add_verbose_argument(parser)
    args = parser.parse_args()  # type: ignore
    resolution = args.resolution
    print(georefinspect(resolution, verbose=args.verbose))

georefstats_cli()

Command-line interface for generating GEOREF DGGS statistics.

CLI options

-unit, --unit {m,km}

Source code in vgrid/stats/georefstats.py

def georefstats_cli():
    """
    Command-line interface for generating GEOREF DGGS statistics.

    CLI options:
      -unit, --unit {m,km}
    """
    parser = argparse.ArgumentParser(add_help=False)
    parser.add_argument(
        "-unit", "--unit", dest="unit", choices=["m", "km"], default="m"
    )
    args = parser.parse_args()  # type: ignore

    unit = args.unit

    # Get the DataFrame
    df = georefstats(unit=unit)

    # Display the DataFrame
    print(df)

h3inspect(resolution, fix_antimeridian=None, verbose=True)

Generate comprehensive inspection data for H3 DGGS cells at a given resolution.

This function creates a detailed analysis of H3 cells including area variations, compactness measures, and Antimeridian crossing detection.

Parameters:

Name	Type	Description	Default
resolution	int	H3 resolution level (0-15)	required
fix_antimeridian	None	Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none	None
verbose		Show progress bars. Defaults to True.	True

Source code in vgrid/stats/h3stats.py

def h3inspect(resolution: int, fix_antimeridian: None = None, verbose=True):
    """
    Generate comprehensive inspection data for H3 DGGS cells at a given resolution.

    This function creates a detailed analysis of H3 cells including area variations,
    compactness measures, and Antimeridian crossing detection.

    Args:
        resolution: H3 resolution level (0-15)
        fix_antimeridian: Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none

        verbose: Show progress bars. Defaults to True.
    Returns:
        geopandas.GeoDataFrame: DataFrame containing H3 cell inspection data with columns:
            - h3: H3 cell ID
            - resolution: Resolution level
            - geometry: Cell geometry
            - cell_area: Cell area in square meters
            - cell_perimeter: Cell perimeter in meters
            - crossed: Whether cell crosses the Antimeridian
            - is_pentagon: Whether cell is a pentagon
            - norm_area: Normalized area (cell_area / mean_area)
            - ipq: Isoperimetric Quotient compactness
            - zsc: Zonal Standardized Compactness
    """
    h3_gdf = h3grid(resolution, output_format="gpd", fix_antimeridian=fix_antimeridian, verbose=verbose)
    h3_gdf["crossed"] = h3_gdf["geometry"].apply(check_crossing_geom)
    h3_gdf = h3_gdf[~h3_gdf["crossed"]]  # remove cells that cross the Antimeridian
    h3_gdf["is_pentagon"] = h3_gdf["h3"].apply(h3.is_pentagon)
    # mean_area = h3_gdf["cell_area"].mean()
    mean_area = AUTHALIC_AREA / h3.get_num_cells(resolution)
    # Calculate normalized area
    h3_gdf["norm_area"] = h3_gdf["cell_area"] / mean_area
    # Calculate IPQ compactness using the standard formula: CI = 4πA/P²
    h3_gdf["ipq"] = 4 * np.pi * h3_gdf["cell_area"] / (h3_gdf["cell_perimeter"] ** 2)
    # Calculate zonal standardized compactness
    h3_gdf["zsc"] = (
        np.sqrt(
            4 * np.pi * h3_gdf["cell_area"]
            - np.power(h3_gdf["cell_area"], 2) / np.power(6378137, 2)
        )
        / h3_gdf["cell_perimeter"]
    )

    # Compute convex hull using Lambert Azimuthal Equal Area projection
    convex_hull = h3_gdf["geometry"].apply(convexhull_from_lambert)
    # Calculate convex hull area using Lambert projection
    convex_hull_area = convex_hull.apply(
        lambda g: get_area_perimeter_from_lambert(g)[0] if g is not None else np.nan
    )
    # Calculate cell area using Lambert projection for consistent cvh calculation
    h3_gdf_lambert = get_cells_area(h3_gdf.copy(), "LAEA")
    # Compute CVH safely; set to NaN where convex hull area is non-positive or invalid
    h3_gdf["cvh"] = np.where(
        (convex_hull_area > 0) & np.isfinite(convex_hull_area),
        h3_gdf_lambert["area"] / convex_hull_area,
        np.nan,
    )
    # Replace any accidental inf values with NaN
    h3_gdf["cvh"] = h3_gdf["cvh"].replace([np.inf, -np.inf], np.nan)
    return h3_gdf

h3inspect_cli()

Command-line interface for H3 cell inspection.

CLI options

-r, --resolution: H3 resolution level (0-15) -split, --split_antimeridian: Apply antimeridian fixing to the resulting polygons

Source code in vgrid/stats/h3stats.py

def h3inspect_cli():
    """
    Command-line interface for H3 cell inspection.

    CLI options:
      -r, --resolution: H3 resolution level (0-15)
      -split, --split_antimeridian: Apply antimeridian fixing to the resulting polygons
    """
    parser = argparse.ArgumentParser(add_help=False)
    parser.add_argument("-r", "--resolution", dest="resolution", type=int, default=0)
    parser.add_argument(
        "-fix--fix_antimeridian",
        type=str,
        choices=[
            "shift",
            "shift_balanced",
            "shift_west",
            "shift_east",
            "split",
            "none",
        ],
        default=None,
        help="Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none",
    )
    add_verbose_argument(parser)
    args = parser.parse_args()  # type: ignore
    resolution = args.resolution
    print(h3inspect(resolution, fix_antimeridian=args.fix_antimeridian, verbose=args.verbose))

h3stats_cli()

Command-line interface for generating H3 DGGS statistics.

CLI options

-unit, --unit {m,km}

Source code in vgrid/stats/h3stats.py

def h3stats_cli():
    """
    Command-line interface for generating H3 DGGS statistics.

    CLI options:
      -unit, --unit {m,km}
    """
    parser = argparse.ArgumentParser(add_help=False)
    parser.add_argument(
        "-unit", "--unit", dest="unit", choices=["m", "km"], default="m"
    )
    args = parser.parse_args()  # type: ignore

    unit = args.unit

    df = h3stats(unit=unit)
    df["number_of_cells"] = df["number_of_cells"].apply(lambda x: "{:,.0f}".format(x))
    print(df)

isea3hinspect(resolution, fix_antimeridian=None, verbose=True)

Generate comprehensive inspection data for ISEA3H DGGS cells at a given resolution.

This function creates a detailed analysis of ISEA3H cells including area variations, compactness measures, and Antimeridian crossing detection.

Parameters:

Name	Type	Description	Default
resolution	int	ISEA3H resolution level (0-40)	required
fix_antimeridian	None	Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none	None
verbose		Show progress bars. Defaults to True.	True

Source code in vgrid/stats/isea3hstats.py

def isea3hinspect(resolution: int, fix_antimeridian: None = None, verbose=True):
    """
    Generate comprehensive inspection data for ISEA3H DGGS cells at a given resolution.

    This function creates a detailed analysis of ISEA3H cells including area variations,
    compactness measures, and Antimeridian crossing detection.

    Args:
        resolution: ISEA3H resolution level (0-40)
        fix_antimeridian: Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none
        verbose: Show progress bars. Defaults to True.
    Returns:
        geopandas.GeoDataFrame: DataFrame containing ISEA3H cell inspection data with columns:
            - isea3h: ISEA3H cell ID
            - resolution: Resolution level
            - geometry: Cell geometry
            - cell_area: Cell area in square meters
            - cell_perimeter: Cell perimeter in meters
            - crossed: Whether cell crosses the Antimeridian
            - norm_area: Normalized area (cell_area / mean_area)
            - ipq: Isoperimetric Quotient compactness
            - zsc: Zonal Standardized Compactness
    """
    # Allow running on all platforms

    isea3h_gdf = isea3hgrid(
        resolution, output_format="gpd", fix_antimeridian=fix_antimeridian, verbose=verbose
    )  # remove cells that cross the Antimeridian
    isea3h_gdf["crossed"] = isea3h_gdf["geometry"].apply(check_crossing_geom)
    isea3h_gdf = isea3h_gdf[
        ~isea3h_gdf["crossed"]
    ]  # remove cells that cross the Antimeridian
    mean_area = isea3h_gdf["cell_area"].mean()
    # Calculate normalized area
    isea3h_gdf["norm_area"] = isea3h_gdf["cell_area"] / mean_area
    # Calculate IPQ compactness using the standard formula: CI = 4πA/P²
    isea3h_gdf["ipq"] = (
        4 * np.pi * isea3h_gdf["cell_area"] / (isea3h_gdf["cell_perimeter"] ** 2)
    )
    # Calculate zonal standardized compactness
    isea3h_gdf["zsc"] = (
        np.sqrt(
            4 * np.pi * isea3h_gdf["cell_area"]
            - np.power(isea3h_gdf["cell_area"], 2) / np.power(6378137, 2)
        )
        / isea3h_gdf["cell_perimeter"]
    )

    # Compute convex hull using Lambert Azimuthal Equal Area projection
    convex_hull = isea3h_gdf["geometry"].apply(convexhull_from_lambert)
    # Calculate convex hull area using Lambert projection
    convex_hull_area = convex_hull.apply(
        lambda g: get_area_perimeter_from_lambert(g)[0] if g is not None else np.nan
    )
    # Calculate cell area using Lambert projection for consistent cvh calculation
    isea3h_gdf_lambert = get_cells_area(isea3h_gdf.copy(), "LAEA")
    # Compute CVH safely; set to NaN where convex hull area is non-positive or invalid
    isea3h_gdf["cvh"] = np.where(
        (convex_hull_area > 0) & np.isfinite(convex_hull_area),
        isea3h_gdf_lambert["area"] / convex_hull_area,
        np.nan,
    )
    # Replace any accidental inf values with NaN
    isea3h_gdf["cvh"] = isea3h_gdf["cvh"].replace([np.inf, -np.inf], np.nan)
    return isea3h_gdf

isea3hinspect_cli()

Command-line interface for ISEA3H cell inspection.

CLI options

-r, --resolution: ISEA3H resolution level (0-40) -split, --split_antimeridian: Enable antimeridian splitting (default: enabled)

Source code in vgrid/stats/isea3hstats.py

def isea3hinspect_cli():
    """
    Command-line interface for ISEA3H cell inspection.

    CLI options:
      -r, --resolution: ISEA3H resolution level (0-40)
      -split, --split_antimeridian: Enable antimeridian splitting (default: enabled)
    """

    parser = argparse.ArgumentParser(add_help=False)
    parser.add_argument("-r", "--resolution", dest="resolution", type=int, default=0)
    parser.add_argument(
        "-split",
        "--split_antimeridian",
        action="store_true",
        default=False,  # default is False to avoid splitting the Antimeridian by default
        help="Enable antimeridian splitting",
    )
    add_verbose_argument(parser)
    args = parser.parse_args()  # type: ignore
    resolution = args.resolution
    split_antimeridian = args.split_antimeridian
    print(isea3hinspect(resolution, split_antimeridian=split_antimeridian, verbose=args.verbose))

isea3hstats_cli()

Command-line interface for generating ISEA3H DGGS statistics.

CLI options

-unit, --unit {m,km}

Source code in vgrid/stats/isea3hstats.py

def isea3hstats_cli():
    """
    Command-line interface for generating ISEA3H DGGS statistics.

    CLI options:
      -unit, --unit {m,km}
    """
    parser = argparse.ArgumentParser(add_help=False)
    parser.add_argument(
        "-unit", "--unit", dest="unit", choices=["m", "km"], default="m"
    )
    args = parser.parse_args()  # type: ignore

    unit = args.unit

    # Get the DataFrame
    df = isea3hstats(unit=unit)

    # Display the DataFrame
    print(df)

isea4tinspect(resolution, fix_antimeridian=None, verbose=True)

Generate comprehensive inspection data for ISEA4T DGGS cells at a given resolution.

This function creates a detailed analysis of ISEA4T cells including area variations, compactness measures, and dateline crossing detection.

Parameters:

Name	Type	Description	Default
resolution		ISEA4T resolution level (0-15)	required
fix_antimeridian	None	Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none	None
verbose		Show progress bars. Defaults to True.	True

Source code in vgrid/stats/isea4tstats.py

def isea4tinspect(resolution, fix_antimeridian: None = None, verbose=True):
    """
    Generate comprehensive inspection data for ISEA4T DGGS cells at a given resolution.

    This function creates a detailed analysis of ISEA4T cells including area variations,
    compactness measures, and dateline crossing detection.

    Args:
        resolution: ISEA4T resolution level (0-15)
        fix_antimeridian: Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none
        verbose: Show progress bars. Defaults to True.
    Returns:
        geopandas.GeoDataFrame: DataFrame containing ISEA4T cell inspection data with columns:
            - isea4t: ISEA4T cell ID
            - resolution: Resolution level
            - geometry: Cell geometry
            - cell_area: Cell area in square meters
            - cell_perimeter: Cell perimeter in meters
            - crossed: Whether cell crosses the dateline
            - norm_area: Normalized area (cell_area / mean_area)
            - ipq: Isoperimetric Quotient compactness
            - zsc: Zonal Standardized Compactness
    """
    # Allow running on all platforms
    resolution = validate_isea4t_resolution(resolution)
    isea4t_gdf = isea4tgrid(
        resolution, output_format="gpd", fix_antimeridian=fix_antimeridian, verbose=verbose
    )
    isea4t_gdf["crossed"] = isea4t_gdf["geometry"].apply(check_crossing_geom)
    isea4t_gdf = isea4t_gdf[
        ~isea4t_gdf["crossed"]
    ]  # remove cells that cross the Antimeridian
    # mean_area = isea4t_gdf["cell_area"].mean()
    num_cells = 20 * (4**resolution)
    mean_area = AUTHALIC_AREA / num_cells
    # Calculate normalized area
    isea4t_gdf["norm_area"] = isea4t_gdf["cell_area"] / mean_area
    # Calculate IPQ compactness using the standard formula: CI = 4πA/P²
    isea4t_gdf["ipq"] = (
        4 * np.pi * isea4t_gdf["cell_area"] / (isea4t_gdf["cell_perimeter"] ** 2)
    )
    # Calculate zonal standardized compactness
    isea4t_gdf["zsc"] = (
        np.sqrt(
            4 * np.pi * isea4t_gdf["cell_area"]
            - np.power(isea4t_gdf["cell_area"], 2) / np.power(6378137, 2)
        )
        / isea4t_gdf["cell_perimeter"]
    )

    # Compute convex hull using Lambert Azimuthal Equal Area projection
    convex_hull = isea4t_gdf["geometry"].apply(convexhull_from_lambert)
    # Calculate convex hull area using Lambert projection
    convex_hull_area = convex_hull.apply(
        lambda g: get_area_perimeter_from_lambert(g)[0] if g is not None else np.nan
    )
    # Calculate cell area using Lambert projection for consistent cvh calculation
    isea4t_gdf_lambert = get_cells_area(isea4t_gdf.copy(), "LAEA")
    # Compute CVH safely; set to NaN where convex hull area is non-positive or invalid
    isea4t_gdf["cvh"] = np.where(
        (convex_hull_area > 0) & np.isfinite(convex_hull_area),
        isea4t_gdf_lambert["area"] / convex_hull_area,
        np.nan,
    )
    # Replace any accidental inf values with NaN
    isea4t_gdf["cvh"] = isea4t_gdf["cvh"].replace([np.inf, -np.inf], np.nan)
    return isea4t_gdf

isea4tinspect_cli()

Command-line interface for ISEA4T cell inspection.

CLI options

-r, --resolution: ISEA4T resolution level (0-15)

-fix, --fix_antimeridian: Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none

Source code in vgrid/stats/isea4tstats.py

def isea4tinspect_cli():
    """
    Command-line interface for ISEA4T cell inspection.

    CLI options:
      -r, --resolution: ISEA4T resolution level (0-15)
    -fix, --fix_antimeridian: Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none
    """
    parser = argparse.ArgumentParser(add_help=False)
    parser.add_argument("-r", "--resolution", dest="resolution", type=int, default=0)
    parser.add_argument(
        "-fix",
        "--fix_antimeridian",
        type=str,
        choices=[
            "shift",
            "shift_balanced",
            "shift_west",
            "shift_east",
            "split",
            "none",
        ],
        default=None,
        help="Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none",
    )
    add_verbose_argument(parser)
    args = parser.parse_args()
    resolution = args.resolution
    fix_antimeridian = args.fix_antimeridian
    print(isea4tinspect(resolution, fix_antimeridian=fix_antimeridian, verbose=args.verbose))

isea4tstats_cli()

Command-line interface for generating ISEA4T DGGS statistics.

CLI options

-unit, --unit {m,km}

Source code in vgrid/stats/isea4tstats.py

def isea4tstats_cli():
    """
    Command-line interface for generating ISEA4T DGGS statistics.

    CLI options:
      -unit, --unit {m,km}
    """
    parser = argparse.ArgumentParser(add_help=False)
    parser.add_argument(
        "-unit", "--unit", dest="unit", choices=["m", "km"], default="m"
    )
    args, _ = parser.parse_known_args()  # type: ignore

    unit = args.unit

    # Get the DataFrame
    df = isea4tstats(unit=unit)

    # Display the DataFrame
    print(df)

maidenheadinspect(resolution, verbose=True)

Generate comprehensive inspection data for Maidenhead DGGS cells at a given resolution.

This function creates a detailed analysis of Maidenhead cells including area variations, compactness measures, and dateline crossing detection.

Parameters:

Name	Type	Description	Default
resolution	int	Maidenhead resolution level (1-4)	required
verbose		Show progress bars. Defaults to True.	True

Source code in vgrid/stats/maidenheadstats.py

def maidenheadinspect(resolution: int, verbose=True):
    """
    Generate comprehensive inspection data for Maidenhead DGGS cells at a given resolution.

    This function creates a detailed analysis of Maidenhead cells including area variations,
    compactness measures, and dateline crossing detection.

    Args:
        resolution: Maidenhead resolution level (1-4)

        verbose: Show progress bars. Defaults to True.
    Returns:
        geopandas.GeoDataFrame: DataFrame containing Maidenhead cell inspection data with columns:
            - maidenhead: Maidenhead cell ID
            - resolution: Resolution level
            - geometry: Cell geometry
            - cell_area: Cell area in square meters
            - cell_perimeter: Cell perimeter in meters
            - crossed: Whether cell crosses the dateline
            - norm_area: Normalized area (cell_area / mean_area)
            - ipq: Isoperimetric Quotient compactness
            - zsc: Zonal Standardized Compactness
    """
    resolution = validate_maidenhead_resolution(resolution)
    maidenhead_gdf = maidenheadgrid(resolution, output_format="gpd", verbose=verbose)
    maidenhead_gdf["crossed"] = maidenhead_gdf["geometry"].apply(check_crossing_geom)
    # mean_area = maidenhead_gdf["cell_area"].mean()
    mean_area = AUTHALIC_AREA / maidenhead.num_cells(resolution)
    # Calculate normalized area
    maidenhead_gdf["norm_area"] = maidenhead_gdf["cell_area"] / mean_area
    # Calculate IPQ compactness using the standard formula: CI = 4πA/P²
    maidenhead_gdf["ipq"] = (
        4
        * np.pi
        * maidenhead_gdf["cell_area"]
        / (maidenhead_gdf["cell_perimeter"] ** 2)
    )
    # Calculate zonal standardized compactness
    maidenhead_gdf["zsc"] = (
        np.sqrt(
            4 * np.pi * maidenhead_gdf["cell_area"]
            - np.power(maidenhead_gdf["cell_area"], 2) / np.power(6378137, 2)
        )
        / maidenhead_gdf["cell_perimeter"]
    )

    # Compute convex hull using Lambert Azimuthal Equal Area projection
    convex_hull = maidenhead_gdf["geometry"].apply(convexhull_from_lambert)
    # Calculate convex hull area using Lambert projection
    convex_hull_area = convex_hull.apply(
        lambda g: get_area_perimeter_from_lambert(g)[0] if g is not None else np.nan
    )
    # Calculate cell area using Lambert projection for consistent cvh calculation
    maidenhead_gdf_lambert = get_cells_area(maidenhead_gdf.copy(), "LAEA")
    # Compute CVH safely; set to NaN where convex hull area is non-positive or invalid
    maidenhead_gdf["cvh"] = np.where(
        (convex_hull_area > 0) & np.isfinite(convex_hull_area),
        maidenhead_gdf_lambert["area"] / convex_hull_area,
        np.nan,
    )
    # Replace any accidental inf values with NaN
    maidenhead_gdf["cvh"] = maidenhead_gdf["cvh"].replace([np.inf, -np.inf], np.nan)

    return maidenhead_gdf

maidenheadinspect_cli()

Command-line interface for Maidenhead cell inspection.

CLI options

-r, --resolution: Maidenhead resolution level (1-4)

Source code in vgrid/stats/maidenheadstats.py

def maidenheadinspect_cli():
    """
    Command-line interface for Maidenhead cell inspection.

    CLI options:
      -r, --resolution: Maidenhead resolution level (1-4)
    """
    parser = argparse.ArgumentParser(add_help=False)
    parser.add_argument("-r", "--resolution", dest="resolution", type=int, default=0)
    add_verbose_argument(parser)
    args, _ = parser.parse_known_args()  # type: ignore
    resolution = args.resolution
    print(maidenheadinspect(resolution, verbose=args.verbose))

maidenheadstats_cli()

Command-line interface for generating Maidenhead DGGS statistics.

CLI options

-unit, --unit {m,km}

Source code in vgrid/stats/maidenheadstats.py

def maidenheadstats_cli():
    """
    Command-line interface for generating Maidenhead DGGS statistics.

    CLI options:
      -unit, --unit {m,km}
    """
    parser = argparse.ArgumentParser(add_help=False)
    parser.add_argument(
        "-unit", "--unit", dest="unit", choices=["m", "km"], default="m"
    )
    args, _ = parser.parse_known_args()  # type: ignore

    unit = args.unit

    # Get the DataFrame
    df = maidenheadstats(unit=unit)

    # Display the DataFrame
    print(df)

mgrsstats_cli()

Command-line interface for generating MGRS DGGS statistics.

CLI options

-unit, --unit {m,km}

Source code in vgrid/stats/mgrsstats.py

def mgrsstats_cli():
    """
    Command-line interface for generating MGRS DGGS statistics.

    CLI options:
      -unit, --unit {m,km}
    """
    parser = argparse.ArgumentParser(add_help=False)
    parser.add_argument(
        "-unit", "--unit", dest="unit", choices=["m", "km"], default="m"
    )
    args = parser.parse_args()  # type: ignore

    unit = args.unit

    print("Resolution 0: 100 x 100 km")
    print("Resolution 1: 10 x 10 km")
    print("2 <= Resolution <= 5 = Finer subdivisions (1 x 1 km, 0.1 x 0.11 km, etc.)")

    # Get the DataFrame
    df = mgrsstats(unit=unit)

    # Display the DataFrame
    print(df)

olcinspect(resolution, verbose=True)

Generate comprehensive inspection data for OLC DGGS cells at a given resolution.

This function creates a detailed analysis of OLC cells including area variations, compactness measures, and dateline crossing detection.

Parameters:

Name	Type	Description	Default
resolution	int	OLC resolution level (2-15)	required
verbose		Show progress bars. Defaults to True.	True

Source code in vgrid/stats/olcstats.py

def olcinspect(resolution: int, verbose=True):
    """
    Generate comprehensive inspection data for OLC DGGS cells at a given resolution.

    This function creates a detailed analysis of OLC cells including area variations,
    compactness measures, and dateline crossing detection.

    Args:
        resolution: OLC resolution level (2-15)

        verbose: Show progress bars. Defaults to True.
    Returns:
        geopandas.GeoDataFrame: DataFrame containing OLC cell inspection data with columns:
            - olc: OLC cell ID
            - resolution: Resolution level
            - geometry: Cell geometry
            - cell_area: Cell area in square meters
            - cell_perimeter: Cell perimeter in meters
            - crossed: Whether cell crosses the dateline
            - norm_area: Normalized area (cell_area / mean_area)
            - ipq: Isoperimetric Quotient compactness
            - zsc: Zonal Standardized Compactness
    """
    olc_gdf = olcgrid(resolution, output_format="gpd", verbose=verbose)
    olc_gdf["crossed"] = olc_gdf["geometry"].apply(check_crossing_geom)
    # mean_area = olc_gdf["cell_area"].mean()
    if resolution <= 10:
        num_cells = 162 * (400 ** ((resolution // 2) - 1))
    else:
        base = 162 * (400 ** ((10 // 2) - 1))
        extra = resolution - 10
        num_cells = base * (20**extra)
    mean_area = AUTHALIC_AREA / num_cells
    # Calculate normalized area
    olc_gdf["norm_area"] = olc_gdf["cell_area"] / mean_area
    # Calculate IPQ compactness using the standard formula: CI = 4πA/P²
    olc_gdf["ipq"] = 4 * np.pi * olc_gdf["cell_area"] / (olc_gdf["cell_perimeter"] ** 2)
    # Calculate zonal standardized compactness
    olc_gdf["zsc"] = (
        np.sqrt(
            4 * np.pi * olc_gdf["cell_area"]
            - np.power(olc_gdf["cell_area"], 2) / np.power(6378137, 2)
        )
        / olc_gdf["cell_perimeter"]
    )

    # Compute convex hull using Lambert Azimuthal Equal Area projection
    convex_hull = olc_gdf["geometry"].apply(convexhull_from_lambert)
    # Calculate convex hull area using Lambert projection
    convex_hull_area = convex_hull.apply(
        lambda g: get_area_perimeter_from_lambert(g)[0] if g is not None else np.nan
    )
    # Calculate cell area using Lambert projection for consistent cvh calculation
    olc_gdf_lambert = get_cells_area(olc_gdf.copy(), "LAEA")
    # Compute CVH safely; set to NaN where convex hull area is non-positive or invalid
    olc_gdf["cvh"] = np.where(
        (convex_hull_area > 0) & np.isfinite(convex_hull_area),
        olc_gdf_lambert["area"] / convex_hull_area,
        np.nan,
    )
    # Replace any accidental inf values with NaN
    olc_gdf["cvh"] = olc_gdf["cvh"].replace([np.inf, -np.inf], np.nan)

    return olc_gdf

olcinspect_cli()

Command-line interface for OLC cell inspection.

CLI options

-r, --resolution: OLC resolution level (2-15)

Source code in vgrid/stats/olcstats.py

def olcinspect_cli():
    """
    Command-line interface for OLC cell inspection.

    CLI options:
      -r, --resolution: OLC resolution level (2-15)
    """
    parser = argparse.ArgumentParser(add_help=False)
    parser.add_argument("-r", "--resolution", dest="resolution", type=int, default=0)
    add_verbose_argument(parser)
    args, _ = parser.parse_known_args()  # type: ignore
    resolution = args.resolution
    print(olcinspect(resolution, verbose=args.verbose))

olcstats_cli()

Command-line interface for generating OLC DGGS statistics.

CLI options

-unit, --unit {m,km}

Source code in vgrid/stats/olcstats.py

def olcstats_cli():
    """
    Command-line interface for generating OLC DGGS statistics.

    CLI options:
      -unit, --unit {m,km}
    """
    parser = argparse.ArgumentParser(add_help=False)
    parser.add_argument(
        "-unit", "--unit", dest="unit", choices=["m", "km"], default="m"
    )
    args, _ = parser.parse_known_args()  # type: ignore

    unit = args.unit

    # Get the DataFrame
    df = olcstats(unit=unit)

    # Display the DataFrame
    print(df)

qtminspect(resolution, verbose=True)

Generate comprehensive inspection data for QTM DGGS cells at a given resolution.

This function creates a detailed analysis of QTM cells including area variations, compactness measures, and dateline crossing detection.

Parameters:

Name	Type	Description	Default
resolution	int	QTM resolution level (1-24)	required
verbose		Show progress bars. Defaults to True.	True

Source code in vgrid/stats/qtmstats.py

def qtminspect(resolution: int, verbose=True):
    """
    Generate comprehensive inspection data for QTM DGGS cells at a given resolution.

    This function creates a detailed analysis of QTM cells including area variations,
    compactness measures, and dateline crossing detection.

    Args:
        resolution: QTM resolution level (1-24)

        verbose: Show progress bars. Defaults to True.
    Returns:
        geopandas.GeoDataFrame: DataFrame containing QTM cell inspection data with columns:
            - qtm: QTM cell ID
            - resolution: Resolution level
            - geometry: Cell geometry
            - cell_area: Cell area in square meters
            - cell_perimeter: Cell perimeter in meters
            - crossed: Whether cell crosses the dateline
            - norm_area: Normalized area (cell_area / mean_area)
            - ipq: Isoperimetric Quotient compactness
            - zsc: Zonal Standardized Compactness
    """
    qtm_gdf = qtm_grid(resolution, verbose=verbose)
    qtm_gdf["crossed"] = qtm_gdf["geometry"].apply(check_crossing_geom)
    qtm_gdf = qtm_gdf[~qtm_gdf["crossed"]]  # remove cells that cross the Antimeridian
    # mean_area = qtm_gdf["cell_area"].mean()
    num_cells = 8 * 4 ** (resolution - 1)
    mean_area = AUTHALIC_AREA / num_cells
    # Calculate normalized area
    qtm_gdf["norm_area"] = qtm_gdf["cell_area"] / mean_area
    # Calculate IPQ compactness using the standard formula: CI = 4πA/P²
    qtm_gdf["ipq"] = 4 * np.pi * qtm_gdf["cell_area"] / (qtm_gdf["cell_perimeter"] ** 2)
    # Calculate zonal standardized compactness
    qtm_gdf["zsc"] = (
        np.sqrt(
            4 * np.pi * qtm_gdf["cell_area"]
            - np.power(qtm_gdf["cell_area"], 2) / np.power(6378137, 2)
        )
        / qtm_gdf["cell_perimeter"]
    )

    # Compute convex hull using Lambert Azimuthal Equal Area projection
    convex_hull = qtm_gdf["geometry"].apply(convexhull_from_lambert)
    # Calculate convex hull area using Lambert projection
    convex_hull_area = convex_hull.apply(
        lambda g: get_area_perimeter_from_lambert(g)[0] if g is not None else np.nan
    )
    # Calculate cell area using Lambert projection for consistent cvh calculation
    qtm_gdf_lambert = get_cells_area(qtm_gdf.copy(), "LAEA")
    # Compute CVH safely; set to NaN where convex hull area is non-positive or invalid
    qtm_gdf["cvh"] = np.where(
        (convex_hull_area > 0) & np.isfinite(convex_hull_area),
        qtm_gdf_lambert["area"] / convex_hull_area,
        np.nan,
    )
    # Replace any accidental inf values with NaN
    qtm_gdf["cvh"] = qtm_gdf["cvh"].replace([np.inf, -np.inf], np.nan)

    return qtm_gdf

qtminspect_cli()

Command-line interface for QTM cell inspection.

CLI options

-r, --resolution: QTM resolution level (1-24)

Source code in vgrid/stats/qtmstats.py

def qtminspect_cli():
    """
    Command-line interface for QTM cell inspection.

    CLI options:
      -r, --resolution: QTM resolution level (1-24)
    """
    parser = argparse.ArgumentParser(add_help=False)
    parser.add_argument("-r", "--resolution", dest="resolution", type=int, default=0)
    add_verbose_argument(parser)
    args = parser.parse_args()
    resolution = args.resolution
    print(qtminspect(resolution, verbose=args.verbose))

qtmstats_cli()

Command-line interface for generating QTM DGGS statistics.

CLI options

-unit, --unit {m,km}

Source code in vgrid/stats/qtmstats.py

def qtmstats_cli():
    """
    Command-line interface for generating QTM DGGS statistics.

    CLI options:
      -unit, --unit {m,km}
    """
    parser = argparse.ArgumentParser(add_help=False)
    parser.add_argument(
        "-unit", "--unit", dest="unit", choices=["m", "km"], default="m"
    )
    args = parser.parse_args()
    unit = args.unit
    # Get the DataFrame
    df = qtmstats(unit=unit)
    # Display the DataFrame
    print(df)

quadkeyinspect(resolution, verbose=True)

Generate comprehensive inspection data for Quadkey DGGS cells at a given resolution.

This function creates a detailed analysis of Quadkey cells including area variations, compactness measures, and dateline crossing detection.

Parameters:

Name	Type	Description	Default
resolution	int	Quadkey resolution level (0-29)	required
verbose		Show progress bars. Defaults to True.	True

Source code in vgrid/stats/quadkeystats.py

def quadkeyinspect(resolution: int, verbose=True):
    """
    Generate comprehensive inspection data for Quadkey DGGS cells at a given resolution.

    This function creates a detailed analysis of Quadkey cells including area variations,
    compactness measures, and dateline crossing detection.

    Args:
        resolution: Quadkey resolution level (0-29)

        verbose: Show progress bars. Defaults to True.
    Returns:
        geopandas.GeoDataFrame: DataFrame containing Quadkey cell inspection data with columns:
            - quadkey: Quadkey cell ID
            - resolution: Resolution level
            - geometry: Cell geometry
            - cell_area: Cell area in square meters
            - cell_perimeter: Cell perimeter in meters
            - crossed: Whether cell crosses the dateline
            - norm_area: Normalized area (cell_area / mean_area)
            - ipq: Isoperimetric Quotient compactness
            - zsc: Zonal Standardized Compactness
    """
    quadkey_gdf = quadkeygrid(resolution, output_format="gpd", verbose=verbose)
    quadkey_gdf["crossed"] = quadkey_gdf["geometry"].apply(check_crossing_geom)
    # mean_area = quadkey_gdf["cell_area"].mean()
    num_cells = 4**resolution
    mean_area = AUTHALIC_AREA / num_cells
    # Calculate normalized area
    quadkey_gdf["norm_area"] = quadkey_gdf["cell_area"] / mean_area
    # Calculate IPQ compactness using the standard formula: CI = 4πA/P²
    quadkey_gdf["ipq"] = (
        4 * np.pi * quadkey_gdf["cell_area"] / (quadkey_gdf["cell_perimeter"] ** 2)
    )
    # Calculate zonal standardized compactness
    quadkey_gdf["zsc"] = (
        np.sqrt(
            4 * np.pi * quadkey_gdf["cell_area"]
            - np.power(quadkey_gdf["cell_area"], 2) / np.power(6378137, 2)
        )
        / quadkey_gdf["cell_perimeter"]
    )

    # Compute convex hull using Lambert Azimuthal Equal Area projection
    convex_hull = quadkey_gdf["geometry"].apply(convexhull_from_lambert)
    # Calculate convex hull area using Lambert projection
    convex_hull_area = convex_hull.apply(
        lambda g: get_area_perimeter_from_lambert(g)[0] if g is not None else np.nan
    )
    # Calculate cell area using Lambert projection for consistent cvh calculation
    quadkey_gdf_lambert = get_cells_area(quadkey_gdf.copy(), "LAEA")
    # Compute CVH safely; set to NaN where convex hull area is non-positive or invalid
    quadkey_gdf["cvh"] = np.where(
        (convex_hull_area > 0) & np.isfinite(convex_hull_area),
        quadkey_gdf_lambert["area"] / convex_hull_area,
        np.nan,
    )
    # Replace any accidental inf values with NaN
    quadkey_gdf["cvh"] = quadkey_gdf["cvh"].replace([np.inf, -np.inf], np.nan)

    return quadkey_gdf

quadkeyinspect_cli()

Command-line interface for Quadkey cell inspection.

CLI options

-r, --resolution: Quadkey resolution level (0-29)

Source code in vgrid/stats/quadkeystats.py

def quadkeyinspect_cli():
    """
    Command-line interface for Quadkey cell inspection.

    CLI options:
      -r, --resolution: Quadkey resolution level (0-29)
    """
    parser = argparse.ArgumentParser(add_help=False)
    parser.add_argument("-r", "--resolution", dest="resolution", type=int, default=None)
    add_verbose_argument(parser)
    args, _ = parser.parse_known_args()
    res = args.resolution if args.resolution is not None else 2
    print(quadkeyinspect(res, verbose=args.verbose))

quadkeystats_cli()

Command-line interface for generating Quadkey DGGS statistics.

CLI options

-unit, --unit {m,km}

Source code in vgrid/stats/quadkeystats.py

def quadkeystats_cli():
    """
    Command-line interface for generating Quadkey DGGS statistics.

    CLI options:
      -unit, --unit {m,km}
    """
    parser = argparse.ArgumentParser(add_help=False)
    parser.add_argument(
        "-unit", "--unit", dest="unit", choices=["m", "km"], default="m"
    )
    args = parser.parse_args()
    unit = args.unit
    # Get the DataFrame
    df = quadkeystats(unit=unit)
    # Display the DataFrame
    print(df)

rhealpixinspect(resolution=0, fix_antimeridian=None, verbose=True)

Generate comprehensive inspection data for rHEALPix DGGS cells at a given resolution.

This function creates a detailed analysis of rHEALPix cells including area variations, compactness measures, and dateline crossing detection.

Parameters:

Name	Type	Description	Default
resolution	int	rHEALPix resolution level (0-15)	0
fix_antimeridian	str	Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none	None
verbose		Show progress bars. Defaults to True.	True

Source code in vgrid/stats/rhealpixstats.py

def rhealpixinspect(resolution: int = 0, fix_antimeridian: str = None, verbose=True):
    """
    Generate comprehensive inspection data for rHEALPix DGGS cells at a given resolution.

    This function creates a detailed analysis of rHEALPix cells including area variations,
    compactness measures, and dateline crossing detection.

    Args:
        resolution: rHEALPix resolution level (0-15)
        fix_antimeridian: Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none
        Defaults to False to avoid splitting the Antimeridian by default.
        verbose: Show progress bars. Defaults to True.
    Returns:
        geopandas.GeoDataFrame: DataFrame containing rHEALPix cell inspection data with columns:
            - rhealpix: rHEALPix cell ID
            - resolution: Resolution level
            - geometry: Cell geometry
            - cell_area: Cell area in square meters
            - cell_perimeter: Cell perimeter in meters
            - crossed: Whether cell crosses the dateline
            - norm_area: Normalized area (cell_area / mean_area)
            - ipq: Isoperimetric Quotient compactness
            - zsc: Zonal Standardized Compactness
            - cvh: Convex Hull Compactness
    """
    rhealpix_gdf = rhealpixgrid(
        resolution, output_format="gpd", fix_antimeridian=fix_antimeridian, verbose=verbose
    )  # type: ignore
    rhealpix_gdf["crossed"] = rhealpix_gdf["geometry"].apply(check_crossing_geom)
    rhealpix_gdf = rhealpix_gdf[
        ~rhealpix_gdf["crossed"]
    ]  # remove cells that cross the Antimeridian
    # mean_area = rhealpix_gdf["cell_area"].mean()
    num_cells = 6 * 9 ** (resolution)
    mean_area = AUTHALIC_AREA / num_cells
    # Calculate normalized area
    rhealpix_gdf["norm_area"] = rhealpix_gdf["cell_area"] / mean_area
    # Calculate IPQ compactness using the standard formula: CI = 4πA/P²
    rhealpix_gdf["ipq"] = (
        4 * np.pi * rhealpix_gdf["cell_area"] / (rhealpix_gdf["cell_perimeter"] ** 2)
    )
    # Calculate zonal standardized compactness
    rhealpix_gdf["zsc"] = (
        np.sqrt(
            4 * np.pi * rhealpix_gdf["cell_area"]
            - np.power(rhealpix_gdf["cell_area"], 2) / np.power(6378137, 2)
        )
        / rhealpix_gdf["cell_perimeter"]
    )
    # Compute convex hull using Lambert Azimuthal Equal Area projection
    convex_hull = rhealpix_gdf["geometry"].apply(convexhull_from_lambert)
    # Calculate convex hull area using Lambert projection
    convex_hull_area = convex_hull.apply(
        lambda g: get_area_perimeter_from_lambert(g)[0] if g is not None else np.nan
    )
    # Calculate cell area using Lambert projection for consistent cvh calculation
    rhealpix_gdf_lambert = get_cells_area(rhealpix_gdf.copy(), "LAEA")
    # Compute CVH safely; set to NaN where convex hull area is non-positive or invalid
    rhealpix_gdf["cvh"] = np.where(
        (convex_hull_area > 0) & np.isfinite(convex_hull_area),
        rhealpix_gdf_lambert["area"] / convex_hull_area,
        np.nan,
    )
    # Replace any accidental inf values with NaN
    rhealpix_gdf["cvh"] = rhealpix_gdf["cvh"].replace([np.inf, -np.inf], np.nan)
    return rhealpix_gdf

rhealpixinspect_cli()

Command-line interface for rHEALPix cell inspection.

CLI options

-r, --resolution: rHEALPix resolution level (0-15) -fix, --fix_antimeridian: Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none (default: none)

Source code in vgrid/stats/rhealpixstats.py

def rhealpixinspect_cli():
    """
    Command-line interface for rHEALPix cell inspection.

    CLI options:
      -r, --resolution: rHEALPix resolution level (0-15)
      -fix, --fix_antimeridian: Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none (default: none)
    """
    parser = argparse.ArgumentParser(add_help=False)
    parser.add_argument("-r", "--resolution", dest="resolution", type=int, default=0)
    parser.add_argument(
        "-fix",
        "--fix_antimeridian",
        type=str,
        choices=[
            "shift",
            "shift_balanced",
            "shift_west",
            "shift_east",
            "split",
            "none",
        ],
        default=None,
        help="Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none (default: none)",
    )
    add_verbose_argument(parser)
    args = parser.parse_args()  # type: ignore
    resolution = args.resolution
    fix_antimeridian = args.fix_antimeridian
    print(rhealpixinspect(resolution, fix_antimeridian=fix_antimeridian, verbose=args.verbose))

rhealpixstats_cli()

Command-line interface for generating rHEALPix DGGS statistics.

CLI options

-unit, --unit {m,km}

Source code in vgrid/stats/rhealpixstats.py

def rhealpixstats_cli():
    """
    Command-line interface for generating rHEALPix DGGS statistics.

    CLI options:
      -unit, --unit {m,km}
    """
    parser = argparse.ArgumentParser(add_help=False)
    parser.add_argument(
        "-unit", "--unit", dest="unit", choices=["m", "km"], default="m"
    )
    args = parser.parse_args()  # type: ignore

    unit = args.unit

    # Get the DataFrame
    df = rhealpixstats(unit=unit)

    # Display the DataFrame
    print(df)

s2inspect(resolution, fix_antimeridian=None, verbose=True)

Generate comprehensive inspection data for S2 DGGS cells at a given resolution.

Parameters:

Name	Type	Description	Default
resolution	int	S2 resolution level (0-30)	required
verbose		Show progress bars. Defaults to True.	True

Source code in vgrid/stats/s2stats.py

def s2inspect(resolution: int, fix_antimeridian=None, verbose=True):
    """
    Generate comprehensive inspection data for S2 DGGS cells at a given resolution.

    Args:
        resolution: S2 resolution level (0-30)

        verbose: Show progress bars. Defaults to True.
    Returns:
        geopandas.GeoDataFrame: DataFrame containing S2 cell inspection data with columns:
            - s2: S2 cell ID
            - resolution: Resolution level
            - geometry: Cell geometry
            - cell_area: Cell area in square meters
            - cell_perimeter: Cell perimeter in meters
            - crossed: Whether cell crosses the dateline
            - norm_area: Normalized area (cell_area / mean_area)
            - ipq: Isoperimetric Quotient compactness
            - zsc: Zonal Standardized Compactness
    """
    s2_gdf = s2grid(resolution, output_format="gpd", fix_antimeridian=fix_antimeridian, verbose=verbose)
    s2_gdf["crossed"] = s2_gdf["geometry"].apply(check_crossing_geom)
    s2_gdf = s2_gdf[~s2_gdf["crossed"]]  # remove cells that cross the Antimeridian
    # mean_area = s2_gdf["cell_area"].mean()
    num_cells = 6 * (4**resolution)
    mean_area = AUTHALIC_AREA / num_cells
    # Calculate normalized area
    s2_gdf["norm_area"] = s2_gdf["cell_area"] / mean_area
    # Calculate IPQ compactness using the standard formula: CI = 4πA/P²
    s2_gdf["ipq"] = 4 * np.pi * s2_gdf["cell_area"] / (s2_gdf["cell_perimeter"] ** 2)
    # Calculate zonal standardized compactness
    s2_gdf["zsc"] = (
        np.sqrt(
            4 * np.pi * s2_gdf["cell_area"]
            - np.power(s2_gdf["cell_area"], 2) / np.power(6378137, 2)
        )
        / s2_gdf["cell_perimeter"]
    )
    # Compute convex hull using Lambert Azimuthal Equal Area projection
    convex_hull = s2_gdf["geometry"].apply(convexhull_from_lambert)
    # Calculate convex hull area using Lambert projection
    convex_hull_area = convex_hull.apply(
        lambda g: get_area_perimeter_from_lambert(g)[0] if g is not None else np.nan
    )
    # Calculate cell area using Lambert projection for consistent cvh calculation
    s2_gdf_lambert = get_cells_area(s2_gdf.copy(), "LAEA")
    # Compute CVH safely; set to NaN where convex hull area is non-positive or invalid
    s2_gdf["cvh"] = np.where(
        (convex_hull_area > 0) & np.isfinite(convex_hull_area),
        s2_gdf_lambert["area"] / convex_hull_area,
        np.nan,
    )
    # Replace any accidental inf values with NaN
    s2_gdf["cvh"] = s2_gdf["cvh"].replace([np.inf, -np.inf], np.nan)
    return s2_gdf

s2inspect_cli()

Command-line interface for S2 cell inspection. CLI options: -r, --resolution: S2 resolution level (0-30) -split, --split_antimeridian: Enable antimeridian splitting (default: enabled)

Source code in vgrid/stats/s2stats.py

def s2inspect_cli():
    """
    Command-line interface for S2 cell inspection.
    CLI options:
      -r, --resolution: S2 resolution level (0-30)
      -split, --split_antimeridian: Enable antimeridian splitting (default: enabled)
    """
    parser = argparse.ArgumentParser(add_help=False)
    parser.add_argument("-r", "--resolution", dest="resolution", type=int, default=0)
    parser.add_argument(
        "-fix",
        "--fix_antimeridian",
        type=str,
        choices=[
            "shift",
            "shift_balanced",
            "shift_west",
            "shift_east",
            "split",
            "none",
        ],
        default=None,
        help="Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none",
    )
    add_verbose_argument(parser)
    args = parser.parse_args()  # type: ignore
    resolution = args.resolution
    fix_antimeridian = args.fix_antimeridian
    print(s2inspect(resolution, fix_antimeridian=fix_antimeridian, verbose=args.verbose))

s2stats_cli()

Command-line interface for generating S2 DGGS statistics.

CLI options

-unit, --unit {m,km}

Source code in vgrid/stats/s2stats.py

def s2stats_cli():
    """
    Command-line interface for generating S2 DGGS statistics.

    CLI options:
      -unit, --unit {m,km}
    """
    parser = argparse.ArgumentParser(add_help=False)
    parser.add_argument(
        "-unit", "--unit", dest="unit", choices=["m", "km"], default="m"
    )
    args = parser.parse_args()  # type: ignore

    unit = args.unit

    # Get the DataFrame
    df = s2stats(unit=unit)

    # Display the DataFrame
    print(df)

tilecodeinspect(resolution, verbose=True)

Generate comprehensive inspection data for Tilecode DGGS cells at a given resolution.

This function creates a detailed analysis of Tilecode cells including area variations, compactness measures, and dateline crossing detection.

Parameters:

Name	Type	Description	Default
resolution	int	Tilecode resolution level (0-29)	required
verbose		Show progress bars. Defaults to True.	True

Source code in vgrid/stats/tilecodestats.py

def tilecodeinspect(resolution: int, verbose=True):
    """
    Generate comprehensive inspection data for Tilecode DGGS cells at a given resolution.

    This function creates a detailed analysis of Tilecode cells including area variations,
    compactness measures, and dateline crossing detection.

    Args:
        resolution: Tilecode resolution level (0-29)

        verbose: Show progress bars. Defaults to True.
    Returns:
        geopandas.GeoDataFrame: DataFrame containing Tilecode cell inspection data with columns:
            - tilecode: Tilecode cell ID
            - resolution: Resolution level
            - geometry: Cell geometry
            - cell_area: Cell area in square meters
            - cell_perimeter: Cell perimeter in meters
            - crossed: Whether cell crosses the dateline
            - norm_area: Normalized area (cell_area / mean_area)
            - ipq: Isoperimetric Quotient compactness
            - zsc: Zonal Standardized Compactness
    """
    tilecode_gdf = tilecodegrid(resolution, output_format="gpd", verbose=verbose)
    tilecode_gdf["crossed"] = tilecode_gdf["geometry"].apply(check_crossing_geom)
    # mean_area = tilecode_gdf["cell_area"].mean()
    num_cells = 4**resolution
    mean_area = AUTHALIC_AREA / num_cells
    # Calculate normalized area
    tilecode_gdf["norm_area"] = tilecode_gdf["cell_area"] / mean_area
    # Calculate IPQ compactness using the standard formula: CI = 4πA/P²
    tilecode_gdf["ipq"] = (
        4 * np.pi * tilecode_gdf["cell_area"] / (tilecode_gdf["cell_perimeter"] ** 2)
    )
    # Calculate zonal standardized compactness
    tilecode_gdf["zsc"] = (
        np.sqrt(
            4 * np.pi * tilecode_gdf["cell_area"]
            - np.power(tilecode_gdf["cell_area"], 2) / np.power(6378137, 2)
        )
        / tilecode_gdf["cell_perimeter"]
    )

    # Compute convex hull using Lambert Azimuthal Equal Area projection
    convex_hull = tilecode_gdf["geometry"].apply(convexhull_from_lambert)
    # Calculate convex hull area using Lambert projection
    convex_hull_area = convex_hull.apply(
        lambda g: get_area_perimeter_from_lambert(g)[0] if g is not None else np.nan
    )
    # Calculate cell area using Lambert projection for consistent cvh calculation
    tilecode_gdf_lambert = get_cells_area(tilecode_gdf.copy(), "LAEA")
    # Compute CVH safely; set to NaN where convex hull area is non-positive or invalid
    tilecode_gdf["cvh"] = np.where(
        (convex_hull_area > 0) & np.isfinite(convex_hull_area),
        tilecode_gdf_lambert["area"] / convex_hull_area,
        np.nan,
    )
    # Replace any accidental inf values with NaN
    tilecode_gdf["cvh"] = tilecode_gdf["cvh"].replace([np.inf, -np.inf], np.nan)

    return tilecode_gdf

tilecodeinspect_cli()

Command-line interface for Tilecode cell inspection.

CLI options

-r, --resolution: Tilecode resolution level (0-30)

Source code in vgrid/stats/tilecodestats.py

def tilecodeinspect_cli():
    """
    Command-line interface for Tilecode cell inspection.

    CLI options:
      -r, --resolution: Tilecode resolution level (0-30)
    """
    parser = argparse.ArgumentParser(add_help=False)
    parser.add_argument("-r", "--resolution", dest="resolution", type=int, default=0)
    add_verbose_argument(parser)
    args = parser.parse_args()
    resolution = args.resolution
    print(tilecodeinspect(resolution, verbose=args.verbose))

tilecodestats_cli()

Command-line interface for generating Tilecode DGGS statistics.

CLI options

-unit, --unit {m,km}

Source code in vgrid/stats/tilecodestats.py

def tilecodestats_cli():
    """
    Command-line interface for generating Tilecode DGGS statistics.

    CLI options:
      -unit, --unit {m,km}
    """
    parser = argparse.ArgumentParser(add_help=False)
    parser.add_argument(
        "-unit", "--unit", dest="unit", choices=["m", "km"], default="m"
    )
    args = parser.parse_known_args()  # type: ignore

    unit = args.unit

    # Get the DataFrame
    df = tilecodestats(unit=unit)

    # Display the DataFrame
    print(df)

This module provides functions for generating statistics for H3 DGGS cells.

h3stats(unit='m')

Generate comprehensive statistics for H3 DGGS cells.

This function combines basic H3 statistics (number of cells, edge lengths, areas) with area extrema analysis (min/max areas and ratios).

Parameters:

Name	Type	Description	Default
unit	str	'm' or 'km' for length; area will be 'm^2' or 'km^2'	'm'

Returns:

Type

Description

pandas.DataFrame: DataFrame containing comprehensive H3 DGGS statistics with columns: - resolution: Resolution level (0-15) - number_of_cells: Number of cells at each resolution - avg_edge_len_{unit}: Average edge length in the given unit - avg_area_{unit}2: Average cell area in the squared unit - min_area_{unit}2: Minimum pentagon area - max_area_{unit}2: Maximum hexagon area - max_min_ratio: Ratio of max hexagon area to min pentagon area

Source code in vgrid/stats/h3stats.py

def h3stats(unit: str = "m"):
    """
    Generate comprehensive statistics for H3 DGGS cells.

    This function combines basic H3 statistics (number of cells, edge lengths, areas)
    with area extrema analysis (min/max areas and ratios).

    Args:
        unit: 'm' or 'km' for length; area will be 'm^2' or 'km^2'

    Returns:
        pandas.DataFrame: DataFrame containing comprehensive H3 DGGS statistics with columns:
            - resolution: Resolution level (0-15)
            - number_of_cells: Number of cells at each resolution
            - avg_edge_len_{unit}: Average edge length in the given unit
            - avg_area_{unit}2: Average cell area in the squared unit
            - min_area_{unit}2: Minimum pentagon area
            - max_area_{unit}2: Maximum hexagon area
            - max_min_ratio: Ratio of max hexagon area to min pentagon area
    """
    # normalize and validate unit
    unit = unit.strip().lower()
    if unit not in {"m", "km"}:
        raise ValueError("unit must be one of {'m','km'}")

    # Initialize lists to store data
    resolutions = []
    num_cells_list = []
    avg_edge_lens = []
    avg_areas = []
    min_areas = []
    max_areas = []
    max_min_ratios = []
    cls_list = []
    for res in range(min_res, max_res + 1):
        # Get comprehensive metrics
        metrics_data = h3_metrics(res, unit=unit)  # length unit is km, area unit is km2

        resolutions.append(res)
        num_cells_list.append(metrics_data["number_of_cells"])
        avg_edge_lens.append(metrics_data["avg_edge_len"])
        avg_areas.append(metrics_data["avg_area"])
        min_areas.append(metrics_data["min_area"])
        max_areas.append(metrics_data["max_area"])
        max_min_ratios.append(metrics_data["max_min_ratio"])
        cls_list.append(metrics_data["cls"])
    # Create DataFrame
    # Build column labels with unit awareness (lower case)
    avg_edge_len = f"avg_edge_len_{unit}"
    avg_area = f"avg_area_{unit}"
    min_area = f"min_area_{unit}"
    max_area = f"max_area_{unit}"
    cls_label = f"cls_{unit}"
    df = pd.DataFrame(
        {
            "resolution": resolutions,
            "number_of_cells": num_cells_list,
            avg_edge_len: avg_edge_lens,
            avg_area: avg_areas,
            min_area: min_areas,
            max_area: max_areas,
            "max_min_ratio": max_min_ratios,
            cls_label: cls_list,
        }
    )

    return df

h3inspect(resolution, fix_antimeridian=None, verbose=True)

Generate comprehensive inspection data for H3 DGGS cells at a given resolution.

This function creates a detailed analysis of H3 cells including area variations, compactness measures, and Antimeridian crossing detection.

Parameters:

Name	Type	Description	Default
resolution	int	H3 resolution level (0-15)	required
fix_antimeridian	None	Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none	None
verbose		Show progress bars. Defaults to True.	True

Source code in vgrid/stats/h3stats.py

def h3inspect(resolution: int, fix_antimeridian: None = None, verbose=True):
    """
    Generate comprehensive inspection data for H3 DGGS cells at a given resolution.

    This function creates a detailed analysis of H3 cells including area variations,
    compactness measures, and Antimeridian crossing detection.

    Args:
        resolution: H3 resolution level (0-15)
        fix_antimeridian: Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none

        verbose: Show progress bars. Defaults to True.
    Returns:
        geopandas.GeoDataFrame: DataFrame containing H3 cell inspection data with columns:
            - h3: H3 cell ID
            - resolution: Resolution level
            - geometry: Cell geometry
            - cell_area: Cell area in square meters
            - cell_perimeter: Cell perimeter in meters
            - crossed: Whether cell crosses the Antimeridian
            - is_pentagon: Whether cell is a pentagon
            - norm_area: Normalized area (cell_area / mean_area)
            - ipq: Isoperimetric Quotient compactness
            - zsc: Zonal Standardized Compactness
    """
    h3_gdf = h3grid(resolution, output_format="gpd", fix_antimeridian=fix_antimeridian, verbose=verbose)
    h3_gdf["crossed"] = h3_gdf["geometry"].apply(check_crossing_geom)
    h3_gdf = h3_gdf[~h3_gdf["crossed"]]  # remove cells that cross the Antimeridian
    h3_gdf["is_pentagon"] = h3_gdf["h3"].apply(h3.is_pentagon)
    # mean_area = h3_gdf["cell_area"].mean()
    mean_area = AUTHALIC_AREA / h3.get_num_cells(resolution)
    # Calculate normalized area
    h3_gdf["norm_area"] = h3_gdf["cell_area"] / mean_area
    # Calculate IPQ compactness using the standard formula: CI = 4πA/P²
    h3_gdf["ipq"] = 4 * np.pi * h3_gdf["cell_area"] / (h3_gdf["cell_perimeter"] ** 2)
    # Calculate zonal standardized compactness
    h3_gdf["zsc"] = (
        np.sqrt(
            4 * np.pi * h3_gdf["cell_area"]
            - np.power(h3_gdf["cell_area"], 2) / np.power(6378137, 2)
        )
        / h3_gdf["cell_perimeter"]
    )

    # Compute convex hull using Lambert Azimuthal Equal Area projection
    convex_hull = h3_gdf["geometry"].apply(convexhull_from_lambert)
    # Calculate convex hull area using Lambert projection
    convex_hull_area = convex_hull.apply(
        lambda g: get_area_perimeter_from_lambert(g)[0] if g is not None else np.nan
    )
    # Calculate cell area using Lambert projection for consistent cvh calculation
    h3_gdf_lambert = get_cells_area(h3_gdf.copy(), "LAEA")
    # Compute CVH safely; set to NaN where convex hull area is non-positive or invalid
    h3_gdf["cvh"] = np.where(
        (convex_hull_area > 0) & np.isfinite(convex_hull_area),
        h3_gdf_lambert["area"] / convex_hull_area,
        np.nan,
    )
    # Replace any accidental inf values with NaN
    h3_gdf["cvh"] = h3_gdf["cvh"].replace([np.inf, -np.inf], np.nan)
    return h3_gdf

This module provides functions for generating statistics for S2 DGGS cells.

s2stats(unit='m')

Generate statistics for S2 DGGS cells.

Parameters:

Name	Type	Description	Default
unit	str	'm' or 'km' for length; area will be 'm^2' or 'km^2'	'm'

Returns:

Type	Description
	pandas.DataFrame: DataFrame containing S2 DGGS statistics with columns: - Resolution: Resolution level (0-30) - Number_of_Cells: Number of cells at each resolution - Avg_Edge_Length_{unit}: Average edge length in the given unit - Avg_Cell_Area_{unit}2: Average cell area in the squared unit

Source code in vgrid/stats/s2stats.py

def s2stats(unit: str = "m"):  # length unit is km, area unit is km2
    """
    Generate statistics for S2 DGGS cells.

    Args:
        unit: 'm' or 'km' for length; area will be 'm^2' or 'km^2'

    Returns:
        pandas.DataFrame: DataFrame containing S2 DGGS statistics with columns:
            - Resolution: Resolution level (0-30)
            - Number_of_Cells: Number of cells at each resolution
            - Avg_Edge_Length_{unit}: Average edge length in the given unit
            - Avg_Cell_Area_{unit}2: Average cell area in the squared unit
    """
    # normalize and validate unit
    unit = unit.strip().lower()
    if unit not in {"m", "km"}:
        raise ValueError("unit must be one of {'m','km'}")

    # Initialize lists to store data
    resolutions = []
    num_cells_list = []
    avg_edge_lens = []
    avg_cell_areas = []
    cls_list = []
    for res in range(min_res, max_res + 1):
        num_cells, avg_edge_len, avg_cell_area, cls = s2_metrics(
            res, unit=unit
        )  # length unit is km, area unit is km2
        resolutions.append(res)
        num_cells_list.append(num_cells)
        avg_edge_lens.append(avg_edge_len)
        avg_cell_areas.append(avg_cell_area)
        cls_list.append(cls)
    # Create DataFrame
    # Build column labels with unit awareness
    avg_edge_len = f"avg_edge_len_{unit}"
    unit_area_label = {"m": "m2", "km": "km2"}[unit]
    avg_cell_area = f"avg_cell_area_{unit_area_label}"
    cls_label = f"cls_{unit}"
    df = pd.DataFrame(
        {
            "resolution": resolutions,
            "number_of_cells": num_cells_list,
            avg_edge_len: avg_edge_lens,
            avg_cell_area: avg_cell_areas,
            cls_label: cls_list,
        }
    )

    return df

s2inspect(resolution, fix_antimeridian=None, verbose=True)

Generate comprehensive inspection data for S2 DGGS cells at a given resolution.

Parameters:

Name	Type	Description	Default
resolution	int	S2 resolution level (0-30)	required
verbose		Show progress bars. Defaults to True.	True

Source code in vgrid/stats/s2stats.py

def s2inspect(resolution: int, fix_antimeridian=None, verbose=True):
    """
    Generate comprehensive inspection data for S2 DGGS cells at a given resolution.

    Args:
        resolution: S2 resolution level (0-30)

        verbose: Show progress bars. Defaults to True.
    Returns:
        geopandas.GeoDataFrame: DataFrame containing S2 cell inspection data with columns:
            - s2: S2 cell ID
            - resolution: Resolution level
            - geometry: Cell geometry
            - cell_area: Cell area in square meters
            - cell_perimeter: Cell perimeter in meters
            - crossed: Whether cell crosses the dateline
            - norm_area: Normalized area (cell_area / mean_area)
            - ipq: Isoperimetric Quotient compactness
            - zsc: Zonal Standardized Compactness
    """
    s2_gdf = s2grid(resolution, output_format="gpd", fix_antimeridian=fix_antimeridian, verbose=verbose)
    s2_gdf["crossed"] = s2_gdf["geometry"].apply(check_crossing_geom)
    s2_gdf = s2_gdf[~s2_gdf["crossed"]]  # remove cells that cross the Antimeridian
    # mean_area = s2_gdf["cell_area"].mean()
    num_cells = 6 * (4**resolution)
    mean_area = AUTHALIC_AREA / num_cells
    # Calculate normalized area
    s2_gdf["norm_area"] = s2_gdf["cell_area"] / mean_area
    # Calculate IPQ compactness using the standard formula: CI = 4πA/P²
    s2_gdf["ipq"] = 4 * np.pi * s2_gdf["cell_area"] / (s2_gdf["cell_perimeter"] ** 2)
    # Calculate zonal standardized compactness
    s2_gdf["zsc"] = (
        np.sqrt(
            4 * np.pi * s2_gdf["cell_area"]
            - np.power(s2_gdf["cell_area"], 2) / np.power(6378137, 2)
        )
        / s2_gdf["cell_perimeter"]
    )
    # Compute convex hull using Lambert Azimuthal Equal Area projection
    convex_hull = s2_gdf["geometry"].apply(convexhull_from_lambert)
    # Calculate convex hull area using Lambert projection
    convex_hull_area = convex_hull.apply(
        lambda g: get_area_perimeter_from_lambert(g)[0] if g is not None else np.nan
    )
    # Calculate cell area using Lambert projection for consistent cvh calculation
    s2_gdf_lambert = get_cells_area(s2_gdf.copy(), "LAEA")
    # Compute CVH safely; set to NaN where convex hull area is non-positive or invalid
    s2_gdf["cvh"] = np.where(
        (convex_hull_area > 0) & np.isfinite(convex_hull_area),
        s2_gdf_lambert["area"] / convex_hull_area,
        np.nan,
    )
    # Replace any accidental inf values with NaN
    s2_gdf["cvh"] = s2_gdf["cvh"].replace([np.inf, -np.inf], np.nan)
    return s2_gdf

This module provides functions for generating statistics for A5 DGGS cells.

a5stats(unit='m')

Generate statistics for A5 DGGS cells.

Parameters:

Name	Type	Description	Default
unit	str	'm' or 'km' for length; area will be 'm^2' or 'km^2'	'm'

Returns:

Type	Description
	pandas.DataFrame: DataFrame containing A5 DGGS statistics with columns: - Resolution: Resolution level (0-29) - Number_of_Cells: Number of cells at each resolution - Avg_Edge_Length_{unit}: Average edge length in the given unit - CLS: Characteristic length scale in the given unit - Avg_Cell_Area_{unit}2: Average cell area in the squared unit

Source code in vgrid/stats/a5stats.py

def a5stats(unit: str = "m"):
    """
    Generate statistics for A5 DGGS cells.

    Args:
        unit: 'm' or 'km' for length; area will be 'm^2' or 'km^2'

    Returns:
        pandas.DataFrame: DataFrame containing A5 DGGS statistics with columns:
            - Resolution: Resolution level (0-29)
            - Number_of_Cells: Number of cells at each resolution
            - Avg_Edge_Length_{unit}: Average edge length in the given unit
            - CLS: Characteristic length scale in the given unit
            - Avg_Cell_Area_{unit}2: Average cell area in the squared unit
    """
    # normalize and validate unit
    unit = unit.strip().lower()
    if unit not in {"m", "km"}:
        raise ValueError("unit must be one of {'m','km'}")

    # Derive bounds from central constants registry

    # Initialize lists to store data
    resolutions = []
    num_cells_list = []
    avg_edge_lens = []
    avg_cell_areas = []
    cls_list = []
    for res in range(min_res, max_res + 1):
        num_cells, avg_edge_len, avg_cell_area, cls = a5_metrics(
            res, unit=unit
        )  # length unit is m, area unit is m2
        resolutions.append(res)
        num_cells_list.append(num_cells)
        avg_edge_lens.append(avg_edge_len)
        avg_cell_areas.append(avg_cell_area)
        cls_list.append(cls)

    # Create DataFrame
    # Build column labels with unit awareness
    avg_edge_len = f"avg_edge_len_{unit}"
    unit_area_label = {"m": "m2", "km": "km2"}[unit]
    cls_label = f"cls_{unit}"
    avg_cell_area = f"avg_cell_area_{unit_area_label}"

    df = pd.DataFrame(
        {
            "resolution": resolutions,
            "number_of_cells": num_cells_list,
            avg_edge_len: avg_edge_lens,
            avg_cell_area: avg_cell_areas,
            cls_label: cls_list,
        },
        index=None,
    )

    return df

a5inspect(resolution, options={'segments': 100}, split_antimeridian=False, verbose=True)

Generate comprehensive inspection data for A5 DGGS cells at a given resolution.

This function creates a detailed analysis of A5 cells including area variations, compactness measures, and Antimeridian crossing detection.

Parameters:

Name	Type	Description	Default
resolution	int	A5 resolution level (0-29)	required
options		Optional dictionary of options for grid generation	{'segments': 100}
split_antimeridian	bool	When True, apply antimeridian splitting to the resulting polygons. Defaults to False when None or omitted.	False
verbose		Show progress bars. Defaults to True.	True

Returns:

Type

Description

geopandas.GeoDataFrame: DataFrame containing A5 cell inspection data with columns: - a5: A5 cell ID - resolution: Resolution level - geometry: Cell geometry - cell_area: Cell area in square meters - cell_perimeter: Cell perimeter in meters - crossed: Whether cell crosses the Antimeridian - norm_area: Normalized area (cell_area / mean_area) - ipq: Isoperimetric Quotient compactness - zsc: Zonal Standardized Compactness

Source code in vgrid/stats/a5stats.py

def a5inspect(
    resolution: int,
    options={"segments": 100},
    split_antimeridian: bool = False,
    verbose=True,
):
    """
    Generate comprehensive inspection data for A5 DGGS cells at a given resolution.

    This function creates a detailed analysis of A5 cells including area variations,
    compactness measures, and Antimeridian crossing detection.

    Args:
        resolution: A5 resolution level (0-29)
        options: Optional dictionary of options for grid generation
        split_antimeridian: When True, apply antimeridian splitting to the resulting polygons.
            Defaults to False when None or omitted.
        verbose: Show progress bars. Defaults to True.

    Returns:
        geopandas.GeoDataFrame: DataFrame containing A5 cell inspection data with columns:
            - a5: A5 cell ID
            - resolution: Resolution level
            - geometry: Cell geometry
            - cell_area: Cell area in square meters
            - cell_perimeter: Cell perimeter in meters
            - crossed: Whether cell crosses the Antimeridian
            - norm_area: Normalized area (cell_area / mean_area)
            - ipq: Isoperimetric Quotient compactness
            - zsc: Zonal Standardized Compactness
    """
    a5_gdf = a5grid(
        resolution,
        output_format="gpd",
        options=options,
        split_antimeridian=split_antimeridian,
        verbose=verbose,
    )
    a5_gdf["crossed"] = a5_gdf["geometry"].apply(check_crossing_geom)
    a5_gdf = a5_gdf[~a5_gdf["crossed"]]  # remove cells that cross the Antimeridian

    # mean_area = a5_gdf["cell_area"].mean()
    mean_area = AUTHALIC_AREA / get_num_cells(resolution)

    # Calculate normalized area
    a5_gdf["norm_area"] = a5_gdf["cell_area"] / mean_area
    # Calculate IPQ compactness using the standard formula: CI = 4πA/P²
    a5_gdf["ipq"] = 4 * np.pi * a5_gdf["cell_area"] / (a5_gdf["cell_perimeter"] ** 2)
    # Calculate zonal standardized compactness
    a5_gdf["zsc"] = (
        np.sqrt(
            4 * np.pi * a5_gdf["cell_area"]
            - np.power(a5_gdf["cell_area"], 2) / np.power(6378137, 2)
        )
        / a5_gdf["cell_perimeter"]
    )

    # Compute convex hull using Lambert Azimuthal Equal Area projection
    convex_hull = a5_gdf["geometry"].apply(convexhull_from_lambert)
    # Calculate convex hull area using Lambert projection
    convex_hull_area = convex_hull.apply(
        lambda g: get_area_perimeter_from_lambert(g)[0] if g is not None else np.nan
    )
    # Calculate cell area using Lambert projection for consistent cvh calculation
    a5_gdf_lambert = get_cells_area(a5_gdf.copy(), "LAEA")
    # Compute CVH safely; set to NaN where convex hull area is non-positive or invalid
    a5_gdf["cvh"] = np.where(
        (convex_hull_area > 0) & np.isfinite(convex_hull_area),
        a5_gdf_lambert["area"] / convex_hull_area,
        np.nan,
    )
    # Replace any accidental inf values with NaN
    a5_gdf["cvh"] = a5_gdf["cvh"].replace([np.inf, -np.inf], np.nan)
    return a5_gdf

This module provides functions for generating statistics for rHEALPix DGGS cells.

rhealpixstats(unit='m')

Generate statistics for rHEALPix DGGS cells.

Parameters:

Name	Type	Description	Default
unit	str	'm' or 'km' for length; area will be 'm^2' or 'km^2'	'm'

Returns:

Type	Description
	pandas.DataFrame: DataFrame containing rHEALPix DGGS statistics with columns: - Resolution: Resolution level (0-30) - Number_of_Cells: Number of cells at each resolution - Avg_Edge_Length_{unit}: Average edge length in the given unit - Avg_Cell_Area_{unit}2: Average cell area in the squared unit

Source code in vgrid/stats/rhealpixstats.py

def rhealpixstats(unit: str = "m"):
    """
    Generate statistics for rHEALPix DGGS cells.

    Args:
        unit: 'm' or 'km' for length; area will be 'm^2' or 'km^2'

    Returns:
        pandas.DataFrame: DataFrame containing rHEALPix DGGS statistics with columns:
            - Resolution: Resolution level (0-30)
            - Number_of_Cells: Number of cells at each resolution
            - Avg_Edge_Length_{unit}: Average edge length in the given unit
            - Avg_Cell_Area_{unit}2: Average cell area in the squared unit
    """
    # normalize and validate unit
    unit = unit.strip().lower()
    if unit not in {"m", "km"}:
        raise ValueError("unit must be one of {'m','km'}")

    # Initialize lists to store data
    resolutions = []
    num_cells_list = []
    avg_edge_lens = []
    avg_cell_areas = []
    cls_list = []
    for res in range(min_res, max_res + 1):
        num_cells, avg_edge_len, avg_cell_area, cls = rhealpix_metrics(
            res, unit=unit
        )  # length unit is km, area unit is km2
        resolutions.append(res)
        num_cells_list.append(num_cells)
        avg_edge_lens.append(avg_edge_len)
        avg_cell_areas.append(avg_cell_area)
        cls_list.append(cls)
    # Create DataFrame
    # Build column labels with unit awareness
    avg_edge_len = f"avg_edge_len_{unit}"
    unit_area_label = {"m": "m2", "km": "km2"}[unit]
    avg_cell_area = f"avg_cell_area_{unit_area_label}"
    cls_label = f"cls_{unit}"
    df = pd.DataFrame(
        {
            "resolution": resolutions,
            "number_of_cells": num_cells_list,
            avg_edge_len: avg_edge_lens,
            avg_cell_area: avg_cell_areas,
            cls_label: cls_list,
        }
    )

    return df

rhealpixinspect(resolution=0, fix_antimeridian=None, verbose=True)

Generate comprehensive inspection data for rHEALPix DGGS cells at a given resolution.

This function creates a detailed analysis of rHEALPix cells including area variations, compactness measures, and dateline crossing detection.

Parameters:

Name	Type	Description	Default
resolution	int	rHEALPix resolution level (0-15)	0
fix_antimeridian	str	Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none	None
verbose		Show progress bars. Defaults to True.	True

Source code in vgrid/stats/rhealpixstats.py

def rhealpixinspect(resolution: int = 0, fix_antimeridian: str = None, verbose=True):
    """
    Generate comprehensive inspection data for rHEALPix DGGS cells at a given resolution.

    This function creates a detailed analysis of rHEALPix cells including area variations,
    compactness measures, and dateline crossing detection.

    Args:
        resolution: rHEALPix resolution level (0-15)
        fix_antimeridian: Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none
        Defaults to False to avoid splitting the Antimeridian by default.
        verbose: Show progress bars. Defaults to True.
    Returns:
        geopandas.GeoDataFrame: DataFrame containing rHEALPix cell inspection data with columns:
            - rhealpix: rHEALPix cell ID
            - resolution: Resolution level
            - geometry: Cell geometry
            - cell_area: Cell area in square meters
            - cell_perimeter: Cell perimeter in meters
            - crossed: Whether cell crosses the dateline
            - norm_area: Normalized area (cell_area / mean_area)
            - ipq: Isoperimetric Quotient compactness
            - zsc: Zonal Standardized Compactness
            - cvh: Convex Hull Compactness
    """
    rhealpix_gdf = rhealpixgrid(
        resolution, output_format="gpd", fix_antimeridian=fix_antimeridian, verbose=verbose
    )  # type: ignore
    rhealpix_gdf["crossed"] = rhealpix_gdf["geometry"].apply(check_crossing_geom)
    rhealpix_gdf = rhealpix_gdf[
        ~rhealpix_gdf["crossed"]
    ]  # remove cells that cross the Antimeridian
    # mean_area = rhealpix_gdf["cell_area"].mean()
    num_cells = 6 * 9 ** (resolution)
    mean_area = AUTHALIC_AREA / num_cells
    # Calculate normalized area
    rhealpix_gdf["norm_area"] = rhealpix_gdf["cell_area"] / mean_area
    # Calculate IPQ compactness using the standard formula: CI = 4πA/P²
    rhealpix_gdf["ipq"] = (
        4 * np.pi * rhealpix_gdf["cell_area"] / (rhealpix_gdf["cell_perimeter"] ** 2)
    )
    # Calculate zonal standardized compactness
    rhealpix_gdf["zsc"] = (
        np.sqrt(
            4 * np.pi * rhealpix_gdf["cell_area"]
            - np.power(rhealpix_gdf["cell_area"], 2) / np.power(6378137, 2)
        )
        / rhealpix_gdf["cell_perimeter"]
    )
    # Compute convex hull using Lambert Azimuthal Equal Area projection
    convex_hull = rhealpix_gdf["geometry"].apply(convexhull_from_lambert)
    # Calculate convex hull area using Lambert projection
    convex_hull_area = convex_hull.apply(
        lambda g: get_area_perimeter_from_lambert(g)[0] if g is not None else np.nan
    )
    # Calculate cell area using Lambert projection for consistent cvh calculation
    rhealpix_gdf_lambert = get_cells_area(rhealpix_gdf.copy(), "LAEA")
    # Compute CVH safely; set to NaN where convex hull area is non-positive or invalid
    rhealpix_gdf["cvh"] = np.where(
        (convex_hull_area > 0) & np.isfinite(convex_hull_area),
        rhealpix_gdf_lambert["area"] / convex_hull_area,
        np.nan,
    )
    # Replace any accidental inf values with NaN
    rhealpix_gdf["cvh"] = rhealpix_gdf["cvh"].replace([np.inf, -np.inf], np.nan)
    return rhealpix_gdf

This module provides lightweight wrappers for DGGAL using the external dgg CLI directly.

Per request, dggalstats simply returns the direct output from dgg <dggs_type> level without computing any additional metrics.

dggalstats(dggs_type, unit='m')

Compute and return a DataFrame of DGGAL metrics per resolution for the given type.

Parameters:

Name	Type	Description	Default
dggs_type	str	DGGS type supported by DGGAL (see vgrid.utils.constants.DGGAL_TYPES)	required
unit	str	'm' or 'km' for length; area columns will reflect the squared unit	'm'

Returns:

Type	Description
DataFrame | None	pandas DataFrame with columns for resolution, number of cells, average edge length,
DataFrame | None	and average cell area in the requested units.

Source code in vgrid/stats/dggalstats.py

def dggalstats(
    dggs_type: str, unit: str = "m"
) -> pd.DataFrame | None:  # length unit is km, area unit is km2
    """
    Compute and return a DataFrame of DGGAL metrics per resolution for the given type.

    Args:
            dggs_type: DGGS type supported by DGGAL (see vgrid.utils.constants.DGGAL_TYPES)
            unit: 'm' or 'km' for length; area columns will reflect the squared unit

    Returns:
            pandas DataFrame with columns for resolution, number of cells, average edge length,
            and average cell area in the requested units.
    """
    dggs_type = validate_dggal_type(dggs_type)
    min_res = int(DGGAL_TYPES[dggs_type]["min_res"])
    max_res = int(DGGAL_TYPES[dggs_type]["max_res"])

    # Initialize lists to store data
    resolutions = []
    num_cells_list = []
    avg_edge_lens = []
    avg_cell_areas = []
    cls_list = []
    for res in range(min_res, max_res + 1):
        num_cells, avg_edge_len, avg_cell_area, cls = dggal_metrics(
            dggs_type, res, unit=unit
        )  # length unit is km, area unit is km2
        resolutions.append(res)
        num_cells_list.append(num_cells)
        avg_edge_lens.append(avg_edge_len)
        avg_cell_areas.append(avg_cell_area)
        cls_list.append(cls)
    # Build column labels with unit awareness
    avg_edge_len_col = f"avg_edge_len_{unit}"
    unit_area_label = {"m": "m2", "km": "km2"}[unit]
    avg_cell_area_col = f"avg_cell_area_{unit_area_label}"
    cls_label = f"cls_{unit}"
    df = pd.DataFrame(
        {
            "resolution": resolutions,
            "number_of_cells": num_cells_list,
            avg_edge_len_col: avg_edge_lens,
            avg_cell_area_col: avg_cell_areas,
            cls_label: cls_list,
        }
    )

    return df

dggalinspect(dggs_type, resolution, split_antimeridian=False, verbose=True)

Generate detailed inspection data for a DGGAL DGGS type at a given resolution.

Parameters:

Name	Type	Description	Default
dggs_type	str	DGGS type supported by DGGAL	required
resolution	int	Resolution level	required
split_antimeridian	bool	When True, apply antimeridian splitting to the resulting polygons. Defaults to True when None or omitted.	False
verbose		Show progress bars. Defaults to True.	True

Returns:

Type	Description
GeoDataFrame	geopandas.GeoDataFrame with columns: - ZoneID (as provided by DGGAL output; no renaming is performed) - resolution - geometry - cell_area (m^2) - cell_perimeter (m) - crossed (bool) - norm_area (area/mean_area) - ipq (4πA/P²) - zsc (sqrt(4πA - A²/R²)/P), with R=WGS84 a

Source code in vgrid/stats/dggalstats.py

def dggalinspect(
    dggs_type: str, resolution: int, split_antimeridian: bool = False, verbose=True
) -> gpd.GeoDataFrame:
    """
    Generate detailed inspection data for a DGGAL DGGS type at a given resolution.

    Args:
        dggs_type: DGGS type supported by DGGAL
        resolution: Resolution level
        split_antimeridian: When True, apply antimeridian splitting to the resulting polygons.
            Defaults to True when None or omitted.
        verbose: Show progress bars. Defaults to True.

    Returns:
        geopandas.GeoDataFrame with columns:
          - ZoneID (as provided by DGGAL output; no renaming is performed)
          - resolution
          - geometry
          - cell_area (m^2)
          - cell_perimeter (m)
          - crossed (bool)
          - norm_area (area/mean_area)
          - ipq (4πA/P²)
          - zsc (sqrt(4πA - A²/R²)/P), with R=WGS84 a
    """
    dggal_gdf = dggalgen(
        dggs_type,
        resolution,
        output_format="gpd",
        split_antimeridian=split_antimeridian,
        verbose=verbose,
    )

    # Determine whether current CRS is geographic; compute metrics accordingly
    if dggal_gdf.crs.is_geographic:
        def _geod_area_perimeter(g):
            cell_area_perimeter = geod.geometry_area_perimeter(g)
            return pd.Series(
                {
                    "cell_area": abs(cell_area_perimeter[0]),
                    "cell_perimeter": abs(cell_area_perimeter[1]),
                }
            )

        metrics = dggal_gdf.geometry.apply(_geod_area_perimeter)
        dggal_gdf["cell_area"] = metrics["cell_area"]
        dggal_gdf["cell_perimeter"] = metrics["cell_perimeter"]
        dggal_gdf["crossed"] = dggal_gdf.geometry.apply(check_crossing_geom)
    else:
        dggal_gdf["cell_area"] = dggal_gdf.geometry.area
        dggal_gdf["cell_perimeter"] = dggal_gdf.geometry.length
        dggal_gdf["crossed"] = False

    dggal_gdf = dggal_gdf[
        ~dggal_gdf["crossed"]
    ]  # remove cells that cross the Antimeridian
    # mean_area = dggal_gdf["cell_area"].mean()
    num_cells, _, _, _ = dggal_metrics(dggs_type, resolution)
    mean_area = AUTHALIC_AREA / num_cells

    dggal_gdf["norm_area"] = (
        dggal_gdf["cell_area"] / mean_area if mean_area and mean_area != 0 else np.nan
    )
    # Robust formulas avoiding division by zero
    dggal_gdf["ipq"] = (
        4 * np.pi * dggal_gdf["cell_area"] / (dggal_gdf["cell_perimeter"] ** 2)
    )

    dggal_gdf["zsc"] = (
        np.sqrt(
            4 * np.pi * dggal_gdf["cell_area"]
            - np.power(dggal_gdf["cell_area"], 2) / np.power(6378137, 2)
        )
        / dggal_gdf["cell_perimeter"]
    )

    # Compute convex hull using Lambert Azimuthal Equal Area projection
    convex_hull = dggal_gdf["geometry"].apply(convexhull_from_lambert)
    # Calculate convex hull area using Lambert projection
    convex_hull_area = convex_hull.apply(
        lambda g: get_area_perimeter_from_lambert(g)[0] if g is not None else np.nan
    )
    # Calculate cell area using Lambert projection for consistent cvh calculation
    dggal_gdf_lambert = get_cells_area(dggal_gdf.copy(), "LAEA")
    # Compute CVH safely; set to NaN where convex hull area is non-positive or invalid
    dggal_gdf["cvh"] = np.where(
        (convex_hull_area > 0) & np.isfinite(convex_hull_area),
        dggal_gdf_lambert["area"] / convex_hull_area,
        np.nan,
    )
    # Replace any accidental inf values with NaN
    dggal_gdf["cvh"] = dggal_gdf["cvh"].replace([np.inf, -np.inf], np.nan)
    return dggal_gdf

DGGRID Statistics Module

This module provides functions to calculate and display statistics for DGGRID Discrete Global Grid System (DGGS) types. It supports both command-line interface and direct function calls.

Key Functions: - dggrid_stats: Calculate and display statistics for a given DGGRID DGGS type and resolution - dggridinspect: Generate detailed inspection data for a given DGGRID DGGS type and resolution - main: Command-line interface for dggrid_stats

dggridstats(dggrid_instance, dggs_type, unit='m')

length unit is m, area unit is m2 Return a DataFrame of DGGRID stats per resolution.

'km' or 'm' for length columns; area is squared unit.

DGGRID native output is km^2 for area and km for CLS.

Columns include avg_edge_len_{unit}, derived from mean cell area and topology (hex vs quad).

Source code in vgrid/stats/dggridstats.py

def dggridstats(
    dggrid_instance, dggs_type: str, unit: str = "m"
) -> pd.DataFrame:  # length unit is km, area unit is km2
    """length unit is m, area unit is m2
    Return a DataFrame of DGGRID stats per resolution.

    unit: 'km' or 'm' for length columns; area is squared unit.
          DGGRID native output is km^2 for area and km for CLS.

    Columns include ``avg_edge_len_{unit}``, derived from mean cell area
    and topology (hex vs quad).
    """
    dggs_type = validate_dggrid_type(dggs_type)
    unit_norm = unit.strip().lower()

    if unit_norm not in {"m", "km"}:
        raise ValueError("unit must be one of {'m','km'}")

    max_res = int(DGGRID_TYPES[dggs_type]["max_res"])

    dggrid_stats_table = dggrid_instance.grid_stats_table(dggs_type, max_res)
    # Characteristic Length Scale (CLS): the diameter of a spherical cap of the same area as a cell of the specified res
    if isinstance(dggrid_stats_table, pd.DataFrame):
        rename_map = {
            "Resolution": "resolution",
            "Cells": "number_of_cells",
            "Area (km^2)": "area_km2",
            "CLS (km)": "cls_km",
        }
        dggrid_stats = dggrid_stats_table.rename(columns=rename_map).copy()
    else:
        dggrid_stats = pd.DataFrame(
            dggrid_stats_table,
            columns=["resolution", "number_of_cells", "area_km2", "cls_km"],
        )

    if unit_norm == "m":
        dggrid_stats = dggrid_stats.rename(
            columns={"area_km2": "area_m2", "cls_km": "cls_m"}
        )
        dggrid_stats["area_m2"] = dggrid_stats["area_m2"] * (10**6)
        dggrid_stats["cls_m"] = dggrid_stats["cls_m"] * (10**3)

    area_col = "area_m2" if unit_norm == "m" else "area_km2"
    avg_edge_len_col = f"avg_edge_len_{unit_norm}"
    areas = dggrid_stats[area_col]
    if dggrid_num_edges(dggs_type) == 6:
        dggrid_stats[avg_edge_len_col] = np.sqrt((2 * areas) / (3 * math.sqrt(3)))
    else:
        dggrid_stats[avg_edge_len_col] = np.sqrt(areas)

    if unit_norm == "m":
        col_order = [
            "resolution",
            "number_of_cells",
            avg_edge_len_col,
            "area_m2",
            "cls_m",
        ]
    else:
        col_order = [
            "resolution",
            "number_of_cells",
            avg_edge_len_col,
            "area_km2",
            "cls_km",
        ]
    return dggrid_stats[col_order]

dggridinspect(dggrid_instance, dggs_type, resolution, split_antimeridian=False, aggregate=False, options={'densification': 30}, verbose=True)

Generate detailed inspection data for a DGGRID DGGS type at a given resolution.

Parameters:

Name	Type	Description	Default
dggrid_instance		DGGRID instance for grid operations	required
dggs_type	str	DGGS type supported by DGGRID (see dggs_types)	required
resolution	int	Resolution level	required
split_antimeridian	bool	When True, apply antimeridian fixing to the resulting polygons.	False
aggregate	bool	When True, aggregate the resulting polygons. Defaults to False to avoid aggregation by default.	False
options	dict	Options to pass to grid_cell_polygons_for_extent. For example: {"densification": 2} to add densification points. Defaults to None.	{'densification': 30}
verbose		Show progress bars. Defaults to True.	True

Source code in vgrid/stats/dggridstats.py

def dggridinspect(
    dggrid_instance,
    dggs_type: str,
    resolution: int,
    split_antimeridian: bool = False,
    aggregate: bool = False,
    options={"densification": 30},
    verbose=True,
) -> gpd.GeoDataFrame:
    """
    Generate detailed inspection data for a DGGRID DGGS type at a given resolution.

    Args:
        dggrid_instance: DGGRID instance for grid operations
        dggs_type: DGGS type supported by DGGRID (see dggs_types)
        resolution: Resolution level
        split_antimeridian: When True, apply antimeridian fixing to the resulting polygons.
        Defaults to False to avoid splitting the Antimeridian by default.
        aggregate: When True, aggregate the resulting polygons. Defaults to False to avoid aggregation by default.
        options (dict, optional): Options to pass to grid_cell_polygons_for_extent.
            For example: {"densification": 2} to add densification points.
            Defaults to None.
        verbose: Show progress bars. Defaults to True.
    Returns:
        geopandas.GeoDataFrame: DataFrame containing inspection data with columns:
          - name (cell identifier from DGGRID)
          - resolution
          - geometry
          - cell_area (m^2)
          - cell_perimeter (m)
          - crossed (bool)
          - norm_area (area/mean_area)
          - ipq (4πA/P²)
          - zsc (sqrt(4πA - A²/R²)/P), with R=WGS84 a
    """

    # Generate grid using dggridgen
    dggrid_gdf = dggridgen(
        dggrid_instance,
        dggs_type,
        resolution,
        output_format="gpd",
        split_antimeridian=split_antimeridian,
        aggregate=aggregate,
        options=options,
        verbose=verbose,
    )

    # Remove cells with null or invalid geometry
    dggrid_gdf = dggrid_gdf.dropna(subset=["geometry"])
    dggrid_gdf = dggrid_gdf[dggrid_gdf.geometry.is_valid]

    # Add dggs_type column
    dggrid_gdf["dggs_type"] = f"dggrid_{dggs_type.lower()}"

    # Rename global_id to cell_id
    if "global_id" in dggrid_gdf.columns:
        dggrid_gdf = dggrid_gdf.rename(columns={"global_id": "cell_id"})

    # Determine whether current CRS is geographic; compute metrics accordingly
    if dggrid_gdf.crs.is_geographic:
        def _geod_area_perimeter(g):
            cell_area_perimeter = geod.geometry_area_perimeter(g)
            return pd.Series(
                {
                    "cell_area": abs(cell_area_perimeter[0]),
                    "cell_perimeter": abs(cell_area_perimeter[1]),
                }
            )

        metrics = dggrid_gdf.geometry.apply(_geod_area_perimeter)
        dggrid_gdf["cell_area"] = metrics["cell_area"]
        dggrid_gdf["cell_perimeter"] = metrics["cell_perimeter"]
        dggrid_gdf["crossed"] = dggrid_gdf.geometry.apply(check_crossing_geom)
    else:
        dggrid_gdf["cell_area"] = dggrid_gdf.geometry.area
        dggrid_gdf["cell_perimeter"] = dggrid_gdf.geometry.length
        dggrid_gdf["crossed"] = False

    # Add resolution column
    dggrid_gdf["resolution"] = resolution

    dggrid_gdf = dggrid_gdf[
        ~dggrid_gdf["crossed"]
    ]  # remove cells that cross the Antimeridian
    # Calculate normalized area
    # mean_area = dggrid_gdf["cell_area"].mean()
    num_cells, _, _, _ = dggrid_metrics(dggrid_instance, dggs_type, resolution)
    mean_area = AUTHALIC_AREA / num_cells
    dggrid_gdf["norm_area"] = (
        dggrid_gdf["cell_area"] / mean_area if mean_area and mean_area != 0 else np.nan
    )

    # Calculate compactness metrics (robust formulas avoiding division by zero)
    dggrid_gdf["ipq"] = (
        4 * np.pi * dggrid_gdf["cell_area"] / (dggrid_gdf["cell_perimeter"] ** 2)
    )
    dggrid_gdf["zsc"] = (
        np.sqrt(
            4 * np.pi * dggrid_gdf["cell_area"]
            - np.power(dggrid_gdf["cell_area"], 2) / np.power(6378137, 2)
        )
        / dggrid_gdf["cell_perimeter"]
    )

    # Compute convex hull using Lambert Azimuthal Equal Area projection
    convex_hull = dggrid_gdf["geometry"].apply(convexhull_from_lambert)
    # Calculate convex hull area using Lambert projection
    convex_hull_area = convex_hull.apply(
        lambda g: get_area_perimeter_from_lambert(g)[0] if g is not None else np.nan
    )
    # Calculate cell area using Lambert projection for consistent cvh calculation
    dggrid_gdf_lambert = get_cells_area(dggrid_gdf.copy(), "LAEA")
    # Compute CVH safely; set to NaN where convex hull area is non-positive or invalid
    dggrid_gdf["cvh"] = np.where(
        (convex_hull_area > 0) & np.isfinite(convex_hull_area),
        dggrid_gdf_lambert["area"] / convex_hull_area,
        np.nan,
    )
    # Replace any accidental inf values with NaN
    dggrid_gdf["cvh"] = dggrid_gdf["cvh"].replace([np.inf, -np.inf], np.nan)

    return dggrid_gdf

This module provides functions for generating statistics for ISEA4T DGGS cells.

isea4tstats(unit='m')

Generate statistics for ISEA4T DGGS cells.

Parameters:

Name	Type	Description	Default
unit	str	'm' or 'km' for length; area will be 'm^2' or 'km^2'	'm'

Returns:

Type	Description
	pandas.DataFrame: DataFrame containing ISEA4T DGGS statistics with columns: - Resolution: Resolution level (0-39) - Number_of_Cells: Number of cells at each resolution - Avg_Edge_Length_{unit}: Average edge length in the given unit - Avg_Cell_Area_{unit}2: Average cell area in the squared unit

Source code in vgrid/stats/isea4tstats.py

def isea4tstats(unit: str = "m"):  # length unit is km, area unit is km2
    """
    Generate statistics for ISEA4T DGGS cells.

    Args:
        unit: 'm' or 'km' for length; area will be 'm^2' or 'km^2'

    Returns:
        pandas.DataFrame: DataFrame containing ISEA4T DGGS statistics with columns:
            - Resolution: Resolution level (0-39)
            - Number_of_Cells: Number of cells at each resolution
            - Avg_Edge_Length_{unit}: Average edge length in the given unit
            - Avg_Cell_Area_{unit}2: Average cell area in the squared unit
    """
    # normalize and validate unit
    unit = unit.strip().lower()
    if unit not in {"m", "km"}:
        raise ValueError("unit must be one of {'m','km'}")

    # Initialize lists to store data
    resolutions = []
    num_cells_list = []
    avg_edge_lens = []
    avg_cell_areas = []
    cls_list = []
    for res in range(min_res, max_res + 1):
        num_cells, avg_edge_len, avg_cell_area, cls = isea4t_metrics(
            res, unit=unit
        )  # length unit is km, area unit is km2
        resolutions.append(res)
        num_cells_list.append(num_cells)
        avg_edge_lens.append(avg_edge_len)
        avg_cell_areas.append(avg_cell_area)
        cls_list.append(cls)
    # Create DataFrame
    # Build column labels with unit awareness
    avg_edge_len = f"avg_edge_len_{unit}"
    unit_area_label = {"m": "m2", "km": "km2"}[unit]
    avg_cell_area = f"avg_cell_area_{unit_area_label}"
    cls_label = f"cls_{unit}"
    df = pd.DataFrame(
        {
            "resolution": resolutions,
            "number_of_cells": num_cells_list,
            avg_edge_len: avg_edge_lens,
            avg_cell_area: avg_cell_areas,
            cls_label: cls_list,
        }
    )

    return df

isea4tinspect(resolution, fix_antimeridian=None, verbose=True)

Generate comprehensive inspection data for ISEA4T DGGS cells at a given resolution.

This function creates a detailed analysis of ISEA4T cells including area variations, compactness measures, and dateline crossing detection.

Parameters:

Name	Type	Description	Default
resolution		ISEA4T resolution level (0-15)	required
fix_antimeridian	None	Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none	None
verbose		Show progress bars. Defaults to True.	True

Source code in vgrid/stats/isea4tstats.py

def isea4tinspect(resolution, fix_antimeridian: None = None, verbose=True):
    """
    Generate comprehensive inspection data for ISEA4T DGGS cells at a given resolution.

    This function creates a detailed analysis of ISEA4T cells including area variations,
    compactness measures, and dateline crossing detection.

    Args:
        resolution: ISEA4T resolution level (0-15)
        fix_antimeridian: Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none
        verbose: Show progress bars. Defaults to True.
    Returns:
        geopandas.GeoDataFrame: DataFrame containing ISEA4T cell inspection data with columns:
            - isea4t: ISEA4T cell ID
            - resolution: Resolution level
            - geometry: Cell geometry
            - cell_area: Cell area in square meters
            - cell_perimeter: Cell perimeter in meters
            - crossed: Whether cell crosses the dateline
            - norm_area: Normalized area (cell_area / mean_area)
            - ipq: Isoperimetric Quotient compactness
            - zsc: Zonal Standardized Compactness
    """
    # Allow running on all platforms
    resolution = validate_isea4t_resolution(resolution)
    isea4t_gdf = isea4tgrid(
        resolution, output_format="gpd", fix_antimeridian=fix_antimeridian, verbose=verbose
    )
    isea4t_gdf["crossed"] = isea4t_gdf["geometry"].apply(check_crossing_geom)
    isea4t_gdf = isea4t_gdf[
        ~isea4t_gdf["crossed"]
    ]  # remove cells that cross the Antimeridian
    # mean_area = isea4t_gdf["cell_area"].mean()
    num_cells = 20 * (4**resolution)
    mean_area = AUTHALIC_AREA / num_cells
    # Calculate normalized area
    isea4t_gdf["norm_area"] = isea4t_gdf["cell_area"] / mean_area
    # Calculate IPQ compactness using the standard formula: CI = 4πA/P²
    isea4t_gdf["ipq"] = (
        4 * np.pi * isea4t_gdf["cell_area"] / (isea4t_gdf["cell_perimeter"] ** 2)
    )
    # Calculate zonal standardized compactness
    isea4t_gdf["zsc"] = (
        np.sqrt(
            4 * np.pi * isea4t_gdf["cell_area"]
            - np.power(isea4t_gdf["cell_area"], 2) / np.power(6378137, 2)
        )
        / isea4t_gdf["cell_perimeter"]
    )

    # Compute convex hull using Lambert Azimuthal Equal Area projection
    convex_hull = isea4t_gdf["geometry"].apply(convexhull_from_lambert)
    # Calculate convex hull area using Lambert projection
    convex_hull_area = convex_hull.apply(
        lambda g: get_area_perimeter_from_lambert(g)[0] if g is not None else np.nan
    )
    # Calculate cell area using Lambert projection for consistent cvh calculation
    isea4t_gdf_lambert = get_cells_area(isea4t_gdf.copy(), "LAEA")
    # Compute CVH safely; set to NaN where convex hull area is non-positive or invalid
    isea4t_gdf["cvh"] = np.where(
        (convex_hull_area > 0) & np.isfinite(convex_hull_area),
        isea4t_gdf_lambert["area"] / convex_hull_area,
        np.nan,
    )
    # Replace any accidental inf values with NaN
    isea4t_gdf["cvh"] = isea4t_gdf["cvh"].replace([np.inf, -np.inf], np.nan)
    return isea4t_gdf

This module provides functions for generating statistics for ISEA3H DGGS cells.

isea3hstats(unit='m')

Generate statistics for ISEA3H DGGS cells.

Parameters:

Name	Type	Description	Default
unit	str	'm' or 'km' for length; area will be 'm^2' or 'km^2'	'm'

Returns:

Type	Description
	pandas.DataFrame: DataFrame containing ISEA3H DGGS statistics with columns: - Resolution: Resolution level (0-40) - Number_of_Cells: Number of cells at each resolution - Avg_Edge_Length_{unit}: Average edge length in the given unit - Avg_Cell_Area_{unit}2: Average cell area in the squared unit

Source code in vgrid/stats/isea3hstats.py

def isea3hstats(unit: str = "m"):  # length unit is km, area unit is km2
    """
    Generate statistics for ISEA3H DGGS cells.

    Args:
        unit: 'm' or 'km' for length; area will be 'm^2' or 'km^2'

    Returns:
        pandas.DataFrame: DataFrame containing ISEA3H DGGS statistics with columns:
            - Resolution: Resolution level (0-40)
            - Number_of_Cells: Number of cells at each resolution
            - Avg_Edge_Length_{unit}: Average edge length in the given unit
            - Avg_Cell_Area_{unit}2: Average cell area in the squared unit
    """
    # normalize and validate unit
    unit = unit.strip().lower()
    if unit not in {"m", "km"}:
        raise ValueError("unit must be one of {'m','km'}")

    # Initialize lists to store data
    resolutions = []
    num_cells_list = []
    avg_edge_lens = []
    avg_cell_areas = []
    cls_list = []
    for res in range(min_res, max_res + 1):
        num_cells, avg_edge_len, avg_cell_area, cls = isea3h_metrics(
            res, unit=unit
        )  # length unit is km, area unit is km2
        resolutions.append(res)
        num_cells_list.append(num_cells)
        avg_edge_lens.append(avg_edge_len)
        avg_cell_areas.append(avg_cell_area)
        cls_list.append(cls)
    # Create DataFrame
    # Build column labels with unit awareness
    avg_edge_len = f"avg_edge_len_{unit}"
    unit_area_label = {"m": "m2", "km": "km2"}[unit]
    avg_cell_area = f"avg_cell_area_{unit_area_label}"
    cls_label = f"cls_{unit}"
    df = pd.DataFrame(
        {
            "resolution": resolutions,
            "number_of_cells": num_cells_list,
            avg_edge_len: avg_edge_lens,
            avg_cell_area: avg_cell_areas,
            cls_label: cls_list,
        }
    )

    return df

isea3hinspect(resolution, fix_antimeridian=None, verbose=True)

Generate comprehensive inspection data for ISEA3H DGGS cells at a given resolution.

This function creates a detailed analysis of ISEA3H cells including area variations, compactness measures, and Antimeridian crossing detection.

Parameters:

Name	Type	Description	Default
resolution	int	ISEA3H resolution level (0-40)	required
fix_antimeridian	None	Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none	None
verbose		Show progress bars. Defaults to True.	True

Source code in vgrid/stats/isea3hstats.py

def isea3hinspect(resolution: int, fix_antimeridian: None = None, verbose=True):
    """
    Generate comprehensive inspection data for ISEA3H DGGS cells at a given resolution.

    This function creates a detailed analysis of ISEA3H cells including area variations,
    compactness measures, and Antimeridian crossing detection.

    Args:
        resolution: ISEA3H resolution level (0-40)
        fix_antimeridian: Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none
        verbose: Show progress bars. Defaults to True.
    Returns:
        geopandas.GeoDataFrame: DataFrame containing ISEA3H cell inspection data with columns:
            - isea3h: ISEA3H cell ID
            - resolution: Resolution level
            - geometry: Cell geometry
            - cell_area: Cell area in square meters
            - cell_perimeter: Cell perimeter in meters
            - crossed: Whether cell crosses the Antimeridian
            - norm_area: Normalized area (cell_area / mean_area)
            - ipq: Isoperimetric Quotient compactness
            - zsc: Zonal Standardized Compactness
    """
    # Allow running on all platforms

    isea3h_gdf = isea3hgrid(
        resolution, output_format="gpd", fix_antimeridian=fix_antimeridian, verbose=verbose
    )  # remove cells that cross the Antimeridian
    isea3h_gdf["crossed"] = isea3h_gdf["geometry"].apply(check_crossing_geom)
    isea3h_gdf = isea3h_gdf[
        ~isea3h_gdf["crossed"]
    ]  # remove cells that cross the Antimeridian
    mean_area = isea3h_gdf["cell_area"].mean()
    # Calculate normalized area
    isea3h_gdf["norm_area"] = isea3h_gdf["cell_area"] / mean_area
    # Calculate IPQ compactness using the standard formula: CI = 4πA/P²
    isea3h_gdf["ipq"] = (
        4 * np.pi * isea3h_gdf["cell_area"] / (isea3h_gdf["cell_perimeter"] ** 2)
    )
    # Calculate zonal standardized compactness
    isea3h_gdf["zsc"] = (
        np.sqrt(
            4 * np.pi * isea3h_gdf["cell_area"]
            - np.power(isea3h_gdf["cell_area"], 2) / np.power(6378137, 2)
        )
        / isea3h_gdf["cell_perimeter"]
    )

    # Compute convex hull using Lambert Azimuthal Equal Area projection
    convex_hull = isea3h_gdf["geometry"].apply(convexhull_from_lambert)
    # Calculate convex hull area using Lambert projection
    convex_hull_area = convex_hull.apply(
        lambda g: get_area_perimeter_from_lambert(g)[0] if g is not None else np.nan
    )
    # Calculate cell area using Lambert projection for consistent cvh calculation
    isea3h_gdf_lambert = get_cells_area(isea3h_gdf.copy(), "LAEA")
    # Compute CVH safely; set to NaN where convex hull area is non-positive or invalid
    isea3h_gdf["cvh"] = np.where(
        (convex_hull_area > 0) & np.isfinite(convex_hull_area),
        isea3h_gdf_lambert["area"] / convex_hull_area,
        np.nan,
    )
    # Replace any accidental inf values with NaN
    isea3h_gdf["cvh"] = isea3h_gdf["cvh"].replace([np.inf, -np.inf], np.nan)
    return isea3h_gdf

This module provides functions for generating statistics for EASE-DGGS cells.

easestats(unit='m')

Generate statistics for EASE-DGGS cells. length unit is m, area unit is m2 Args: unit: 'm' or 'km' for length; area will be 'm^2' or 'km^2'

Returns:

Type	Description
	pandas.DataFrame: DataFrame containing EASE-DGGS statistics with columns: - Resolution: Resolution level (0-6) - Number_of_Cells: Number of cells at each resolution - Avg_Edge_Length_{unit}: Average edge length in the given unit - Avg_Cell_Area_{unit}2: Average cell area in the squared unit - CLS_{unit}: Characteristic Length Scale in the given unit

Source code in vgrid/stats/easestats.py

def easestats(unit: str = "m"):  # length unit is m, area unit is m2
    """
    Generate statistics for EASE-DGGS cells.
    length unit is m, area unit is m2
    Args:
        unit: 'm' or 'km' for length; area will be 'm^2' or 'km^2'

    Returns:
        pandas.DataFrame: DataFrame containing EASE-DGGS statistics with columns:
            - Resolution: Resolution level (0-6)
            - Number_of_Cells: Number of cells at each resolution
            - Avg_Edge_Length_{unit}: Average edge length in the given unit
            - Avg_Cell_Area_{unit}2: Average cell area in the squared unit
            - CLS_{unit}: Characteristic Length Scale in the given unit
    """
    # normalize and validate unit
    unit = unit.strip().lower()
    if unit not in {"m", "km"}:
        raise ValueError("unit must be one of {'m','km'}")

    # Initialize lists to store data
    resolutions = []
    num_cells_list = []
    avg_edge_lens = []
    avg_cell_areas = []
    cls_list = []
    for res in range(min_res, max_res + 1):
        num_cells_at_res, avg_edge_length, cell_area, cls = ease_metrics(res, unit)
        resolutions.append(res)
        num_cells_list.append(num_cells_at_res)
        avg_edge_lens.append(avg_edge_length)
        avg_cell_areas.append(cell_area)
        cls_list.append(cls)
    # Create DataFrame
    # Build column labels with unit awareness
    avg_edge_len = f"avg_edge_len_{unit}"
    unit_area_label = {"m": "m2", "km": "km2"}[unit]
    avg_cell_area = f"avg_cell_area_{unit_area_label}"
    cls_label = f"cls_{unit}"
    df = pd.DataFrame(
        {
            "resolution": resolutions,
            "number_of_cells": num_cells_list,
            avg_edge_len: avg_edge_lens,
            avg_cell_area: avg_cell_areas,
            cls_label: cls_list,
        }
    )

    return df

easeinspect(resolution, verbose=True)

Generate comprehensive inspection data for EASE-DGGS cells at a given resolution.

This function creates a detailed analysis of EASE cells including area variations, compactness measures, and Antimeridian crossing detection.

Parameters:

Name	Type	Description	Default
resolution	int	EASE-DGGS resolution level (0-6)	required
verbose		Show progress bars. Defaults to True.	True

Source code in vgrid/stats/easestats.py

def easeinspect(resolution: int, verbose=True):  # length unit is m, area unit is m2
    """
    Generate comprehensive inspection data for EASE-DGGS cells at a given resolution.

    This function creates a detailed analysis of EASE cells including area variations,
    compactness measures, and Antimeridian crossing detection.

    Args:
        resolution: EASE-DGGS resolution level (0-6)

        verbose: Show progress bars. Defaults to True.
    Returns:
        geopandas.GeoDataFrame: DataFrame containing EASE cell inspection data with columns:
            - ease: EASE cell ID
            - resolution: Resolution level
            - geometry: Cell geometry
            - cell_area: Cell area in square meters
            - cell_perimeter: Cell perimeter in meters
            - crossed: Whether cell crosses the dateline
            - norm_area: Normalized area (cell_area / mean_area)
            - ipq: Isoperimetric Quotient compactness
            - zsc: Zonal Standardized Compactness
    """
    ease_gdf = easegrid(resolution, output_format="gpd", verbose=verbose)
    ease_gdf["crossed"] = ease_gdf["geometry"].apply(check_crossing_geom)
    # ease_gdf = ease_gdf[~ease_gdf["crossed"]]  # remove cells that cross the Antimeridian

    # mean_area = ease_gdf["cell_area"].mean()
    num_cells = levels_specs[resolution]["n_row"] * levels_specs[resolution]["n_col"]
    mean_area = AUTHALIC_AREA / num_cells
    # Calculate normalized area
    ease_gdf["norm_area"] = ease_gdf["cell_area"] / mean_area
    # Calculate IPQ compactness using the standard formula: CI = 4πA/P²
    ease_gdf["ipq"] = (
        4 * np.pi * ease_gdf["cell_area"] / (ease_gdf["cell_perimeter"] ** 2)
    )
    # Calculate zonal standardized compactness
    ease_gdf["zsc"] = (
        np.sqrt(
            4 * np.pi * ease_gdf["cell_area"]
            - np.power(ease_gdf["cell_area"], 2) / np.power(6378137, 2)
        )
        / ease_gdf["cell_perimeter"]
    )

    # Compute convex hull using Lambert Azimuthal Equal Area projection
    convex_hull = ease_gdf["geometry"].apply(convexhull_from_lambert)
    # Calculate convex hull area using Lambert projection
    convex_hull_area = convex_hull.apply(
        lambda g: get_area_perimeter_from_lambert(g)[0] if g is not None else np.nan
    )
    # Calculate cell area using Lambert projection for consistent cvh calculation
    ease_gdf_lambert = get_cells_area(ease_gdf.copy(), "LAEA")
    # Compute CVH safely; set to NaN where convex hull area is non-positive or invalid
    ease_gdf["cvh"] = np.where(
        (convex_hull_area > 0) & np.isfinite(convex_hull_area),
        ease_gdf_lambert["area"] / convex_hull_area,
        np.nan,
    )
    # Replace any accidental inf values with NaN
    ease_gdf["cvh"] = ease_gdf["cvh"].replace([np.inf, -np.inf], np.nan)
    return ease_gdf

This module provides functions for generating statistics for QTM DGGS cells.

qtmstats(unit='m')

Generate statistics for QTM DGGS cells.

Parameters:

Name	Type	Description	Default
unit	str	'm' or 'km' for length; area will be 'm^2' or 'km^2'	'm'

Returns:

Type	Description
	pandas.DataFrame: DataFrame containing QTM DGGS statistics with columns: - resolution: Resolution level (1-24) - number_of_cells: Number of cells at each resolution - avg_edge_len_{unit}: Average edge length in the given unit - avg_cell_area_{unit}2: Average cell area in the squared unit

Source code in vgrid/stats/qtmstats.py

def qtmstats(unit: str = "m"):  # length unit is km, area unit is km2
    """
    Generate statistics for QTM DGGS cells.

    Args:
        unit: 'm' or 'km' for length; area will be 'm^2' or 'km^2'

    Returns:
        pandas.DataFrame: DataFrame containing QTM DGGS statistics with columns:
            - resolution: Resolution level (1-24)
            - number_of_cells: Number of cells at each resolution
            - avg_edge_len_{unit}: Average edge length in the given unit
            - avg_cell_area_{unit}2: Average cell area in the squared unit
    """
    # normalize and validate unit
    unit = unit.strip().lower()
    if unit not in {"m", "km"}:
        raise ValueError("unit must be one of {'m','km'}")

    # Initialize lists to store data
    resolutions = []
    num_cells_list = []
    avg_edge_lens = []
    avg_cell_areas = []
    cls_list = []
    for res in range(min_res, max_res + 1):
        num_cells, avg_edge_len, avg_cell_area, cls = qtm_metrics(res, unit=unit)
        resolutions.append(res)
        num_cells_list.append(num_cells)
        avg_edge_lens.append(avg_edge_len)
        avg_cell_areas.append(avg_cell_area)
        cls_list.append(cls)
    # Create DataFrame
    # Build column labels with unit awareness (lower case)
    avg_edge_len = f"avg_edge_len_{unit}"
    unit_area_label = {"m": "m2", "km": "km2"}[unit]
    avg_cell_area = f"avg_cell_area_{unit_area_label}"
    cls_label = f"cls_{unit}"
    df = pd.DataFrame(
        {
            "resolution": resolutions,
            "number_of_cells": num_cells_list,
            avg_edge_len: avg_edge_lens,
            avg_cell_area: avg_cell_areas,
            cls_label: cls_list,
        }
    )

    return df

qtminspect(resolution, verbose=True)

Generate comprehensive inspection data for QTM DGGS cells at a given resolution.

This function creates a detailed analysis of QTM cells including area variations, compactness measures, and dateline crossing detection.

Parameters:

Name	Type	Description	Default
resolution	int	QTM resolution level (1-24)	required
verbose		Show progress bars. Defaults to True.	True

Source code in vgrid/stats/qtmstats.py

def qtminspect(resolution: int, verbose=True):
    """
    Generate comprehensive inspection data for QTM DGGS cells at a given resolution.

    This function creates a detailed analysis of QTM cells including area variations,
    compactness measures, and dateline crossing detection.

    Args:
        resolution: QTM resolution level (1-24)

        verbose: Show progress bars. Defaults to True.
    Returns:
        geopandas.GeoDataFrame: DataFrame containing QTM cell inspection data with columns:
            - qtm: QTM cell ID
            - resolution: Resolution level
            - geometry: Cell geometry
            - cell_area: Cell area in square meters
            - cell_perimeter: Cell perimeter in meters
            - crossed: Whether cell crosses the dateline
            - norm_area: Normalized area (cell_area / mean_area)
            - ipq: Isoperimetric Quotient compactness
            - zsc: Zonal Standardized Compactness
    """
    qtm_gdf = qtm_grid(resolution, verbose=verbose)
    qtm_gdf["crossed"] = qtm_gdf["geometry"].apply(check_crossing_geom)
    qtm_gdf = qtm_gdf[~qtm_gdf["crossed"]]  # remove cells that cross the Antimeridian
    # mean_area = qtm_gdf["cell_area"].mean()
    num_cells = 8 * 4 ** (resolution - 1)
    mean_area = AUTHALIC_AREA / num_cells
    # Calculate normalized area
    qtm_gdf["norm_area"] = qtm_gdf["cell_area"] / mean_area
    # Calculate IPQ compactness using the standard formula: CI = 4πA/P²
    qtm_gdf["ipq"] = 4 * np.pi * qtm_gdf["cell_area"] / (qtm_gdf["cell_perimeter"] ** 2)
    # Calculate zonal standardized compactness
    qtm_gdf["zsc"] = (
        np.sqrt(
            4 * np.pi * qtm_gdf["cell_area"]
            - np.power(qtm_gdf["cell_area"], 2) / np.power(6378137, 2)
        )
        / qtm_gdf["cell_perimeter"]
    )

    # Compute convex hull using Lambert Azimuthal Equal Area projection
    convex_hull = qtm_gdf["geometry"].apply(convexhull_from_lambert)
    # Calculate convex hull area using Lambert projection
    convex_hull_area = convex_hull.apply(
        lambda g: get_area_perimeter_from_lambert(g)[0] if g is not None else np.nan
    )
    # Calculate cell area using Lambert projection for consistent cvh calculation
    qtm_gdf_lambert = get_cells_area(qtm_gdf.copy(), "LAEA")
    # Compute CVH safely; set to NaN where convex hull area is non-positive or invalid
    qtm_gdf["cvh"] = np.where(
        (convex_hull_area > 0) & np.isfinite(convex_hull_area),
        qtm_gdf_lambert["area"] / convex_hull_area,
        np.nan,
    )
    # Replace any accidental inf values with NaN
    qtm_gdf["cvh"] = qtm_gdf["cvh"].replace([np.inf, -np.inf], np.nan)

    return qtm_gdf

This module provides functions for generating statistics for OLC DGGS cells.

olcstats(unit='m')

Generate statistics for OLC DGGS cells.

Parameters:

Name	Type	Description	Default
unit	str	'm' or 'km' for length; area will be 'm^2' or 'km^2'	'm'

Returns:

Type	Description
	pandas.DataFrame: DataFrame containing OLC DGGS statistics with columns: - resolution: Resolution level (2,4,6,8,10,11,12,13,14,15) - number_of_cells: Number of cells at each resolution - avg_edge_len_{unit}: Average edge length in the given unit - avg_cell_area_{unit}2: Average cell area in the squared unit

Source code in vgrid/stats/olcstats.py

def olcstats(unit: str = "m"):  # length unit is km, area unit is km2
    """
    Generate statistics for OLC DGGS cells.

    Args:
        unit: 'm' or 'km' for length; area will be 'm^2' or 'km^2'

    Returns:
        pandas.DataFrame: DataFrame containing OLC DGGS statistics with columns:
            - resolution: Resolution level (2,4,6,8,10,11,12,13,14,15)
            - number_of_cells: Number of cells at each resolution
            - avg_edge_len_{unit}: Average edge length in the given unit
            - avg_cell_area_{unit}2: Average cell area in the squared unit
    """
    # normalize and validate unit
    unit = unit.strip().lower()
    if unit not in {"m", "km"}:
        raise ValueError("unit must be one of {'m','km'}")

    # Only specific resolutions are supported

    # Initialize lists to store data
    resolutions = []
    num_cells_list = []
    avg_edge_lens = []
    avg_cell_areas = []
    cls_list = []
    for res in olc_resolutions:
        num_cells, avg_edge_len, avg_cell_area, cls = olc_metrics(res, unit=unit)
        resolutions.append(res)
        num_cells_list.append(num_cells)
        avg_edge_lens.append(avg_edge_len)
        avg_cell_areas.append(avg_cell_area)
        cls_list.append(cls)
    # Create DataFrame
    # Build column labels with unit awareness (lower case)
    avg_edge_len = f"avg_edge_len_{unit}"
    unit_area_label = {"m": "m2", "km": "km2"}[unit]
    avg_cell_area = f"avg_cell_area_{unit_area_label}"
    cls_label = f"cls_{unit}"
    df = pd.DataFrame(
        {
            "resolution": resolutions,
            "number_of_cells": num_cells_list,
            avg_edge_len: avg_edge_lens,
            avg_cell_area: avg_cell_areas,
            cls_label: cls_list,
        }
    )

    return df

olcinspect(resolution, verbose=True)

Generate comprehensive inspection data for OLC DGGS cells at a given resolution.

This function creates a detailed analysis of OLC cells including area variations, compactness measures, and dateline crossing detection.

Parameters:

Name	Type	Description	Default
resolution	int	OLC resolution level (2-15)	required
verbose		Show progress bars. Defaults to True.	True

Source code in vgrid/stats/olcstats.py

def olcinspect(resolution: int, verbose=True):
    """
    Generate comprehensive inspection data for OLC DGGS cells at a given resolution.

    This function creates a detailed analysis of OLC cells including area variations,
    compactness measures, and dateline crossing detection.

    Args:
        resolution: OLC resolution level (2-15)

        verbose: Show progress bars. Defaults to True.
    Returns:
        geopandas.GeoDataFrame: DataFrame containing OLC cell inspection data with columns:
            - olc: OLC cell ID
            - resolution: Resolution level
            - geometry: Cell geometry
            - cell_area: Cell area in square meters
            - cell_perimeter: Cell perimeter in meters
            - crossed: Whether cell crosses the dateline
            - norm_area: Normalized area (cell_area / mean_area)
            - ipq: Isoperimetric Quotient compactness
            - zsc: Zonal Standardized Compactness
    """
    olc_gdf = olcgrid(resolution, output_format="gpd", verbose=verbose)
    olc_gdf["crossed"] = olc_gdf["geometry"].apply(check_crossing_geom)
    # mean_area = olc_gdf["cell_area"].mean()
    if resolution <= 10:
        num_cells = 162 * (400 ** ((resolution // 2) - 1))
    else:
        base = 162 * (400 ** ((10 // 2) - 1))
        extra = resolution - 10
        num_cells = base * (20**extra)
    mean_area = AUTHALIC_AREA / num_cells
    # Calculate normalized area
    olc_gdf["norm_area"] = olc_gdf["cell_area"] / mean_area
    # Calculate IPQ compactness using the standard formula: CI = 4πA/P²
    olc_gdf["ipq"] = 4 * np.pi * olc_gdf["cell_area"] / (olc_gdf["cell_perimeter"] ** 2)
    # Calculate zonal standardized compactness
    olc_gdf["zsc"] = (
        np.sqrt(
            4 * np.pi * olc_gdf["cell_area"]
            - np.power(olc_gdf["cell_area"], 2) / np.power(6378137, 2)
        )
        / olc_gdf["cell_perimeter"]
    )

    # Compute convex hull using Lambert Azimuthal Equal Area projection
    convex_hull = olc_gdf["geometry"].apply(convexhull_from_lambert)
    # Calculate convex hull area using Lambert projection
    convex_hull_area = convex_hull.apply(
        lambda g: get_area_perimeter_from_lambert(g)[0] if g is not None else np.nan
    )
    # Calculate cell area using Lambert projection for consistent cvh calculation
    olc_gdf_lambert = get_cells_area(olc_gdf.copy(), "LAEA")
    # Compute CVH safely; set to NaN where convex hull area is non-positive or invalid
    olc_gdf["cvh"] = np.where(
        (convex_hull_area > 0) & np.isfinite(convex_hull_area),
        olc_gdf_lambert["area"] / convex_hull_area,
        np.nan,
    )
    # Replace any accidental inf values with NaN
    olc_gdf["cvh"] = olc_gdf["cvh"].replace([np.inf, -np.inf], np.nan)

    return olc_gdf

This module provides functions for generating statistics for Geohash DGGS cells.

geohashstats(unit='m')

Generate statistics for Geohash DGGS cells.

Parameters:

Name	Type	Description	Default
unit	str	'm' or 'km' for length; area will be 'm^2' or 'km^2'	'm'

Returns:

Type	Description
	pandas.DataFrame: DataFrame containing Geohash DGGS statistics with columns: - resolution: Resolution level (0-12) - number_of_cells: Number of cells at each resolution - avg_edge_len_{unit}: Average edge length in the given unit - avg_cell_area_{unit}2: Average cell area in the squared unit

Source code in vgrid/stats/geohashstats.py

def geohashstats(unit: str = "m"):
    """
    Generate statistics for Geohash DGGS cells.

    Args:
        unit: 'm' or 'km' for length; area will be 'm^2' or 'km^2'

    Returns:
        pandas.DataFrame: DataFrame containing Geohash DGGS statistics with columns:
            - resolution: Resolution level (0-12)
            - number_of_cells: Number of cells at each resolution
            - avg_edge_len_{unit}: Average edge length in the given unit
            - avg_cell_area_{unit}2: Average cell area in the squared unit
    """
    # normalize and validate unit
    unit = unit.strip().lower()
    if unit not in {"m", "km"}:
        raise ValueError("unit must be one of {'m','km'}")

    # Initialize lists to store data
    resolutions = []
    num_cells_list = []
    avg_edge_lens = []
    avg_cell_areas = []
    cls_list = []
    for res in range(min_res, max_res + 1):
        num_cells, avg_edge_len, avg_cell_area, cls = geohash_metrics(res, unit=unit)
        resolutions.append(res)
        num_cells_list.append(num_cells)
        avg_edge_lens.append(avg_edge_len)
        avg_cell_areas.append(avg_cell_area)
        cls_list.append(cls)
    # Create DataFrame
    # Build column labels with unit awareness (lower case)
    avg_edge_len = f"avg_edge_len_{unit}"
    unit_area_label = {"m": "m2", "km": "km2"}[unit]
    avg_cell_area = f"avg_cell_area_{unit_area_label}"
    cls_label = f"cls_{unit}"
    df = pd.DataFrame(
        {
            "resolution": resolutions,
            "number_of_cells": num_cells_list,
            avg_edge_len: avg_edge_lens,
            avg_cell_area: avg_cell_areas,
            cls_label: cls_list,
        }
    )

    return df

geohashinspect(resolution, verbose=True)

Generate comprehensive inspection data for Geohash DGGS cells at a given resolution.

This function creates a detailed analysis of Geohash cells including area variations, compactness measures, and Antimeridian crossing detection.

Parameters:

Name	Type	Description	Default
resolution	int	Geohash resolution level (0-12)	required
verbose		Show progress bars. Defaults to True.	True

Source code in vgrid/stats/geohashstats.py

def geohashinspect(resolution: int, verbose=True):
    """
    Generate comprehensive inspection data for Geohash DGGS cells at a given resolution.

    This function creates a detailed analysis of Geohash cells including area variations,
    compactness measures, and Antimeridian crossing detection.

    Args:
        resolution: Geohash resolution level (0-12)

        verbose: Show progress bars. Defaults to True.
    Returns:
        geopandas.GeoDataFrame: DataFrame containing Geohash cell inspection data with columns:
            - geohash: Geohash cell ID
            - resolution: Resolution level
            - geometry: Cell geometry
            - cell_area: Cell area in square meters
            - cell_perimeter: Cell perimeter in meters
            - crossed: Whether cell crosses the Antimeridian
            - norm_area: Normalized area (cell_area / mean_area)
            - ipq: Isoperimetric Quotient compactness
            - zsc: Zonal Standardized Compactness
    """
    geohash_gdf = geohashgrid(resolution, output_format="gpd", verbose=verbose)
    geohash_gdf["crossed"] = geohash_gdf["geometry"].apply(check_crossing_geom)
    # mean_area = geohash_gdf["cell_area"].mean()
    num_cells = 32**resolution
    mean_area = AUTHALIC_AREA / num_cells
    # Calculate normalized area
    geohash_gdf["norm_area"] = geohash_gdf["cell_area"] / mean_area
    # Calculate IPQ compactness using the standard formula: CI = 4πA/P²
    geohash_gdf["ipq"] = (
        4 * np.pi * geohash_gdf["cell_area"] / (geohash_gdf["cell_perimeter"] ** 2)
    )
    # Calculate zonal standardized compactness
    geohash_gdf["zsc"] = (
        np.sqrt(
            4 * np.pi * geohash_gdf["cell_area"]
            - np.power(geohash_gdf["cell_area"], 2) / np.power(6378137, 2)
        )
        / geohash_gdf["cell_perimeter"]
    )

    # Compute convex hull using Lambert Azimuthal Equal Area projection
    convex_hull = geohash_gdf["geometry"].apply(convexhull_from_lambert)
    # Calculate convex hull area using Lambert projection
    convex_hull_area = convex_hull.apply(
        lambda g: get_area_perimeter_from_lambert(g)[0] if g is not None else np.nan
    )
    # Calculate cell area using Lambert projection for consistent cvh calculation
    geohash_gdf_lambert = get_cells_area(geohash_gdf.copy(), "LAEA")
    # Compute CVH safely; set to NaN where convex hull area is non-positive or invalid
    geohash_gdf["cvh"] = np.where(
        (convex_hull_area > 0) & np.isfinite(convex_hull_area),
        geohash_gdf_lambert["area"] / convex_hull_area,
        np.nan,
    )
    # Replace any accidental inf values with NaN
    geohash_gdf["cvh"] = geohash_gdf["cvh"].replace([np.inf, -np.inf], np.nan)

    return geohash_gdf

This module provides functions for generating statistics for GEOREF DGGS cells.

georefstats(unit='m')

Generate statistics for GEOREF DGGS cells.

Parameters:

Name	Type	Description	Default
unit	str	'm' or 'km' for length; area will be 'm^2' or 'km^2'	'm'

Returns:

Type	Description
	pandas.DataFrame: DataFrame containing GEOREF DGGS statistics with columns: - resolution: Resolution level (0-7) - number_of_cells: Number of cells at each resolution - avg_edge_len_{unit}: Average edge length in the given unit - avg_cell_area_{unit}2: Average cell area in the squared unit

Source code in vgrid/stats/georefstats.py

def georefstats(unit: str = "m"):
    """
    Generate statistics for GEOREF DGGS cells.

    Args:
        unit: 'm' or 'km' for length; area will be 'm^2' or 'km^2'

    Returns:
        pandas.DataFrame: DataFrame containing GEOREF DGGS statistics with columns:
            - resolution: Resolution level (0-7)
            - number_of_cells: Number of cells at each resolution
            - avg_edge_len_{unit}: Average edge length in the given unit
            - avg_cell_area_{unit}2: Average cell area in the squared unit
    """
    # normalize and validate unit
    unit = unit.strip().lower()
    if unit not in {"m", "km"}:
        raise ValueError("unit must be one of {'m','km'}")

    # Initialize lists to store data
    resolutions = []
    num_cells_list = []
    avg_edge_lens = []
    avg_cell_areas = []
    cls_list = []
    for res in range(min_res, max_res + 1):
        num_cells, avg_edge_len, avg_cell_area, cls = georef_metrics(res, unit=unit)
        resolutions.append(res)
        num_cells_list.append(num_cells)
        avg_edge_lens.append(avg_edge_len)
        avg_cell_areas.append(avg_cell_area)
        cls_list.append(cls)
    # Create DataFrame
    # Build column labels with unit awareness (lower case)
    length_col = f"avg_edge_len_{unit}"
    unit_area_label = {"m": "m2", "km": "km2"}[unit]
    area_col = f"avg_cell_area_{unit_area_label}"
    cls_label = f"cls_{unit}"
    df = pd.DataFrame(
        {
            "resolution": resolutions,
            "number_of_cells": num_cells_list,
            length_col: avg_edge_lens,
            area_col: avg_cell_areas,
            cls_label: cls_list,
        }
    )

    return df

georefinspect(resolution, verbose=True)

Generate comprehensive inspection data for GEOREF DGGS cells at a given resolution.

This function creates a detailed analysis of GEOREF cells including area variations, compactness measures, and Antimeridian crossing detection.

Parameters:

Name	Type	Description	Default
resolution	int	GEOREF resolution level (0-10)	required
verbose		Show progress bars. Defaults to True.	True

Source code in vgrid/stats/georefstats.py

def georefinspect(resolution: int, verbose=True):
    """
    Generate comprehensive inspection data for GEOREF DGGS cells at a given resolution.

    This function creates a detailed analysis of GEOREF cells including area variations,
    compactness measures, and Antimeridian crossing detection.

    Args:
        resolution: GEOREF resolution level (0-10)

        verbose: Show progress bars. Defaults to True.
    Returns:
        geopandas.GeoDataFrame: DataFrame containing GEOREF cell inspection data with columns:
            - georef: GEOREF cell ID
            - resolution: Resolution level
            - geometry: Cell geometry
            - cell_area: Cell area in square meters
            - cell_perimeter: Cell perimeter in meters
            - crossed: Whether cell crosses the Antimeridian
            - norm_area: Normalized area (cell_area / mean_area)
            - ipq: Isoperimetric Quotient compactness
            - zsc: Zonal Standardized Compactness
    """
    georef_gdf = georefgrid(resolution, output_format="gpd", verbose=verbose)
    georef_gdf["crossed"] = georef_gdf["geometry"].apply(check_crossing_geom)
    # mean_area = georef_gdf["cell_area"].mean()
    grid_size_deg = GEOREF_RESOLUTION_DEGREES.get(resolution)
    num_lon = int(round(360.0 / grid_size_deg))
    num_lat = int(round(180.0 / grid_size_deg))
    num_cells = num_lon * num_lat
    mean_area = AUTHALIC_AREA / num_cells
    # Calculate normalized area
    georef_gdf["norm_area"] = georef_gdf["cell_area"] / mean_area
    # Calculate IPQ compactness using the standard formula: CI = 4πA/P²
    georef_gdf["ipq"] = (
        4 * np.pi * georef_gdf["cell_area"] / (georef_gdf["cell_perimeter"] ** 2)
    )
    # Calculate zonal standardized compactness
    georef_gdf["zsc"] = (
        np.sqrt(
            4 * np.pi * georef_gdf["cell_area"]
            - np.power(georef_gdf["cell_area"], 2) / np.power(6378137, 2)
        )
        / georef_gdf["cell_perimeter"]
    )

    # Compute convex hull using Lambert Azimuthal Equal Area projection
    convex_hull = georef_gdf["geometry"].apply(convexhull_from_lambert)
    # Calculate convex hull area using Lambert projection
    convex_hull_area = convex_hull.apply(
        lambda g: get_area_perimeter_from_lambert(g)[0] if g is not None else np.nan
    )
    # Calculate cell area using Lambert projection for consistent cvh calculation
    georef_gdf_lambert = get_cells_area(georef_gdf.copy(), "LAEA")
    # Compute CVH safely; set to NaN where convex hull area is non-positive or invalid
    georef_gdf["cvh"] = np.where(
        (convex_hull_area > 0) & np.isfinite(convex_hull_area),
        georef_gdf_lambert["area"] / convex_hull_area,
        np.nan,
    )
    # Replace any accidental inf values with NaN
    georef_gdf["cvh"] = georef_gdf["cvh"].replace([np.inf, -np.inf], np.nan)

    return georef_gdf

This module provides functions for generating statistics for MGRS DGGS cells.

mgrsstats(unit='m')

Generate statistics for MGRS DGGS cells.

Parameters:

Name	Type	Description	Default
unit	str	'm' or 'km' for length; area will be 'm^2' or 'km^2'	'm'

Returns:

Type	Description
	pandas.DataFrame: DataFrame containing MGRS DGGS statistics with columns: - resolution: Resolution level (0-5) - number_of_cells: Number of cells at each resolution - avg_edge_len_{unit}: Average edge length in the given unit - avg_cell_area_{unit}2: Average cell area in the squared unit

Source code in vgrid/stats/mgrsstats.py

def mgrsstats(unit: str = "m"):
    """
    Generate statistics for MGRS DGGS cells.

    Args:
        unit: 'm' or 'km' for length; area will be 'm^2' or 'km^2'

    Returns:
        pandas.DataFrame: DataFrame containing MGRS DGGS statistics with columns:
            - resolution: Resolution level (0-5)
            - number_of_cells: Number of cells at each resolution
            - avg_edge_len_{unit}: Average edge length in the given unit
            - avg_cell_area_{unit}2: Average cell area in the squared unit
    """
    # normalize and validate unit
    unit = unit.strip().lower()
    if unit not in {"m", "km"}:
        raise ValueError("unit must be one of {'m','km'}")

    # Initialize lists to store data
    resolutions = []
    num_cells_list = []
    avg_edge_lens = []
    avg_cell_areas = []
    cls_list = []
    for resolution in range(min_res, max_res + 1):
        num_cells, avg_edge_len, avg_cell_area, cls = mgrs_metrics(
            resolution, unit=unit
        )
        resolutions.append(resolution)
        num_cells_list.append(num_cells)
        avg_edge_lens.append(avg_edge_len)
        avg_cell_areas.append(avg_cell_area)
        cls_list.append(cls)
    # Create DataFrame
    # Build column labels with unit awareness (lower case)
    avg_edge_len = f"avg_edge_len_{unit}"
    unit_area_label = {"m": "m2", "km": "km2"}[unit]
    avg_cell_area = f"avg_cell_area_{unit_area_label}"
    cls_label = f"cls_{unit}"
    df = pd.DataFrame(
        {
            "resolution": resolutions,
            "number_of_cells": num_cells_list,
            avg_edge_len: avg_edge_lens,
            avg_cell_area: avg_cell_areas,
            cls_label: cls_list,
        }
    )

    return df

This module provides functions for generating statistics for Tilecode DGGS cells.

tilecodestats(unit='m')

Generate statistics for Tilecode DGGS cells.

Parameters:

Name	Type	Description	Default
unit	str	'm' or 'km' for length; area will be 'm^2' or 'km^2'	'm'

Returns:

Type	Description
	pandas.DataFrame: DataFrame containing Tilecode DGGS statistics with columns: - resolution: Resolution level (0-30) - number_of_cells: Number of cells at each resolution - avg_edge_len_{unit}: Average edge length in the given unit - avg_cell_area_{unit}2: Average cell area in the squared unit

Source code in vgrid/stats/tilecodestats.py

def tilecodestats(unit: str = "m"):
    """
    Generate statistics for Tilecode DGGS cells.

    Args:
        unit: 'm' or 'km' for length; area will be 'm^2' or 'km^2'

    Returns:
        pandas.DataFrame: DataFrame containing Tilecode DGGS statistics with columns:
            - resolution: Resolution level (0-30)
            - number_of_cells: Number of cells at each resolution
            - avg_edge_len_{unit}: Average edge length in the given unit
            - avg_cell_area_{unit}2: Average cell area in the squared unit
    """
    # normalize and validate unit
    unit = unit.strip().lower()
    if unit not in {"m", "km"}:
        raise ValueError("unit must be one of {'m','km'}")

    # Initialize lists to store data
    resolutions = []
    num_cells_list = []
    avg_edge_lens = []
    avg_cell_areas = []
    cls_list = []
    for res in range(min_res, max_res + 1):
        num_cells, avg_edge_len, avg_cell_area, cls = tilecode_metrics(res, unit=unit)
        resolutions.append(res)
        num_cells_list.append(num_cells)
        avg_edge_lens.append(avg_edge_len)
        avg_cell_areas.append(avg_cell_area)
        cls_list.append(cls)
    # Create DataFrame
    # Build column labels with unit awareness (lower case)
    avg_edge_len = f"avg_edge_len_{unit}"
    unit_area_label = {"m": "m2", "km": "km2"}[unit]
    avg_cell_area = f"avg_cell_area_{unit_area_label}"
    cls_label = f"cls_{unit}"
    df = pd.DataFrame(
        {
            "resolution": resolutions,
            "number_of_cells": num_cells_list,
            avg_edge_len: avg_edge_lens,
            avg_cell_area: avg_cell_areas,
            cls_label: cls_list,
        }
    )

    return df

tilecodeinspect(resolution, verbose=True)

Generate comprehensive inspection data for Tilecode DGGS cells at a given resolution.

This function creates a detailed analysis of Tilecode cells including area variations, compactness measures, and dateline crossing detection.

Parameters:

Name	Type	Description	Default
resolution	int	Tilecode resolution level (0-29)	required
verbose		Show progress bars. Defaults to True.	True

Source code in vgrid/stats/tilecodestats.py

def tilecodeinspect(resolution: int, verbose=True):
    """
    Generate comprehensive inspection data for Tilecode DGGS cells at a given resolution.

    This function creates a detailed analysis of Tilecode cells including area variations,
    compactness measures, and dateline crossing detection.

    Args:
        resolution: Tilecode resolution level (0-29)

        verbose: Show progress bars. Defaults to True.
    Returns:
        geopandas.GeoDataFrame: DataFrame containing Tilecode cell inspection data with columns:
            - tilecode: Tilecode cell ID
            - resolution: Resolution level
            - geometry: Cell geometry
            - cell_area: Cell area in square meters
            - cell_perimeter: Cell perimeter in meters
            - crossed: Whether cell crosses the dateline
            - norm_area: Normalized area (cell_area / mean_area)
            - ipq: Isoperimetric Quotient compactness
            - zsc: Zonal Standardized Compactness
    """
    tilecode_gdf = tilecodegrid(resolution, output_format="gpd", verbose=verbose)
    tilecode_gdf["crossed"] = tilecode_gdf["geometry"].apply(check_crossing_geom)
    # mean_area = tilecode_gdf["cell_area"].mean()
    num_cells = 4**resolution
    mean_area = AUTHALIC_AREA / num_cells
    # Calculate normalized area
    tilecode_gdf["norm_area"] = tilecode_gdf["cell_area"] / mean_area
    # Calculate IPQ compactness using the standard formula: CI = 4πA/P²
    tilecode_gdf["ipq"] = (
        4 * np.pi * tilecode_gdf["cell_area"] / (tilecode_gdf["cell_perimeter"] ** 2)
    )
    # Calculate zonal standardized compactness
    tilecode_gdf["zsc"] = (
        np.sqrt(
            4 * np.pi * tilecode_gdf["cell_area"]
            - np.power(tilecode_gdf["cell_area"], 2) / np.power(6378137, 2)
        )
        / tilecode_gdf["cell_perimeter"]
    )

    # Compute convex hull using Lambert Azimuthal Equal Area projection
    convex_hull = tilecode_gdf["geometry"].apply(convexhull_from_lambert)
    # Calculate convex hull area using Lambert projection
    convex_hull_area = convex_hull.apply(
        lambda g: get_area_perimeter_from_lambert(g)[0] if g is not None else np.nan
    )
    # Calculate cell area using Lambert projection for consistent cvh calculation
    tilecode_gdf_lambert = get_cells_area(tilecode_gdf.copy(), "LAEA")
    # Compute CVH safely; set to NaN where convex hull area is non-positive or invalid
    tilecode_gdf["cvh"] = np.where(
        (convex_hull_area > 0) & np.isfinite(convex_hull_area),
        tilecode_gdf_lambert["area"] / convex_hull_area,
        np.nan,
    )
    # Replace any accidental inf values with NaN
    tilecode_gdf["cvh"] = tilecode_gdf["cvh"].replace([np.inf, -np.inf], np.nan)

    return tilecode_gdf

This module provides functions for generating statistics for Quadkey DGGS cells.

quadkeystats(unit='m')

Generate statistics for Quadkey DGGS cells.

Parameters:

Name	Type	Description	Default
unit	str	'm' or 'km' for length; area will be 'm^2' or 'km^2'	'm'

Returns:

Type	Description
	pandas.DataFrame: DataFrame containing Quadkey DGGS statistics with columns: - resolution: Resolution level (0-30) - number_of_cells: Number of cells at each resolution - avg_edge_len_{unit}: Average edge length in the given unit - avg_cell_area_{unit}2: Average cell area in the squared unit

Source code in vgrid/stats/quadkeystats.py

def quadkeystats(unit: str = "m"):  # length unit is km, area unit is km2
    """
    Generate statistics for Quadkey DGGS cells.

    Args:
        unit: 'm' or 'km' for length; area will be 'm^2' or 'km^2'

    Returns:
        pandas.DataFrame: DataFrame containing Quadkey DGGS statistics with columns:
            - resolution: Resolution level (0-30)
            - number_of_cells: Number of cells at each resolution
            - avg_edge_len_{unit}: Average edge length in the given unit
            - avg_cell_area_{unit}2: Average cell area in the squared unit
    """
    # normalize and validate unit
    unit = unit.strip().lower()
    if unit not in {"m", "km"}:
        raise ValueError("unit must be one of {'m','km'}")

    # Initialize lists to store data
    resolutions = []
    num_cells_list = []
    avg_edge_lens = []
    avg_cell_areas = []
    cls_list = []
    for res in range(min_res, max_res + 1):
        num_cells, avg_edge_len, avg_cell_area, cls = quadkey_metrics(
            res, unit=unit
        )  # length unit is km, area unit is km2
        resolutions.append(res)
        num_cells_list.append(num_cells)
        avg_edge_lens.append(avg_edge_len)
        avg_cell_areas.append(avg_cell_area)
        cls_list.append(cls)
    # Create DataFrame
    # Build column labels with unit awareness (lower case)
    avg_edge_len = f"avg_edge_len_{unit}"
    unit_area_label = {"m": "m2", "km": "km2"}[unit]
    avg_cell_area = f"avg_cell_area_{unit_area_label}"
    cls_label = f"cls_{unit}"
    df = pd.DataFrame(
        {
            "resolution": resolutions,
            "number_of_cells": num_cells_list,
            avg_edge_len: avg_edge_lens,
            avg_cell_area: avg_cell_areas,
            cls_label: cls_list,
        }
    )

    return df

quadkeyinspect(resolution, verbose=True)

Generate comprehensive inspection data for Quadkey DGGS cells at a given resolution.

This function creates a detailed analysis of Quadkey cells including area variations, compactness measures, and dateline crossing detection.

Parameters:

Name	Type	Description	Default
resolution	int	Quadkey resolution level (0-29)	required
verbose		Show progress bars. Defaults to True.	True

Source code in vgrid/stats/quadkeystats.py

def quadkeyinspect(resolution: int, verbose=True):
    """
    Generate comprehensive inspection data for Quadkey DGGS cells at a given resolution.

    This function creates a detailed analysis of Quadkey cells including area variations,
    compactness measures, and dateline crossing detection.

    Args:
        resolution: Quadkey resolution level (0-29)

        verbose: Show progress bars. Defaults to True.
    Returns:
        geopandas.GeoDataFrame: DataFrame containing Quadkey cell inspection data with columns:
            - quadkey: Quadkey cell ID
            - resolution: Resolution level
            - geometry: Cell geometry
            - cell_area: Cell area in square meters
            - cell_perimeter: Cell perimeter in meters
            - crossed: Whether cell crosses the dateline
            - norm_area: Normalized area (cell_area / mean_area)
            - ipq: Isoperimetric Quotient compactness
            - zsc: Zonal Standardized Compactness
    """
    quadkey_gdf = quadkeygrid(resolution, output_format="gpd", verbose=verbose)
    quadkey_gdf["crossed"] = quadkey_gdf["geometry"].apply(check_crossing_geom)
    # mean_area = quadkey_gdf["cell_area"].mean()
    num_cells = 4**resolution
    mean_area = AUTHALIC_AREA / num_cells
    # Calculate normalized area
    quadkey_gdf["norm_area"] = quadkey_gdf["cell_area"] / mean_area
    # Calculate IPQ compactness using the standard formula: CI = 4πA/P²
    quadkey_gdf["ipq"] = (
        4 * np.pi * quadkey_gdf["cell_area"] / (quadkey_gdf["cell_perimeter"] ** 2)
    )
    # Calculate zonal standardized compactness
    quadkey_gdf["zsc"] = (
        np.sqrt(
            4 * np.pi * quadkey_gdf["cell_area"]
            - np.power(quadkey_gdf["cell_area"], 2) / np.power(6378137, 2)
        )
        / quadkey_gdf["cell_perimeter"]
    )

    # Compute convex hull using Lambert Azimuthal Equal Area projection
    convex_hull = quadkey_gdf["geometry"].apply(convexhull_from_lambert)
    # Calculate convex hull area using Lambert projection
    convex_hull_area = convex_hull.apply(
        lambda g: get_area_perimeter_from_lambert(g)[0] if g is not None else np.nan
    )
    # Calculate cell area using Lambert projection for consistent cvh calculation
    quadkey_gdf_lambert = get_cells_area(quadkey_gdf.copy(), "LAEA")
    # Compute CVH safely; set to NaN where convex hull area is non-positive or invalid
    quadkey_gdf["cvh"] = np.where(
        (convex_hull_area > 0) & np.isfinite(convex_hull_area),
        quadkey_gdf_lambert["area"] / convex_hull_area,
        np.nan,
    )
    # Replace any accidental inf values with NaN
    quadkey_gdf["cvh"] = quadkey_gdf["cvh"].replace([np.inf, -np.inf], np.nan)

    return quadkey_gdf

This module provides functions for generating statistics for Maidenhead DGGS cells.

maidenheadstats(unit='m')

Generate statistics for Maidenhead DGGS cells.

Parameters:

Name	Type	Description	Default
unit	str	'm' or 'km' for length; area will be 'm^2' or 'km^2'	'm'

Returns:

Type	Description
	pandas.DataFrame: DataFrame containing Maidenhead DGGS statistics with columns: - resolution: Resolution level (0-4) - number_of_cells: Number of cells at each resolution - avg_edge_len_{unit}: Average edge length in the given unit - avg_cell_area_{unit}2: Average cell area in the squared unit

Source code in vgrid/stats/maidenheadstats.py

def maidenheadstats(unit: str = "m"):  # length unit is km, area unit is km2
    """
    Generate statistics for Maidenhead DGGS cells.

    Args:
        unit: 'm' or 'km' for length; area will be 'm^2' or 'km^2'

    Returns:
        pandas.DataFrame: DataFrame containing Maidenhead DGGS statistics with columns:
            - resolution: Resolution level (0-4)
            - number_of_cells: Number of cells at each resolution
            - avg_edge_len_{unit}: Average edge length in the given unit
            - avg_cell_area_{unit}2: Average cell area in the squared unit
    """
    # normalize and validate unit
    unit = unit.strip().lower()
    if unit not in {"m", "km"}:
        raise ValueError("unit must be one of {'m','km'}")

    # Initialize lists to store data
    resolutions = []
    num_cells_list = []
    avg_edge_lens = []
    avg_cell_areas = []
    cls_list = []
    for res in range(min_res, max_res + 1):
        num_cells, avg_edge_len, avg_cell_area, cls = maidenhead_metrics(
            res, unit=unit
        )  # length unit is km, area unit is km2
        resolutions.append(res)
        num_cells_list.append(num_cells)
        avg_edge_lens.append(avg_edge_len)
        avg_cell_areas.append(avg_cell_area)
        cls_list.append(cls)
    # Create DataFrame
    # Build column labels with unit awareness (lower case)
    avg_edge_len = f"avg_edge_len_{unit}"
    unit_area_label = {"m": "m2", "km": "km2"}[unit]
    avg_cell_area = f"avg_cell_area_{unit_area_label}"
    cls_label = f"cls_{unit}"
    df = pd.DataFrame(
        {
            "resolution": resolutions,
            "number_of_cells": num_cells_list,
            avg_edge_len: avg_edge_lens,
            avg_cell_area: avg_cell_areas,
            cls_label: cls_list,
        }
    )

    return df

maidenheadinspect(resolution, verbose=True)

Generate comprehensive inspection data for Maidenhead DGGS cells at a given resolution.

This function creates a detailed analysis of Maidenhead cells including area variations, compactness measures, and dateline crossing detection.

Parameters:

Name	Type	Description	Default
resolution	int	Maidenhead resolution level (1-4)	required
verbose		Show progress bars. Defaults to True.	True

Source code in vgrid/stats/maidenheadstats.py

def maidenheadinspect(resolution: int, verbose=True):
    """
    Generate comprehensive inspection data for Maidenhead DGGS cells at a given resolution.

    This function creates a detailed analysis of Maidenhead cells including area variations,
    compactness measures, and dateline crossing detection.

    Args:
        resolution: Maidenhead resolution level (1-4)

        verbose: Show progress bars. Defaults to True.
    Returns:
        geopandas.GeoDataFrame: DataFrame containing Maidenhead cell inspection data with columns:
            - maidenhead: Maidenhead cell ID
            - resolution: Resolution level
            - geometry: Cell geometry
            - cell_area: Cell area in square meters
            - cell_perimeter: Cell perimeter in meters
            - crossed: Whether cell crosses the dateline
            - norm_area: Normalized area (cell_area / mean_area)
            - ipq: Isoperimetric Quotient compactness
            - zsc: Zonal Standardized Compactness
    """
    resolution = validate_maidenhead_resolution(resolution)
    maidenhead_gdf = maidenheadgrid(resolution, output_format="gpd", verbose=verbose)
    maidenhead_gdf["crossed"] = maidenhead_gdf["geometry"].apply(check_crossing_geom)
    # mean_area = maidenhead_gdf["cell_area"].mean()
    mean_area = AUTHALIC_AREA / maidenhead.num_cells(resolution)
    # Calculate normalized area
    maidenhead_gdf["norm_area"] = maidenhead_gdf["cell_area"] / mean_area
    # Calculate IPQ compactness using the standard formula: CI = 4πA/P²
    maidenhead_gdf["ipq"] = (
        4
        * np.pi
        * maidenhead_gdf["cell_area"]
        / (maidenhead_gdf["cell_perimeter"] ** 2)
    )
    # Calculate zonal standardized compactness
    maidenhead_gdf["zsc"] = (
        np.sqrt(
            4 * np.pi * maidenhead_gdf["cell_area"]
            - np.power(maidenhead_gdf["cell_area"], 2) / np.power(6378137, 2)
        )
        / maidenhead_gdf["cell_perimeter"]
    )

    # Compute convex hull using Lambert Azimuthal Equal Area projection
    convex_hull = maidenhead_gdf["geometry"].apply(convexhull_from_lambert)
    # Calculate convex hull area using Lambert projection
    convex_hull_area = convex_hull.apply(
        lambda g: get_area_perimeter_from_lambert(g)[0] if g is not None else np.nan
    )
    # Calculate cell area using Lambert projection for consistent cvh calculation
    maidenhead_gdf_lambert = get_cells_area(maidenhead_gdf.copy(), "LAEA")
    # Compute CVH safely; set to NaN where convex hull area is non-positive or invalid
    maidenhead_gdf["cvh"] = np.where(
        (convex_hull_area > 0) & np.isfinite(convex_hull_area),
        maidenhead_gdf_lambert["area"] / convex_hull_area,
        np.nan,
    )
    # Replace any accidental inf values with NaN
    maidenhead_gdf["cvh"] = maidenhead_gdf["cvh"].replace([np.inf, -np.inf], np.nan)

    return maidenhead_gdf

This module provides functions for generating statistics for GARS DGGS cells.

garsstats(unit='m')

Generate statistics for GARS DGGS cells.

Parameters:

Name	Type	Description	Default
unit	str	'm' or 'km' for length; area will be 'm^2' or 'km^2'	'm'

Returns:

Type	Description
	pandas.DataFrame: DataFrame containing GARS DGGS statistics with columns: - resolution: Resolution level (0-4) - number_of_cells: Number of cells at each resolution - avg_edge_len_{unit}: Average edge length in the given unit - avg_cell_area_{unit}2: Average cell area in the squared unit

Source code in vgrid/stats/garsstats.py

def garsstats(unit: str = "m"):  # length unit is km, area unit is km2
    """
    Generate statistics for GARS DGGS cells.

    Args:
        unit: 'm' or 'km' for length; area will be 'm^2' or 'km^2'

    Returns:
        pandas.DataFrame: DataFrame containing GARS DGGS statistics with columns:
            - resolution: Resolution level (0-4)
            - number_of_cells: Number of cells at each resolution
            - avg_edge_len_{unit}: Average edge length in the given unit
            - avg_cell_area_{unit}2: Average cell area in the squared unit
    """
    # normalize and validate unit
    unit = unit.strip().lower()
    if unit not in {"m", "km"}:
        raise ValueError("unit must be one of {'m','km'}")

    # Initialize lists to store data
    resolutions = []
    num_cells_list = []
    avg_edge_lens = []
    avg_cell_areas = []
    cls_list = []
    for res in range(min_res, max_res + 1):
        num_cells, avg_edge_len, avg_cell_area, cls = gars_metrics(
            res, unit=unit
        )  # length unit is km, area unit is km2
        resolutions.append(res)
        num_cells_list.append(num_cells)
        avg_edge_lens.append(avg_edge_len)
        avg_cell_areas.append(avg_cell_area)
        cls_list.append(cls)
    # Create DataFrame
    # Build column labels with unit awareness (lower case)
    avg_edge_len = f"avg_edge_len_{unit}"
    unit_area_label = {"m": "m2", "km": "km2"}[unit]
    avg_cell_area = f"avg_cell_area_{unit_area_label}"
    cls_label = f"cls_{unit}"
    df = pd.DataFrame(
        {
            "resolution": resolutions,
            "number_of_cells": num_cells_list,
            avg_edge_len: avg_edge_lens,
            avg_cell_area: avg_cell_areas,
            cls_label: cls_list,
        }
    )

    return df

garsinspect(resolution, verbose=True)

Generate comprehensive inspection data for GARS DGGS cells at a given resolution.

This function creates a detailed analysis of GARS cells including area variations, compactness measures, and Antimeridian crossing detection.

Parameters:

Name	Type	Description	Default
resolution	int	GARS resolution level (0-4)	required
verbose		Show progress bars. Defaults to True.	True

Source code in vgrid/stats/garsstats.py

def garsinspect(resolution: int, verbose=True):  # length unit is km, area unit is km2
    """
    Generate comprehensive inspection data for GARS DGGS cells at a given resolution.

    This function creates a detailed analysis of GARS cells including area variations,
    compactness measures, and Antimeridian crossing detection.

    Args:
        resolution: GARS resolution level (0-4)

        verbose: Show progress bars. Defaults to True.
    Returns:
        geopandas.GeoDataFrame: DataFrame containing GARS cell inspection data with columns:
            - gars: GARS cell ID
            - resolution: Resolution level
            - geometry: Cell geometry
            - cell_area: Cell area in square meters
            - cell_perimeter: Cell perimeter in meters
            - crossed: Whether cell crosses the Antimeridian
            - norm_area: Normalized area (cell_area / mean_area)
            - ipq: Isoperimetric Quotient compactness
            - zsc: Zonal Standardized Compactness
    """
    gars_gdf = garsgrid(resolution, output_format="gpd", verbose=verbose)
    gars_gdf["crossed"] = gars_gdf["geometry"].apply(check_crossing_geom)
    # mean_area = gars_gdf["cell_area"].mean()
    mean_area = AUTHALIC_AREA / gars_num_cells(resolution)
    # Calculate normalized area
    gars_gdf["norm_area"] = gars_gdf["cell_area"] / mean_area
    # Calculate IPQ compactness using the standard formula: CI = 4πA/P²
    gars_gdf["ipq"] = (
        4 * np.pi * gars_gdf["cell_area"] / (gars_gdf["cell_perimeter"] ** 2)
    )
    # Calculate zonal standardized compactness
    gars_gdf["zsc"] = (
        np.sqrt(
            4 * np.pi * gars_gdf["cell_area"]
            - np.power(gars_gdf["cell_area"], 2) / np.power(6378137, 2)
        )
        / gars_gdf["cell_perimeter"]
    )

    # Compute convex hull using Lambert Azimuthal Equal Area projection
    convex_hull = gars_gdf["geometry"].apply(convexhull_from_lambert)
    # Calculate convex hull area using Lambert projection
    convex_hull_area = convex_hull.apply(
        lambda g: get_area_perimeter_from_lambert(g)[0] if g is not None else np.nan
    )
    # Calculate cell area using Lambert projection for consistent cvh calculation
    gars_gdf_lambert = get_cells_area(gars_gdf.copy(), "LAEA")
    # Compute CVH safely; set to NaN where convex hull area is non-positive or invalid
    gars_gdf["cvh"] = np.where(
        (convex_hull_area > 0) & np.isfinite(convex_hull_area),
        gars_gdf_lambert["area"] / convex_hull_area,
        np.nan,
    )
    # Replace any accidental inf values with NaN
    gars_gdf["cvh"] = gars_gdf["cvh"].replace([np.inf, -np.inf], np.nan)

    return gars_gdf

This module provides functions for generating statistics for DIGIPIN DGGS cells.

digipinstats(unit='m')

Generate statistics for DIGIPIN DGGS cells.

Parameters:

Name	Type	Description	Default
unit	str	'm' or 'km' for length; area will be 'm^2' or 'km^2'	'm'

Returns:

Type	Description
	pandas.DataFrame: DataFrame containing DIGIPIN DGGS statistics with columns: - resolution: Resolution level (1-10) - number_of_cells: Number of cells at each resolution - avg_edge_len_{unit}: Average edge length in the given unit - avg_cell_area_{unit}2: Average cell area in the squared unit - cls_{unit}: Characteristic length scale in the given unit

Source code in vgrid/stats/digipinstats.py

def digipinstats(unit: str = "m"):  # length unit is km, area unit is km2
    """
    Generate statistics for DIGIPIN DGGS cells.

    Args:
        unit: 'm' or 'km' for length; area will be 'm^2' or 'km^2'

    Returns:
        pandas.DataFrame: DataFrame containing DIGIPIN DGGS statistics with columns:
            - resolution: Resolution level (1-10)
            - number_of_cells: Number of cells at each resolution
            - avg_edge_len_{unit}: Average edge length in the given unit
            - avg_cell_area_{unit}2: Average cell area in the squared unit
            - cls_{unit}: Characteristic length scale in the given unit
    """
    # normalize and validate unit
    unit = unit.strip().lower()
    if unit not in {"m", "km"}:
        raise ValueError("unit must be one of {'m','km'}")

    # Initialize lists to store data
    resolutions = []
    num_cells_list = []
    avg_edge_lens = []
    avg_cell_areas = []
    cls_list = []
    for res in range(min_res, max_res + 1):
        num_cells, avg_edge_len, avg_cell_area, cls = digipin_metrics(
            res, unit=unit
        )  # length unit is km, area unit is km2
        resolutions.append(res)
        num_cells_list.append(num_cells)
        avg_edge_lens.append(avg_edge_len)
        avg_cell_areas.append(avg_cell_area)
        cls_list.append(cls)
    # Create DataFrame
    # Build column labels with unit awareness (lower case)
    avg_edge_len = f"avg_edge_len_{unit}"
    unit_area_label = {"m": "m2", "km": "km2"}[unit]
    avg_cell_area = f"avg_cell_area_{unit_area_label}"
    cls_label = f"cls_{unit}"
    df = pd.DataFrame(
        {
            "resolution": resolutions,
            "number_of_cells": num_cells_list,
            avg_edge_len: avg_edge_lens,
            avg_cell_area: avg_cell_areas,
            cls_label: cls_list,
        }
    )

    return df

digipininspect(resolution, verbose=True)

Generate comprehensive inspection data for DIGIPIN DGGS cells at a given resolution.

This function creates a detailed analysis of DIGIPIN cells including area variations, compactness measures, and Antimeridian crossing detection.

Parameters:

Name	Type	Description	Default
resolution		DIGIPIN resolution level (1-10)	required
verbose		Show progress bars. Defaults to True.	True

Source code in vgrid/stats/digipinstats.py

def digipininspect(resolution, verbose=True):
    """
    Generate comprehensive inspection data for DIGIPIN DGGS cells at a given resolution.

    This function creates a detailed analysis of DIGIPIN cells including area variations,
    compactness measures, and Antimeridian crossing detection.

    Args:
        resolution: DIGIPIN resolution level (1-10)

        verbose: Show progress bars. Defaults to True.
    Returns:
        geopandas.GeoDataFrame: DataFrame containing DIGIPIN cell inspection data with columns:
            - digipin: DIGIPIN cell ID
            - resolution: Resolution level
            - geometry: Cell geometry
            - cell_area: Cell area in square meters
            - cell_perimeter: Cell perimeter in meters
            - crossed: Whether cell crosses the Antimeridian
            - norm_area: Normalized area (cell_area / mean_area)
            - ipq: Isoperimetric Quotient compactness
            - zsc: Zonal Standardized Compactness
            - cvh: Convex Hull compactness
    """
    resolution = validate_digipin_resolution(resolution)
    digipin_gdf = digipingrid(resolution, output_format="gpd", verbose=verbose)
    digipin_gdf["crossed"] = digipin_gdf["geometry"].apply(check_crossing_geom)
    # mean_area = digipin_gdf["cell_area"].mean()
    num_cells = 16**resolution
    mean_area = DIGIPIN_AREA / num_cells
    # Calculate normalized area
    digipin_gdf["norm_area"] = digipin_gdf["cell_area"] / mean_area
    # Calculate IPQ compactness using the standard formula: CI = 4πA/P²
    digipin_gdf["ipq"] = (
        4 * np.pi * digipin_gdf["cell_area"] / (digipin_gdf["cell_perimeter"] ** 2)
    )
    # Calculate zonal standardized compactness
    digipin_gdf["zsc"] = (
        np.sqrt(
            4 * np.pi * digipin_gdf["cell_area"]
            - np.power(digipin_gdf["cell_area"], 2) / np.power(6378137, 2)
        )
        / digipin_gdf["cell_perimeter"]
    )

    # Compute convex hull using Lambert Azimuthal Equal Area projection
    convex_hull = digipin_gdf["geometry"].apply(convexhull_from_lambert)
    # Calculate convex hull area using Lambert projection
    convex_hull_area = convex_hull.apply(
        lambda g: get_area_perimeter_from_lambert(g)[0] if g is not None else np.nan
    )
    # Calculate cell area using Lambert projection for consistent cvh calculation
    digipin_gdf_lambert = get_cells_area(digipin_gdf.copy(), "LAEA")
    # Compute CVH safely; set to NaN where convex hull area is non-positive or invalid
    digipin_gdf["cvh"] = np.where(
        (convex_hull_area > 0) & np.isfinite(convex_hull_area),
        digipin_gdf_lambert["area"] / convex_hull_area,
        np.nan,
    )
    # Replace any accidental inf values with NaN
    digipin_gdf["cvh"] = digipin_gdf["cvh"].replace([np.inf, -np.inf], np.nan)

    return digipin_gdf