here.geopandas_adapter.geotiles.heretile module

Module to operate with HERETile tiling scheme using (Geo)DataFrames.

here.geopandas_adapter.geotiles.heretile.ancestor(tile_ids: Series, level: int | None = None) → Series

Return the ancestor tiles at the given level for the tiles.

Index and NaN values are retained. NaN is also returned in case of invalid tile IDs or tiling level, or when the ancestor doesn’t exist.

Parameters:

tile_ids – the tile IDs
level – the tiling level

Returns:
a pd.Series with the tile IDs of the ancestors or parents, when existing

Raises:
ValueError – in case the series doesn’t contain integers # noqa

here.geopandas_adapter.geotiles.heretile.contains_coordinates(tile_ids: Series, lngs: Series, lats: Series) → Series

Return if the tiles contains the points.

The check includes the tile boundary, aligned with the way shapely intersects operates.

NaN values or not all the series containing a value for a given index determine the resulting tile ID to be NaN.

Parameters:

tile_ids – the tile IDs
lngs – the Series with longitudes
lats – the Series with latitudes

Returns:
a pd.Series containing if the points are inside the tiles

Raises:
ValueError – in case the series doesn’t contain integers # noqa

here.geopandas_adapter.geotiles.heretile.contains_geometry(tile_ids: Series, geometries: GeoSeries, fully_contained=False) → Series

Return if the tiles contain the geometries.

Inclusion is modeled as the shapely relation intersects (fully_contained is false) or contains (otherwise) between the tile and the geometry.

NaN values or not all the series containing a value for a given index determine the resulting tile ID to be NaN.

Parameters:

tile_ids – the tile IDs
geometries – a ``gpd.GeoSeries` with any geometric type
fully_contained – check if each geometry is fully contained in each tile

Returns:
a pd.Series of booleans, if the geometries are inside the tiles

Raises:
ValueError – in case the series doesn’t contain integers # noqa

here.geopandas_adapter.geotiles.heretile.contains_point(tile_ids: Series, pts: GeoSeries) → Series

Return if the tiles contains the points.

This method is more efficient than contains_geometry for points.

The check includes the tile boundary, aligned with the way shapely intersects operates.

NaN values or not all the series containing a value for a given index determine the resulting tile ID to be NaN.

Parameters:

tile_ids – the tile IDs
pts – the ``gpd.GeoSeries` with points

Returns:
a pd.Series of booleans, if the points are inside the tiles

Raises:
ValueError – in case the series doesn’t contain integers # noqa

here.geopandas_adapter.geotiles.heretile.descendants(tile_ids: Series, level: int | None = None) → Series

Return the tile IDs of all descendants at some level for each tile.

Index and NaN values are retained. NaN is also returned in place of empty lists or in case of invalid tile IDs or tiling level.

Use pd.Series.explode method to turn the lists into multiple rows.

Parameters:

tile_ids – the tile IDs
level – the tiling level

Returns:
a pd.Series with the list of descendants tile IDs for each tile

Raises:
ValueError – in case the series doesn’t contain integers # noqa

here.geopandas_adapter.geotiles.heretile.from_coordinates(lngs: Series, lats: Series, level: int) → Series

Return the tiles that contain points.

Series must be indexed the same. NaN values or series missing a row for some index value determine the resulting tile ID to be NaN. This is also the case if a point can’t be mapped to a tile ID.

Index is retained.

Parameters:

lngs – the Series with longitudes
lats – the Series with latitudes
level – the tiling level

Returns:
a Series tile IDs, NaN when no tile ID can be calculated

here.geopandas_adapter.geotiles.heretile.from_point(pts: GeoSeries, level: int) → Series

Return the tiles that contain points.

NaN values or rows not containing a Point determine the resulting tile ID to be NaN. This is also the case if a point can’t be mapped to a tile ID.

Index is retained.

Parameters:

pts – the GeoSeries with the points
level – the tiling level

Returns:
a Series tile IDs, NaN when no tile ID can be calculated

here.geopandas_adapter.geotiles.heretile.from_x_y_level(xs: Series, ys: Series, levels: Series) → Series

Return the tiles given X and Y components and levels.

Series must be indexed the same. NaN values or series missing a row for some index value determine the resulting tile ID to be NaN. This is also the case if not tile ID corresponds to a (x, y, level) tuple.

Index is retained.

Parameters:

xs – the Series with the tile X component
ys – the Series with the tile Y component
levels – the Series with tile levels

Returns:
a Series tile IDs, NaN when no tile ID can be calculated

Raises:
ValueError – in case the series doesn’t contain integers # noqa

here.geopandas_adapter.geotiles.heretile.get_boundary_ring(tile_ids: Series) → GeoSeries

Return the boundary of the tiles as linear rings.

Each ring describes the boundary counter-clockwise. It contains 5 points, since a linear ring is always closed by repeating its first point.

Index and NaN values are retained by returning None. None are also returned in case of invalid tile IDs.

Parameters:
tile_ids – the tile IDs

Returns:
a gpd.GeoSeries of linear rings

Raises:
ValueError – in case the series doesn’t contain integers # noqa

here.geopandas_adapter.geotiles.heretile.get_bounds(tile_ids: Series) → DataFrame

Return the bounds of the tiles.

This function returns bounds following the same convention of the bounds function of shapely.

Index and NaN values are retained. NaN are also returned in case of invalid tile IDs.

Parameters:
tile_ids – the tile IDs

Returns:
a DataFrame with columns west, south, east, north. NaN when not applicable

Raises:
ValueError – in case the series doesn’t contain integers # noqa

here.geopandas_adapter.geotiles.heretile.get_center_coordinates(tile_ids: Series) → DataFrame

Return the center points of the tiles.

Index and NaN values are retained. NaN are also returned in case of invalid tile IDs.

Parameters:
tile_ids – the tile IDs

Returns:
a tuple of 2 Series containing longitude and latitude, NaN when not applicable

Raises:
ValueError – in case the series doesn’t contain integers # noqa

here.geopandas_adapter.geotiles.heretile.get_center_point(tile_ids: Series) → GeoSeries

Return the center points of the tiles.

Index and NaN values are retained by returning None. None are also returned in case of invalid tile IDs.

Parameters:
tile_ids – the tile IDs

Returns:
a GeoSeries of points, None when not applicable

Raises:
ValueError – in case the series doesn’t contain integers # noqa

here.geopandas_adapter.geotiles.heretile.get_corners(tile_ids: Series) → GeoDataFrame

Return the southwestern and northeastern corners of the tiles.

Index and NaN values are retained by returning None. None are also returned in case of invalid tile IDs.

Parameters:
tile_ids – the tile IDs

Returns:
a GeoDataFrame with columns southwest, northeast. None when not applicable # noqa

Raises:
ValueError – in case the series doesn’t contain integers or strings # noqa

here.geopandas_adapter.geotiles.heretile.get_level(tile_ids: Series) → Series

Return the levels of the tiles.

Index and NaN values are retained. NaN are also returned in case of invalid tile IDs.

Parameters:
tile_ids – the tile IDs

Returns:
a Series tiling levels, NaN when not applicable

Raises:
ValueError – in case the series doesn’t contain integers # noqa

here.geopandas_adapter.geotiles.heretile.get_polygon(tile_ids: Series) → GeoSeries

Return the tiles as polygons.

Index and NaN values are retained by returning None. None are also returned in case of invalid tile IDs.

Parameters:
tile_ids – the tile IDs

Returns:
a gpd.GeoSeries of polygons

Raises:
ValueError – in case the series doesn’t contain integers # noqa

here.geopandas_adapter.geotiles.heretile.get_x(tile_ids: Series) → Series

Return the X components of the tiles.

Index and NaN values are retained. NaN are also returned in case of invalid tile IDs.

Parameters:
tile_ids – the tile IDs

Returns:
a Series of X components, NaN when not applicable

Raises:
ValueError – in case the series doesn’t contain integers # noqa

here.geopandas_adapter.geotiles.heretile.get_x_y_level(tile_ids: Series) → DataFrame

Return the X and Y components and the levels of the tiles.

Index and NaN values are retained. NaN are also returned in case of invalid tile IDs.

Resulting NaN values are removed, unless drop_na is set to false.

Parameters:
tile_ids – the tile IDs

Returns:
a DataFrame with columns x, y, level, NaN when not applicable

Raises:
ValueError – in case the series doesn’t contain integers # noqa

here.geopandas_adapter.geotiles.heretile.get_y(tile_ids: Series) → Series

Return the Y components of the tiles.

Index and NaN values are retained. NaN are also returned in case of invalid tile IDs.

Parameters:
tile_ids – the tile IDs

Returns:
a Series of Y components, NaN when not applicable

Raises:
ValueError – in case the series doesn’t contain integers # noqa

here.geopandas_adapter.geotiles.heretile.in_geometry(geometries: GeoSeries, level: int, fully_contained: bool = False) → Series

Return the tiles that are included in the geometries.

If fully_contained is false, some of the returned tiles may be partially outside the geometry. Otherwise, return only the tiles wholly inside the geometry.

Inclusion is modeled as the shapely relation intersects (fully_contained is false) or contains (otherwise) between the geometry and the tiles.

Examples (fully_contained is false): - if the geometry is a point, return one, two or four tiles - if the geometry is a line string, it return all the tiles along the line - if the geometry is a polygon, it returns all the tiles intersecting with the polygon - for multi-geometries, return the union of the tiles in each geometry

Examples (fully_contained is true): - if the geometry is a point, nothing is returned - if the geometry is a line string, nothing is returned - if the geometry is a polygon, it returns all the tiles contained in the polygon - for multi-geometries, return the union of the tiles in each geometry

Index and NaN values are retained. NaN is also returned in place of empty lists.

Use pd.Series.explode method to turn the lists into multiple rows.

Parameters:

geometries – the GeoSeries with arbitrary geometries
level – the tiling level
fully_contained – return only tiles wholly inside the bounding box

Returns:
a Series with the list of tile IDs corresponding to each geometry, in the order of West to East first, then South to North

here.geopandas_adapter.geotiles.heretile.in_geometry_bounds(geometries: GeoSeries, level: int, fully_contained: bool = False) → Series

Return the tiles that are included in the bounds of geometries.

If fully_contained is false, some of the returned tiles may be partially outside the bounds. Otherwise, return only the tiles wholly inside the bounds.

Index and NaN values are retained. NaN is also returned in place of empty lists.

Use pd.Series.explode method to turn the lists into multiple rows.

Parameters:

geometries – the GeoSeries with arbitrary geometries
level – the tiling level
fully_contained – return only tiles wholly inside the bounding box

Returns:
a Series with the list of tile IDs corresponding to each geometry, in the order of West to East first, then South to North

here.geopandas_adapter.geotiles.heretile.is_contained_in_geometry(tile_ids: Series, geometries: GeoSeries, fully_contained=False) → Series

Return if the tiles are contained in the geometries.

Inclusion is modeled as the shapely relation intersects (fully_contained is false) or contains (otherwise) between the geometry and the tile.

Parameters:

tile_ids – the tile IDs
geometries – a ``gpd.GeoSeries` with any geometric type
fully_contained – check if the tile is fully contained in the geometry

Returns:
a pd.Series of booleans, if the tiles are contained in the geometries, fully or partially

Raises:
ValueError – in case the series doesn’t contain integers # noqa

here.geopandas_adapter.geotiles.heretile.is_descendant(tile_ids: Series, of_tile_ids: Series) → Series

Check if tiles are the direct descendant of other tiles.

Index and NaN values are retained. Series should be indexed the same.

Parameters:

tile_ids – the subject tile IDs
of_tile_ids – check the relationship of the subjects with these tiles

Returns:
a pd.Series containing if each tile is the descendant of the other tile

Raises:
ValueError – in case the series doesn’t contain integers # noqa

here.geopandas_adapter.geotiles.heretile.is_parent(tile_ids: Series, of_tile_ids: Series) → Series

Check if tiles are the direct parents of other tiles.

Index and NaN values are retained. Series should be indexed the same.

Parameters:

tile_ids – the subject tile IDs
of_tile_ids – check the relationship of the subjects with these tiles

Returns:
a pd.Series containing if each tile is the parent of the other tile

Raises:
ValueError – in case the series doesn’t contain integers # noqa

here.geopandas_adapter.geotiles.heretile.is_valid(tile_ids: Series) → Series

Check if integers are a valid tile IDs.

Index and NaN values are retained.

Parameters:
tile_ids – a Series of integers

Returns:
a Series of booleans with the result of the test

Raises:
ValueError – in case the series doesn’t contain integers # noqa

Example: >>> is_valid(pd.Series([0, 1, 2, 3, 4])) 0 False 1 True 2 False 3 False 4 True dtype: bool

here.geopandas_adapter.geotiles.heretile.neighbors(tile_ids: Series, level: int | None = None) → Series

Return tile IDs of all neighbors on given level for tiles.

Index and NaN values are retained. NaN is also returned in place of empty lists or in case of invalid tile IDs or tiling level.

Use pd.Series.explode method to turn the lists into multiple rows.

Parameters:

tile_ids – the subject tile IDs
level – the tiling level

Returns:
a pd.Series with the list of neighboring tile IDs

Raises:
ValueError – in case the series doesn’t contain integers # noqa