Skip to content

Statistics Module

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

Overview

The statistics module enables:

  • Cell Count Analysis: Calculate the number of cells at each resolution
  • Area Calculations: Determine average cell areas for each resolution
  • Edge Length Analysis: Calculate average edge lengths for grid cells

Supported DGGS Systems

The statistics module supports comprehensive analysis of all major DGGS systems:

  • H3: Uber's hexagonal hierarchical geospatial indexing system
  • S2: Google's spherical geometry library
  • A5: Pentagonal DGGS
  • RHEALPix: Equal-area hierarchical triangular mesh
  • ISEA4T: Icosahedral Snyder Equal Area Aperture 4 Triangle
  • ISEA3H: Icosahedral Snyder Equal Area Aperture 3 Hexagon
  • EASE: Equal-Area Scalable Earth Grid
  • QTM: Quaternary Triangular Mesh
  • OLC: Open Location Code (Plus Codes)
  • Geohash: Hierarchical spatial data structure
  • GEOREF: World Geographic Reference System
  • MGRS: Military Grid Reference System
  • Tilecode: Hierarchical tiling system
  • Quadkey: Microsoft's hierarchical spatial index
  • Maidenhead: Amateur radio grid square system
  • GARS: Global Area Reference System
  • DGGAL: External DGGS family accessed via the dgg CLI (e.g., GNOSIS, ISEA3H/9R, IVEA3H/9R, RTEA3H/9R, RHEALPix)

Key Metrics

Cell Counts

  • Total number of cells at each resolution
  • Hierarchical cell relationships
  • Global coverage statistics

Area Analysis

  • Average cell area in square meters
  • Area consistency across resolutions
  • Equal-area vs. non-equal-area systems

Edge Lengths

  • Average edge length in meters
  • Edge length consistency
  • Geometric properties

Usage Examples

H3 Statistics

1
2
3
4
from vgrid.stats import h3_stats

# Display H3 statistics in terminal
h3_stats()

S2 Metrics

1
2
3
4
from vgrid.stats import s2_metrics

# Get S2 metrics for resolution 15
num_cells, edge_length, cell_area = s2_metrics(15)

RHEALPix Statistics

1
2
3
4
from vgrid.stats import rhealpix_stats

# Display RHEALPix statistics
rhealpix_stats()

DGGAL Statistics

1
2
3
4
5
6
from vgrid.stats import dggalstats

# Get DGGAL statistics (DataFrame) for a specific model
# Available types include: "gnosis", "isea3h", "isea9r", "ivea3h", "ivea9r", "rtea3h", "rtea9r", "rhealpix"
df = dggalstats("isea3h", unit="m")
print(df.head())

Compare Multiple Systems

1
2
3
4
5
6
from vgrid.stats import h3_metrics, s2_metrics, rhealpix_metrics

# Compare cell areas at equivalent resolutions
h3_cells, h3_edge, h3_area = h3_metrics(8)
s2_cells, s2_edge, s2_area = s2_metrics(15)
rhp_cells, rhp_edge, rhp_area = rhealpix_metrics(10)

Output Formats

Statistics can be displayed in multiple formats:

  • Terminal Tables: Dataframe for console display
  • Metrics Arrays: Python arrays for programmatic use

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_metrics(res, unit='m')

Calculate metrics for A5 DGGS cells at a given resolution.

Parameters:

Name Type Description Default
res

Resolution level (0-29)

 required
unit str

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

 'm'

Returns:

Name Type Description
tuple

(num_cells, edge_length_in_unit, cell_area_in_unit_squared)
Source code in vgrid/stats/a5stats.py 
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
def a5_metrics(res, unit: str = "m"):
    """
    Calculate metrics for A5 DGGS cells at a given resolution.

    Args:
        res: Resolution level (0-29)
        unit: 'm' or 'km' for length; area will be 'm^2' or 'km^2'

    Returns:
        tuple: (num_cells, edge_length_in_unit, cell_area_in_unit_squared)
    """
    # normalize and validate unit
    unit = unit.strip().lower()
    if unit not in {"m", "km"}:
        raise ValueError("unit must be one of {'m','km'}")

    num_cells = get_num_cells(res)
    avg_cell_area_m2 = cell_area(res)  # Assuming cell_area returns area in m²

    # Calculate edge length in meters
    k = math.sqrt(5*(5+2*math.sqrt(5)))
    avg_edge_len_m = round(math.sqrt(4*avg_cell_area_m2/k), 3)

    # Convert to requested unit
    if unit == "km":
        avg_edge_len = avg_edge_len_m / 1000.0
        avg_cell_area = avg_cell_area_m2 / (1000.0 ** 2)
    else:  # unit == "m"
        avg_edge_len = avg_edge_len_m
        avg_cell_area = avg_cell_area_m2

    return num_cells, avg_edge_len, avg_cell_area

gars_metrics(res, unit='m')

Calculate metrics for GARS DGGS cells.

Parameters:

Name Type Description Default
res

Resolution level (0-4)

 required
unit str

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

 'm'

Returns:

Name Type Description
tuple

(num_cells, avg_edge_len_in_unit, avg_cell_area_in_unit_squared)
Source code in vgrid/stats/garsstats.py 
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
def gars_metrics(res, unit: str = "m"):
    """
    Calculate metrics for GARS DGGS cells.

    Args:
        res: Resolution level (0-4)
        unit: 'm' or 'km' for length; area will be 'm^2' or 'km^2'

    Returns:
        tuple: (num_cells, avg_edge_len_in_unit, avg_cell_area_in_unit_squared)
    """
    # normalize and validate unit
    unit = unit.strip().lower()
    if unit not in {"m", "km"}:
        raise ValueError("unit must be one of {'m','km'}")

    # GARS grid has 43200 (180x240) cells at base level
    # Each subdivision adds 10x10 = 100 cells per parent cell
    num_cells = gars_num_cells(res) 
    # Calculate area in km² first
    avg_cell_area_km2 = AUTHALIC_AREA / num_cells
    avg_edge_len_km = math.sqrt(avg_cell_area_km2)

    # Convert to requested unit
    if unit == "m":
        avg_cell_area = avg_cell_area_km2 * (10**6)  # Convert km² to m²
        avg_edge_len = avg_edge_len_km * 1000  # Convert km to m
    else:  # unit == "km"
        avg_cell_area = avg_cell_area_km2
        avg_edge_len = avg_edge_len_km

    return num_cells, avg_edge_len, avg_cell_area

geohash_metrics(res, unit='m')

Calculate metrics for Geohash DGGS cells.

Parameters:

Name Type Description Default
res

Resolution level (0-12)

 required
unit str

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

 'm'

Returns:

Name Type Description
tuple

(num_cells, avg_edge_len_in_unit, avg_cell_area_in_unit_squared)
Source code in vgrid/stats/geohashstats.py 
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
def geohash_metrics(res, unit: str = "m"):
    """
    Calculate metrics for Geohash DGGS cells.

    Args:
        res: Resolution level (0-12)
        unit: 'm' or 'km' for length; area will be 'm^2' or 'km^2'

    Returns:
        tuple: (num_cells, avg_edge_len_in_unit, avg_cell_area_in_unit_squared)
    """
    # normalize and validate unit
    unit = unit.strip().lower()
    if unit not in {"m", "km"}:
        raise ValueError("unit must be one of {'m','km'}")

    num_cells = 32 ** res

    # Calculate area in km² first
    avg_cell_area_km2 = AUTHALIC_AREA / num_cells
    avg_edge_len_km = math.sqrt(avg_cell_area_km2)

    # Convert to requested unit
    if unit == "m":
        avg_cell_area = avg_cell_area_km2 * (10**6)  # Convert km² to m²
        avg_edge_len = avg_edge_len_km * 1000  # Convert km to m
    else:  # unit == "km"
        avg_cell_area = avg_cell_area_km2
        avg_edge_len = avg_edge_len_km

    return num_cells, avg_edge_len, avg_cell_area

georef_metrics(res, unit='m')

Calculate metrics for GEOREF DGGS cells.

Parameters:

Name Type Description Default
res int

Resolution level (0-7)

 required
unit str

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

 'm'

Returns:

Name Type Description
tuple

(num_cells, avg_edge_len_in_unit, avg_cell_area_in_unit_squared)
Source code in vgrid/stats/georefstats.py 
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
def georef_metrics(res: int, unit: str = "m"):
    """
    Calculate metrics for GEOREF DGGS cells.

    Args:
        res: Resolution level (0-7)
        unit: 'm' or 'km' for length; area will be 'm^2' or 'km^2'

    Returns:
        tuple: (num_cells, avg_edge_len_in_unit, avg_cell_area_in_unit_squared)
    """
    # normalize and validate unit
    unit = unit.strip().lower()
    if unit not in {"m", "km"}:
        raise ValueError("unit must be one of {'m','km'}")

    if res < 0:
        raise ValueError("Resolution must be >= 0")

    # Compute grid size in degrees per your formula
    grid_size_deg = GEOREF_RESOLUTION_DEGREES.get(res)

    # Number of cells across longitude and latitude
    num_lon = int(round(360.0 / grid_size_deg))
    num_lat = int(round(180.0 / grid_size_deg))
    num_cells = num_lon * num_lat

    # Calculate area in km² first
    avg_cell_area_km2 = AUTHALIC_AREA / num_cells
    avg_edge_len_km = math.sqrt(avg_cell_area_km2)

    # Convert to requested unit
    if unit == "m":
        avg_cell_area = avg_cell_area_km2 * (10**6)  # Convert km² to m²
        avg_edge_len = avg_edge_len_km * 1000  # Convert km to m
    else:  # unit == "km"
        avg_cell_area = avg_cell_area_km2
        avg_edge_len = avg_edge_len_km

    return num_cells, avg_edge_len, avg_cell_area

isea3h_metrics(res, unit='m')

Calculate metrics for ISEA3H DGGS cells at a given resolution.

Parameters:

Name Type Description Default
res

Resolution level (0-40)

 required
unit str

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

 'm'

Returns:

Name Type Description
tuple

(num_cells, edge_length_in_unit, cell_area_in_unit_squared)
Source code in vgrid/stats/isea3hstats.py 
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
def isea3h_metrics(res, unit: str = "m"):
    """
    Calculate metrics for ISEA3H DGGS cells at a given resolution.

    Args:
        res: Resolution level (0-40)
        unit: 'm' or 'km' for length; area will be 'm^2' or 'km^2'

    Returns:
        tuple: (num_cells, edge_length_in_unit, cell_area_in_unit_squared)
    """
    # normalize and validate unit
    unit = unit.strip().lower()
    if unit not in {"m", "km"}:
        raise ValueError("unit must be one of {'m','km'}")

    base_cells = 20 # Icosahedron faces
    num_cells = base_cells * (7**res)
    avg_cell_area_km2 = AUTHALIC_AREA / num_cells
    avg_edge_len_km = math.sqrt((2 * avg_cell_area_km2) / (3 * math.sqrt(3)))

    if res == 0: # icosahedron faces
        avg_edge_len_km = math.sqrt((4 * avg_cell_area_km2) / math.sqrt(3))

    # Convert to requested unit
    if unit == "m":
        avg_edge_len = avg_edge_len_km * 1000
        avg_cell_area = avg_cell_area_km2 * (10**6)
    else:  # unit == "m"
        avg_edge_len = avg_edge_len_km
        avg_cell_area = avg_cell_area_km2

    return num_cells, avg_edge_len, avg_cell_area

isea4t_metrics(res, unit='m')

Calculate metrics for ISEA4T DGGS cells at a given resolution.

Parameters:

Name Type Description Default
res

Resolution level (0-39)

 required
unit str

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

 'm'

Returns:

Name Type Description
tuple

(num_cells, edge_length_in_unit, cell_area_in_unit_squared)
Source code in vgrid/stats/isea4tstats.py 
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
def isea4t_metrics(res, unit: str = "m"):
    """
    Calculate metrics for ISEA4T DGGS cells at a given resolution.

    Args:
        res: Resolution level (0-39)
        unit: 'm' or 'km' for length; area will be 'm^2' or 'km^2'

    Returns:
        tuple: (num_cells, edge_length_in_unit, cell_area_in_unit_squared)
    """
    # normalize and validate unit
    unit = unit.strip().lower()
    if unit not in {"m", "km"}:
        raise ValueError("unit must be one of {'m','km'}")

    num_cells = 20 * (4**res)
    avg_cell_area_km2 = AUTHALIC_AREA / num_cells
    avg_edge_len_km = math.sqrt((4 * avg_cell_area_km2) / math.sqrt(3))

    # Convert to requested unit
    if unit == "m":
        avg_edge_len = avg_edge_len_km * 1000
        avg_cell_area = avg_cell_area_km2 * (10**6)
    else:  # unit == "km"
        avg_edge_len = avg_edge_len_km * 1000
        avg_cell_area = avg_cell_area_km2 * (10**6)

    return num_cells, avg_edge_len, avg_cell_area

maidenhead_metrics(res, unit='m')

Calculate metrics for Maidenhead DGGS cells.

Parameters:

Name Type Description Default
res

Resolution level (0-4)

 required
unit str

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

 'm'

Returns:

Name Type Description
tuple

(num_cells, avg_edge_len_in_unit, avg_cell_area_in_unit_squared)
Source code in vgrid/stats/maidenheadstats.py 
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
def maidenhead_metrics(res, unit: str = "m"):
    """
    Calculate metrics for Maidenhead DGGS cells.

    Args:
        res: Resolution level (0-4)
        unit: 'm' or 'km' for length; area will be 'm^2' or 'km^2'

    Returns:
        tuple: (num_cells, avg_edge_len_in_unit, avg_cell_area_in_unit_squared)
    """
    # normalize and validate unit
    unit = unit.strip().lower()
    if unit not in {"m", "km"}:
        raise ValueError("unit must be one of {'m','km'}")


    # Maidenhead grid has 324 (18x18) cells at base level
    # Each subdivision adds 10x10 = 100 cells per parent cell
    num_cells = maidenhead.num_cells(res)   

    # Calculate area in km² first
    avg_cell_area_km2 = AUTHALIC_AREA / num_cells
    avg_edge_len_km = math.sqrt(avg_cell_area_km2)

    # Convert to requested unit
    if unit == "m":
        avg_cell_area = avg_cell_area_km2 * (10**6)  # Convert km² to m²
        avg_edge_len = avg_edge_len_km * 1000  # Convert km to m
    else:  # unit == "km"
        avg_cell_area = avg_cell_area_km2
        avg_edge_len = avg_edge_len_km

    return num_cells, avg_edge_len, avg_cell_area

mgrs_metrics(res, unit='m')

Calculate metrics for MGRS DGGS cells.

Parameters:

Name Type Description Default
res

Resolution level (0-5)

 required
unit str

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

 'm'

Returns:

Name Type Description
tuple

(num_cells, avg_edge_len_in_unit, avg_cell_area_in_unit_squared)
Source code in vgrid/stats/mgrsstats.py 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
def mgrs_metrics(res, unit: str = "m"):
    """
    Calculate metrics for MGRS DGGS cells.

    Args:
        res: Resolution level (0-5)
        unit: 'm' or 'km' for length; area will be 'm^2' or 'km^2'

    Returns:
        tuple: (num_cells, avg_edge_len_in_unit, avg_cell_area_in_unit_squared)
    """
    # normalize and validate unit
    unit = unit.strip().lower()
    if unit not in {"m", "km"}:
        raise ValueError("unit must be one of {'m','km'}")

    latitude_degrees = 8  # The latitude span of each GZD cell in degrees
    longitude_degrees = 6  # The longitude span of each GZD cell in degrees
    km_per_degree = 111  # Approximate kilometers per degree of latitude/longitude
    gzd_cells = 1200  # Total number of GZD cells

    # Convert degrees to kilometers
    latitude_span = latitude_degrees * km_per_degree
    longitude_span = longitude_degrees * km_per_degree

    # Calculate cell size in kilometers based on resolution
    # Resolution 1: 100 km, each subsequent resolution divides by 10
    cell_size_km = 100 / (10 ** (res))
    # Calculate number of cells in latitude and longitude for the chosen cell size
    cells_latitude = latitude_span / cell_size_km
    cells_longitude = longitude_span / cell_size_km

    # Total number of cells for each GZD cell
    cells_per_gzd_cell = cells_latitude * cells_longitude

    # Total number of cells for all GZD cells
    num_cells = cells_per_gzd_cell * gzd_cells

    # Convert to requested unit
    if unit == "m":
        avg_edge_len = cell_size_km * 1000  # Convert km to m
        avg_cell_area = avg_edge_len**2
    else:  # unit == "km"
        avg_edge_len = cell_size_km
        avg_cell_area = avg_edge_len**2

    return num_cells, avg_edge_len, avg_cell_area

olc_metrics(res, unit='m')

Calculate metrics for OLC DGGS cells.

Parameters:

Name Type Description Default
res

Resolution level (0-15)

 required
unit str

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

 'm'

Returns:

Name Type Description
tuple

(num_cells, avg_edge_len_in_unit, avg_cell_area_in_unit_squared)
Source code in vgrid/stats/olcstats.py 
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
def olc_metrics(res, unit: str = "m"):
    """
    Calculate metrics for OLC DGGS cells.

    Args:
        res: Resolution level (0-15)
        unit: 'm' or 'km' for length; area will be 'm^2' or 'km^2'

    Returns:
        tuple: (num_cells, avg_edge_len_in_unit, avg_cell_area_in_unit_squared)
    """
    # normalize and validate unit
    unit = unit.strip().lower()
    if unit not in {"m", "km"}:
        raise ValueError("unit must be one of {'m','km'}")


    # Length 2 starts with 162 cells globally
    if res <= 10:
        num_cells = 162 * (400 ** ((res // 2) - 1))
    else:
        # Length > 10: start from length 10 count, multiply by 20 per extra char
        base = 162 * (400 ** ((10 // 2) - 1))  # N(10)
        extra = res - 10
        num_cells = base * (20 ** extra)

    # Calculate area in km² first
    avg_cell_area_km2 = AUTHALIC_AREA / num_cells
    avg_edge_len_km = math.sqrt(avg_cell_area_km2)

    # Convert to requested unit
    if unit == "m":
        avg_cell_area = avg_cell_area_km2 * (10**6)  # Convert km² to m²
        avg_edge_len = avg_edge_len_km * 1000  # Convert km to m
    else:  # unit == "km"
        avg_cell_area = avg_cell_area_km2
        avg_edge_len = avg_edge_len_km

    return num_cells, avg_edge_len, avg_cell_area

qtm_metrics(res, unit='m')

Calculate metrics for QTM DGGS cells.

Parameters:

Name Type Description Default
res

Resolution level (1-24)

 required
unit str

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

 'm'

Returns:

Name Type Description
tuple

(num_cells, avg_edge_len_in_unit, avg_cell_area_in_unit_squared)
Source code in vgrid/stats/qtmstats.py 
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
def qtm_metrics(res, unit: str = "m"):
    """
    Calculate metrics for QTM DGGS cells.

    Args:
        res: Resolution level (1-24)
        unit: 'm' or 'km' for length; area will be 'm^2' or 'km^2'

    Returns:
        tuple: (num_cells, avg_edge_len_in_unit, avg_cell_area_in_unit_squared)
    """
    # normalize and validate unit
    unit = unit.strip().lower()
    if unit not in {"m", "km"}:
        raise ValueError("unit must be one of {'m','km'}")

    earth_surface_area_km2 = AUTHALIC_AREA  # 510.1 million square kilometers
    num_cells = 8 * 4 ** (res - 1)

    # Calculate area in km² first
    avg_cell_area_km2 = AUTHALIC_AREA / num_cells
    avg_edge_len_km = math.sqrt((4 * avg_cell_area_km2) / math.sqrt(3))

    # Convert to requested unit
    if unit == "m":
        avg_cell_area = avg_cell_area_km2 * (10**6)  # Convert km² to m²
        avg_edge_len = avg_edge_len_km * 1000  # Convert km to m
    else:  # unit == "km"
        avg_cell_area = avg_cell_area_km2
        avg_edge_len = avg_edge_len_km

    return num_cells, avg_edge_len, avg_cell_area

quadkey_metrics(res, unit='m')

Calculate metrics for Quadkey DGGS cells.

Parameters:

Name Type Description Default
res

Resolution level (0-30)

 required
unit str

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

 'm'

Returns:

Name Type Description
tuple

(num_cells, avg_edge_len_in_unit, avg_cell_area_in_unit_squared)
Source code in vgrid/stats/quadkeystats.py 
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
def quadkey_metrics(res, unit: str = "m"):
    """
    Calculate metrics for Quadkey DGGS cells.

    Args:
        res: Resolution level (0-30)
        unit: 'm' or 'km' for length; area will be 'm^2' or 'km^2'

    Returns:
        tuple: (num_cells, avg_edge_len_in_unit, avg_cell_area_in_unit_squared)
    """
    # normalize and validate unit
    unit = unit.strip().lower()
    if unit not in {"m", "km"}:
        raise ValueError("unit must be one of {'m','km'}")

    earth_surface_area_km2 = AUTHALIC_AREA  # 510.1 million square kilometers
    num_cells = 4 ** res

    # Calculate area in km² first
    avg_cell_area_km2 = AUTHALIC_AREA / num_cells
    avg_edge_len_km = math.sqrt(avg_cell_area_km2)

    # Convert to requested unit
    if unit == "m":
        avg_cell_area = avg_cell_area_km2 * (10**6)  # Convert km² to m²
        avg_edge_len = avg_edge_len_km * 1000  # Convert km to m
    else:  # unit == "km"
        avg_cell_area = avg_cell_area_km2
        avg_edge_len = avg_edge_len_km

    return num_cells, avg_edge_len, avg_cell_area

rhealpix_metrics(res, unit='m')

Calculate metrics for rHEALPix DGGS cells at a given resolution.

Parameters:

Name Type Description Default
res

Resolution level (0-30)

 required
unit str

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

 'm'

Returns:

Name Type Description
tuple

(num_cells, edge_length_in_unit, cell_area_in_unit_squared)
Source code in vgrid/stats/rhealpixstats.py 
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
def rhealpix_metrics(res, unit: str = "m"):
    """
    Calculate metrics for rHEALPix DGGS cells at a given resolution.

    Args:
        res: Resolution level (0-30)
        unit: 'm' or 'km' for length; area will be 'm^2' or 'km^2'

    Returns:
        tuple: (num_cells, edge_length_in_unit, cell_area_in_unit_squared)
    """
    # normalize and validate unit
    unit = unit.strip().lower()
    if unit not in {"m", "km"}:
        raise ValueError("unit must be one of {'m','km'}")

    num_cells = 6 * 9 ** (res)

    # Calculate area in km² first
    avg_cell_area_km2 = AUTHALIC_AREA / num_cells
    avg_edge_len_km = math.sqrt(avg_cell_area_km2)

    # Convert to requested unit
    if unit == "m":
        avg_cell_area = avg_cell_area_km2 * (10**6)  # Convert km² to m²
        avg_edge_len = avg_edge_len_km * 1000  # Convert km to m
    else:  # unit == "km"
        avg_cell_area = avg_cell_area_km2
        avg_edge_len = avg_edge_len_km

    return num_cells, avg_edge_len, avg_cell_area

s2_metrics(res, unit='m')

Calculate metrics for S2 DGGS cells at a given resolution.

Parameters:

Name Type Description Default
res

Resolution level (0-30)

 required
unit str

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

 'm'

Returns:

Name Type Description
tuple

(num_cells, edge_length_in_unit, cell_area_in_unit_squared)
Source code in vgrid/stats/s2stats.py 
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
def s2_metrics(res, unit: str = "m"):
    """
    Calculate metrics for S2 DGGS cells at a given resolution.

    Args:
        res: Resolution level (0-30)
        unit: 'm' or 'km' for length; area will be 'm^2' or 'km^2'

    Returns:
        tuple: (num_cells, edge_length_in_unit, cell_area_in_unit_squared)
    """
    # normalize and validate unit
    unit = unit.strip().lower()
    if unit not in {"m", "km"}:
        raise ValueError("unit must be one of {'m','km'}")

    num_cells = 6 * (4**res)

    # Calculate area in km² first
    avg_cell_area_km2 = AUTHALIC_AREA / num_cells
    avg_edge_len_km = math.sqrt(avg_cell_area_km2)

    # Convert to requested unit
    if unit == "m":
        avg_cell_area = avg_cell_area_km2 * (10**6)  # Convert km² to m²
        avg_edge_len = avg_edge_len_km * 1000  # Convert km to m
    else:  # unit == "km"
        avg_cell_area = avg_cell_area_km2
        avg_edge_len = avg_edge_len_km

    return num_cells, avg_edge_len, avg_cell_area

tilecode_metrics(res, unit='m')

Calculate metrics for Tilecode DGGS cells.

Parameters:

Name Type Description Default
res

Resolution level (0-30)

 required
unit str

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

 'm'

Returns:

Name Type Description
tuple

(num_cells, avg_edge_len_in_unit, avg_cell_area_in_unit_squared)
Source code in vgrid/stats/tilecodestats.py 
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
def tilecode_metrics(res, unit: str = "m"):
    """
    Calculate metrics for Tilecode DGGS cells.

    Args:
        res: Resolution level (0-30)
        unit: 'm' or 'km' for length; area will be 'm^2' or 'km^2'

    Returns:
        tuple: (num_cells, avg_edge_len_in_unit, avg_cell_area_in_unit_squared)
    """
    # normalize and validate unit
    unit = unit.strip().lower()
    if unit not in {"m", "km"}:
        raise ValueError("unit must be one of {'m','km'}")

    num_cells = 4 ** res

    # Calculate area in km² first
    avg_cell_area_km2 = AUTHALIC_AREA / num_cells
    avg_edge_len_km = math.sqrt(avg_cell_area_km2)

    # Convert to requested unit
    if unit == "m":
        avg_cell_area = avg_cell_area_km2 * (10**6)  # Convert km² to m²
        avg_edge_len = avg_edge_len_km * 1000  # Convert km to m
    else:  # unit == "km"
        avg_cell_area = avg_cell_area_km2
        avg_edge_len = avg_edge_len_km

    return num_cells, avg_edge_len, avg_cell_area