Skip to content

EASEPandas module

EASEPandas

Source code in vgridpandas/easepandas.py 
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
@pd.api.extensions.register_dataframe_accessor("ease")
class EASEPandas:
    def __init__(self, df: DataFrame):
        self._df = df

    def latlon2ease(
        self,
        resolution: int,
        lat_col: str = "lat",
        lon_col: str = "lon",
        set_index: bool = False,
    ) -> AnyDataFrame:
        """Adds EASE ID to (Geo)DataFrame.

        pd.DataFrame: uses `lat_col` and `lon_col` (default `lat` and `lon`)
        gpd.GeoDataFrame: uses `geometry`

        Assumes coordinates in epsg=4326.

        Parameters
        ----------
        resolution : int
            EASE resolution
        lat_col : str
            Name of the latitude column (if used), default 'lat'
        lon_col : str
            Name of the longitude column (if used), default 'lon'
        set_index : bool
            If True, the columns with EASE ID is set as index, default 'True'

        Returns
        -------
        (Geo)DataFrame with EASE IDs added
        """
        if isinstance(self._df, gpd.GeoDataFrame):
            lons = self._df.geometry.x
            lats = self._df.geometry.y
        else:
            lons = self._df[lon_col]
            lats = self._df[lat_col]

        ease_ids = [
            latlon_to_ease(lat, lon, resolution) for lat, lon in zip(lats, lons)
        ]

        ease_col = EASE_COL
        assign_arg = {ease_col: ease_ids, f"{ease_col}_res": resolution}
        df = self._df.assign(**assign_arg)
        if set_index:
            return df.set_index(ease_col)
        return df

    def ease2geo(self, ease_col: str = None) -> GeoDataFrame:
        """Add geometry with EASE geometry to the DataFrame."""
        if ease_col is not None:
            if ease_col not in self._df.columns:
                raise ValueError(f"Column '{ease_col}' not found in DataFrame")
            ids = self._df[ease_col]
        else:
            if EASE_COL not in self._df.columns:
                raise ValueError(f"Column '{EASE_COL}' not found in DataFrame")
            ids = self._df[EASE_COL]
        return dggs_ids_to_geodataframe(self._df, ids, ease_to_geo)

    def polyfill(
        self,
        resolution: int,
        predicate: str = None,
        compact: bool = False,
        explode: bool = False,
    ) -> AnyDataFrame:
        """
        Parameters
        ----------
        resolution : int
            EASE resolution
        predicate : str, optional
            Spatial predicate to apply ('intersect', 'within', 'centroid_within', 'largest_overlap')
        compact : bool, optional
            Whether to compact the EASE IDs
        explode : bool
            If True, will explode the resulting list vertically.
            All other columns' values are copied.
            Default: False
        """
        result = self._df.geometry.apply(
            lambda geom: polyfill_row(geom, resolution, predicate, compact)
        )

        if not explode:
            assign_args = {EASE_COL: result}
            return self._df.assign(**assign_args)

        result = result.explode().to_frame(EASE_COL)
        return self._df.join(result)

    def linetrace(self, resolution: int, explode: bool = False) -> AnyDataFrame:
        """EASE cell representation of a (Multi)LineString traced along its vertices.

        Uses the same walk as ``vgrid.conversion.vector2dggs.vector2ease.polyline2ease``.
        """
        result = self._df.apply(
            lambda row: list(linetrace(row.geometry, resolution)), axis=1
        )
        if not explode:
            return self._df.assign(**{EASE_COL: result})
        result = result.explode().to_frame(EASE_COL)
        return self._df.join(result)

    def easebin(
        self,
        resolution: int,
        agg: str = "count",
        numeric_col: str = None,
        category_col: str = None,
        lat_col: str = "lat",
        lon_col: str = "lon",
    ) -> GeoDataFrame:
        """
        Bin points into ease cells and compute statistics.
        """
        ease_col = EASE_COL
        df = self.latlon2ease(resolution, lat_col, lon_col)
        result = aggregate_bin(df, ease_col, agg, numeric_col, category_col)
        return result.ease.ease2geo(ease_col=ease_col)

ease2geo(ease_col=None)

Add geometry with EASE geometry to the DataFrame.

Source code in vgridpandas/easepandas.py 
181
182
183
184
185
186
187
188
189
190
191
def ease2geo(self, ease_col: str = None) -> GeoDataFrame:
    """Add geometry with EASE geometry to the DataFrame."""
    if ease_col is not None:
        if ease_col not in self._df.columns:
            raise ValueError(f"Column '{ease_col}' not found in DataFrame")
        ids = self._df[ease_col]
    else:
        if EASE_COL not in self._df.columns:
            raise ValueError(f"Column '{EASE_COL}' not found in DataFrame")
        ids = self._df[EASE_COL]
    return dggs_ids_to_geodataframe(self._df, ids, ease_to_geo)

easebin(resolution, agg='count', numeric_col=None, category_col=None, lat_col='lat', lon_col='lon')

Bin points into ease cells and compute statistics.

Source code in vgridpandas/easepandas.py 
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
def easebin(
    self,
    resolution: int,
    agg: str = "count",
    numeric_col: str = None,
    category_col: str = None,
    lat_col: str = "lat",
    lon_col: str = "lon",
) -> GeoDataFrame:
    """
    Bin points into ease cells and compute statistics.
    """
    ease_col = EASE_COL
    df = self.latlon2ease(resolution, lat_col, lon_col)
    result = aggregate_bin(df, ease_col, agg, numeric_col, category_col)
    return result.ease.ease2geo(ease_col=ease_col)

latlon2ease(resolution, lat_col='lat', lon_col='lon', set_index=False)

Adds EASE ID to (Geo)DataFrame.

pd.DataFrame: uses lat_col and lon_col (default lat and lon) gpd.GeoDataFrame: uses geometry

Assumes coordinates in epsg=4326.

Parameters

resolution : int EASE resolution lat_col : str Name of the latitude column (if used), default 'lat' lon_col : str Name of the longitude column (if used), default 'lon' set_index : bool If True, the columns with EASE ID is set as index, default 'True'

Returns

(Geo)DataFrame with EASE IDs added

Source code in vgridpandas/easepandas.py 
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
def latlon2ease(
    self,
    resolution: int,
    lat_col: str = "lat",
    lon_col: str = "lon",
    set_index: bool = False,
) -> AnyDataFrame:
    """Adds EASE ID to (Geo)DataFrame.

    pd.DataFrame: uses `lat_col` and `lon_col` (default `lat` and `lon`)
    gpd.GeoDataFrame: uses `geometry`

    Assumes coordinates in epsg=4326.

    Parameters
    ----------
    resolution : int
        EASE resolution
    lat_col : str
        Name of the latitude column (if used), default 'lat'
    lon_col : str
        Name of the longitude column (if used), default 'lon'
    set_index : bool
        If True, the columns with EASE ID is set as index, default 'True'

    Returns
    -------
    (Geo)DataFrame with EASE IDs added
    """
    if isinstance(self._df, gpd.GeoDataFrame):
        lons = self._df.geometry.x
        lats = self._df.geometry.y
    else:
        lons = self._df[lon_col]
        lats = self._df[lat_col]

    ease_ids = [
        latlon_to_ease(lat, lon, resolution) for lat, lon in zip(lats, lons)
    ]

    ease_col = EASE_COL
    assign_arg = {ease_col: ease_ids, f"{ease_col}_res": resolution}
    df = self._df.assign(**assign_arg)
    if set_index:
        return df.set_index(ease_col)
    return df

linetrace(resolution, explode=False)

EASE cell representation of a (Multi)LineString traced along its vertices.

Uses the same walk as vgrid.conversion.vector2dggs.vector2ease.polyline2ease.

Source code in vgridpandas/easepandas.py 
225
226
227
228
229
230
231
232
233
234
235
236
def linetrace(self, resolution: int, explode: bool = False) -> AnyDataFrame:
    """EASE cell representation of a (Multi)LineString traced along its vertices.

    Uses the same walk as ``vgrid.conversion.vector2dggs.vector2ease.polyline2ease``.
    """
    result = self._df.apply(
        lambda row: list(linetrace(row.geometry, resolution)), axis=1
    )
    if not explode:
        return self._df.assign(**{EASE_COL: result})
    result = result.explode().to_frame(EASE_COL)
    return self._df.join(result)

polyfill(resolution, predicate=None, compact=False, explode=False)

Parameters

resolution : int EASE resolution predicate : str, optional Spatial predicate to apply ('intersect', 'within', 'centroid_within', 'largest_overlap') compact : bool, optional Whether to compact the EASE IDs explode : bool If True, will explode the resulting list vertically. All other columns' values are copied. Default: False

Source code in vgridpandas/easepandas.py 
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
def polyfill(
    self,
    resolution: int,
    predicate: str = None,
    compact: bool = False,
    explode: bool = False,
) -> AnyDataFrame:
    """
    Parameters
    ----------
    resolution : int
        EASE resolution
    predicate : str, optional
        Spatial predicate to apply ('intersect', 'within', 'centroid_within', 'largest_overlap')
    compact : bool, optional
        Whether to compact the EASE IDs
    explode : bool
        If True, will explode the resulting list vertically.
        All other columns' values are copied.
        Default: False
    """
    result = self._df.geometry.apply(
        lambda geom: polyfill_row(geom, resolution, predicate, compact)
    )

    if not explode:
        assign_args = {EASE_COL: result}
        return self._df.assign(**assign_args)

    result = result.explode().to_frame(EASE_COL)
    return self._df.join(result)

linetrace(geometry, resolution)

Trace a (Multi)LineString with EASE cells (same walk as polyline2ease).

Source code in vgridpandas/easepandas.py 
111
112
113
114
115
def linetrace(geometry: MultiLineOrLine, resolution: int) -> Iterator[str]:
    """Trace a (Multi)LineString with EASE cells (same walk as ``polyline2ease``)."""
    rows = polyline2ease(geometry, resolution, include_properties=False)
    for row in rows:
        yield row[EASE_COL]

poly2ease(geometry, resolution, predicate=None, compact=False)

Convert polygon or line geometries to EASE grid cells.

Mirrors polygon2ease and polyline2ease in vgrid: bbox discovery via geo_polygon_to_grid_ids, then filter with ease2geo cell polygons. Polygons use predicate; lines use intersection. Compact mode applies to polygons after predicate filtering only (not lines).

Parameters:

Name Type Description Default
resolution int

EASE resolution level [0..6]

 required
geometry

Polygon, MultiPolygon, LineString, or MultiLineString

 required
predicate str

Spatial predicate for polygons ('intersect', 'within', 'centroid_within', 'largest_overlap')

 None
compact bool

Enable EASE compact mode for polygons

 False

Returns:

Name Type Description
list list

List of EASE cell ids
Example

from shapely.geometry import Polygon poly = Polygon([(-122.5, 37.7), (-122.3, 37.7), (-122.3, 37.9), (-122.5, 37.9)]) cells = poly2ease(poly, 4, predicate="intersect", compact=True) len(cells) > 0 True

Source code in vgridpandas/easepandas.py 
 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
103
104
105
106
107
108
def poly2ease(
    geometry,
    resolution: int,
    predicate: str = None,
    compact: bool = False,
) -> list:
    """
    Convert polygon or line geometries to EASE grid cells.

    Mirrors ``polygon2ease`` and ``polyline2ease`` in vgrid: bbox discovery via
    ``geo_polygon_to_grid_ids``, then filter with ``ease2geo`` cell polygons.
    Polygons use ``predicate``; lines use intersection.
    Compact mode applies to polygons after predicate filtering only (not lines).

    Args:
        resolution (int): EASE resolution level [0..6]
        geometry: Polygon, MultiPolygon, LineString, or MultiLineString
        predicate (str, optional): Spatial predicate for polygons
            ('intersect', 'within', 'centroid_within', 'largest_overlap')
        compact (bool, optional): Enable EASE compact mode for polygons

    Returns:
        list: List of EASE cell ids

    Example:
        >>> from shapely.geometry import Polygon
        >>> poly = Polygon([(-122.5, 37.7), (-122.3, 37.7), (-122.3, 37.9), (-122.5, 37.9)])
        >>> cells = poly2ease(poly, 4, predicate="intersect", compact=True)
        >>> len(cells) > 0
        True
    """
    resolution = validate_ease_resolution(resolution)
    ease_ids = []
    if isinstance(geometry, (Polygon, LineString)):
        polys = [geometry]
    elif isinstance(geometry, (MultiPolygon, MultiLineString)):
        polys = list(geometry.geoms)
    else:
        return []

    is_line = isinstance(geometry, (LineString, MultiLineString))
    for poly in polys:
        if poly is None or poly.is_empty:
            continue

        poly_bbox = box(*poly.bounds)
        cells_bbox = geo_polygon_to_grid_ids(
            poly_bbox.wkt,
            resolution,
            geo_crs,
            ease_crs,
            levels_specs,
            return_centroids=True,
            wkt_geom=True,
        )
        candidate_ids = cells_bbox["result"]["data"]
        if not candidate_ids:
            continue

        if compact and is_line:
            candidate_ids = ease_compact(candidate_ids)

        poly_ids = []
        for ease_id in candidate_ids:
            ease_id_str = str(ease_id)
            cell_polygon = ease_to_geo(ease_id_str)
            if not cell_polygon:
                continue
            if is_line:
                if cell_polygon.intersects(poly):
                    poly_ids.append(ease_id_str)
            elif check_predicate(cell_polygon, poly, predicate):
                poly_ids.append(ease_id_str)

        if compact and poly_ids and not is_line:
            poly_ids = [str(cell_id) for cell_id in ease_compact(poly_ids)]

        ease_ids.extend(poly_ids)

    return list(dict.fromkeys(ease_ids))

polyfill_row(geometry, resolution, predicate=None, compact=False)

Return cell ids covering a single row geometry.

Source code in vgridpandas/easepandas.py 
118
119
120
121
122
123
124
125
126
def polyfill_row(geometry, resolution, predicate=None, compact=False) -> list:
    """Return cell ids covering a single row geometry."""
    if isinstance(geometry, (Polygon, MultiPolygon)):
        tokens = set(poly2ease(geometry, resolution, predicate, compact))
    elif isinstance(geometry, (LineString, MultiLineString)):
        tokens = set(linetrace(geometry, resolution))
    else:
        raise TypeError(f"Unknown type {type(geometry)}")
    return list(tokens)