Skip to content

H3Regionalizer

srai.regionalizers.H3Regionalizer(resolution, buffer=True)

Bases: Regionalizer

H3 Regionalizer.

H3 Regionalizer allows the given geometries to be divided into H3 cells - hexagons with pentagons as a very rare exception

PARAMETER DESCRIPTION
resolution

Resolution of the cells. See [1] for a full comparison.

TYPE: int

buffer

Whether to fully cover the geometries with H3 Cells (visible on the borders). Defaults to True.

TYPE: bool DEFAULT: True

RAISES DESCRIPTION
ValueError

If resolution is not between 0 and 15.
References
  1. https://h3geo.org/docs/core-library/restable/
Source code in srai/regionalizers/h3_regionalizer.py 
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
def __init__(self, resolution: int, buffer: bool = True) -> None:
    """
    Init H3Regionalizer.

    Args:
        resolution (int): Resolution of the cells. See [1] for a full comparison.
        buffer (bool, optional): Whether to fully cover the geometries with
            H3 Cells (visible on the borders). Defaults to True.

    Raises:
        ValueError: If resolution is not between 0 and 15.

    References:
        1. https://h3geo.org/docs/core-library/restable/
    """
    if not (0 <= resolution <= 15):
        raise ValueError(f"Resolution {resolution} is not between 0 and 15.")

    self.resolution = resolution
    self.buffer = buffer


transform(gdf)

Regionalize a given GeoDataFrame.

Transforms given geometries into H3 cells of given resolution and optionally applies buffering.

PARAMETER DESCRIPTION
gdf

(Multi)Polygons to be regionalized.

TYPE: GeoDataFrame

RETURNS DESCRIPTION
GeoDataFrame

gpd.GeoDataFrame: H3 cells.
RAISES DESCRIPTION
ValueError

If provided GeoDataFrame has no crs defined.
Source code in srai/regionalizers/h3_regionalizer.py 
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
def transform(self, gdf: gpd.GeoDataFrame) -> gpd.GeoDataFrame:
    """
    Regionalize a given GeoDataFrame.

    Transforms given geometries into H3 cells of given resolution
    and optionally applies buffering.

    Args:
        gdf (gpd.GeoDataFrame): (Multi)Polygons to be regionalized.

    Returns:
        gpd.GeoDataFrame: H3 cells.

    Raises:
        ValueError: If provided GeoDataFrame has no crs defined.
    """
    gdf_wgs84 = gdf.to_crs(crs=WGS84_CRS)

    gdf_exploded = self._explode_multipolygons(gdf_wgs84)

    h3_indexes = list(
        set(
            shapely_geometry_to_h3(
                gdf_exploded[GEOMETRY_COLUMN],
                h3_resolution=self.resolution,
                buffer=self.buffer,
            )
        )
    )
    gdf_h3 = gpd.GeoDataFrame(
        data={REGIONS_INDEX: h3_indexes},
        geometry=h3_to_geoseries(h3_indexes),
        crs=WGS84_CRS,
    ).set_index(REGIONS_INDEX)

    return gdf_h3.to_crs(gdf.crs)