Skip to content

S2Regionalizer

Bases: Regionalizer

S2 Regionalizer.

S2 Regionalizer gives an opportunity to divide the given geometries into square S2 cells.

Source code in srai/regionalizers/s2_regionalizer.py 
 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
 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
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
class S2Regionalizer(Regionalizer):
    """
    S2 Regionalizer.

    S2 Regionalizer gives an opportunity to divide the given geometries into square S2 cells.
    """

    def __init__(self, resolution: int, buffer: bool = True) -> None:
        """
        Init S2 Regionalizer.

        Args:
            resolution (int): Resolution of the cells (S2 supports 0-30). See [1] for
                a full comparison.
            buffer (bool, optional): If True then fully cover geometries with S2 cells.
                Otherwise only use those cells that fully fit into them. Defaults to True.

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

        References:
            1. https://s2geometry.io/resources/s2cell_statistics.html
        """
        if not (0 <= resolution <= 30):
            raise ValueError(f"Resolution {resolution} is not between 0 and 30.")

        self.resolution = resolution
        self.buffer = buffer

    def transform(self, gdf: gpd.GeoDataFrame) -> gpd.GeoDataFrame:
        """
        Regionalize a given GeoDataFrame.

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

        Returns:
            gpd.GeoDataFrame: GeoDataFrame with regionalized geometries.
        """
        gdf_wgs84 = gdf.to_crs(crs=WGS84_CRS)

        s2_gdf = self._fill_with_s2_cells(self._explode_multipolygons(gdf_wgs84))

        # s2 library fills also holes in Polygons, so here we remove redundant cells
        res: gpd.GeoDataFrame = gpd.sjoin(
            s2_gdf,
            gdf_wgs84,
            how="inner",
            predicate="intersects" if self.buffer else "within",
        ).drop(columns=["index_right"])

        res = res[~res.index.duplicated(keep="first")]

        res.index.name = REGIONS_INDEX

        return res

    def _fill_with_s2_cells(self, gdf: gpd.GeoDataFrame) -> gpd.GeoDataFrame:
        geo_json = json.loads(gdf.to_json())
        cells = (
            seq(geo_json["features"])
            .flat_map(lambda f: self._geojson_to_cells(f[GEOMETRY_COLUMN], self.resolution))
            .to_dict()
        )
        cells_gdf = gpd.GeoDataFrame(
            None,
            index=cells.keys(),
            geometry=list(cells.values()),
            crs=WGS84_CRS,
        )

        return cells_gdf

    def _geojson_to_cells(self, geo_json: Dict[str, Any], res: int) -> Sequence:
        raw_cells = s2.polyfill(geo_json, res, with_id=True, geo_json_conformant=True)
        cells: Sequence = seq(raw_cells).map(lambda c: (c["id"], Polygon(c[GEOMETRY_COLUMN])))

        return cells

__init__ 

__init__(resolution: int, buffer: bool = True) -> None

Init S2 Regionalizer.

PARAMETER DESCRIPTION
resolution

Resolution of the cells (S2 supports 0-30). See [1] for a full comparison.

TYPE: int

buffer

If True then fully cover geometries with S2 cells. Otherwise only use those cells that fully fit into them. Defaults to True.

TYPE: bool DEFAULT: True

RAISES DESCRIPTION
ValueError

If resolution is not between 0 and 30.
References
  1. https://s2geometry.io/resources/s2cell_statistics.html
Source code in srai/regionalizers/s2_regionalizer.py 
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
def __init__(self, resolution: int, buffer: bool = True) -> None:
    """
    Init S2 Regionalizer.

    Args:
        resolution (int): Resolution of the cells (S2 supports 0-30). See [1] for
            a full comparison.
        buffer (bool, optional): If True then fully cover geometries with S2 cells.
            Otherwise only use those cells that fully fit into them. Defaults to True.

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

    References:
        1. https://s2geometry.io/resources/s2cell_statistics.html
    """
    if not (0 <= resolution <= 30):
        raise ValueError(f"Resolution {resolution} is not between 0 and 30.")

    self.resolution = resolution
    self.buffer = buffer

transform 

transform(gdf: gpd.GeoDataFrame) -> gpd.GeoDataFrame

Regionalize a given GeoDataFrame.

PARAMETER DESCRIPTION
gdf

GeoDataFrame to be regionalized.

TYPE: gpd.GeoDataFrame

RETURNS DESCRIPTION
gpd.GeoDataFrame

gpd.GeoDataFrame: GeoDataFrame with regionalized geometries.
Source code in srai/regionalizers/s2_regionalizer.py 
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
def transform(self, gdf: gpd.GeoDataFrame) -> gpd.GeoDataFrame:
    """
    Regionalize a given GeoDataFrame.

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

    Returns:
        gpd.GeoDataFrame: GeoDataFrame with regionalized geometries.
    """
    gdf_wgs84 = gdf.to_crs(crs=WGS84_CRS)

    s2_gdf = self._fill_with_s2_cells(self._explode_multipolygons(gdf_wgs84))

    # s2 library fills also holes in Polygons, so here we remove redundant cells
    res: gpd.GeoDataFrame = gpd.sjoin(
        s2_gdf,
        gdf_wgs84,
        how="inner",
        predicate="intersects" if self.buffer else "within",
    ).drop(columns=["index_right"])

    res = res[~res.index.duplicated(keep="first")]

    res.index.name = REGIONS_INDEX

    return res