Indexing GeoPandas#

Index geometries in a GeoPandas GeoDataFrame against the BNG index system.

Note

This module requires the GeoPandas package to be installed.

To install the required package, use:

pip install osbng[geopandas]

osbng.indexing_gpd.gdf_to_bng_intersection_explode(gdf: GeoDataFrame, resolution: int | str, *, reset_index: bool = True) → GeoDataFrame[source]#

Applies geom_to_bng_intersection to a GeoDataFrame at a given resolution.

Decomposes each geometry in the input GeoDataFrame bounded by their presence in grid squares at the specified resolution. The resulting BNGIndexedGeometry objects are exploded into individual rows, with each row containing a new column for each BNGIndexedGeometry object property: bng_ref, is_core, and geom.

Notes

Decomposition is achieved by applying the geom_to_bng_intersection function to each geometry in the input GeoPandas GeoDataFrame, returning a flattened GeoDataFrame by exploding the resulting BNGIndexedGeometry lists.

The input GeoDataFrame geometry column is replaced with the geom property of the BNGIndexedGeometry objects. The input geometry column can be retrieved if required by joining the resulting GeoDataFrame with the original GeoDataFrame on the index (if not reset), or using a feature identifier. Dropping the original geometry column reduces memory usage and simplifies the resulting GeoDataFrame.

All non-geometry columns from the original GeoDataFrame are retained in the resulting GeoDataFrame.

Exploding the resulting GeoDataFrame allows for easier analysis and manipulation of the BNGIndexedGeometry object properties. This is otherwise a more complex operation.

Warning

The active geometry column of the input GeoDataFrame is passed to geom_to_bng_intersection, which is expected to be set and in the OSGB36 / British National Grid coordinate reference system (CRS) (EPSG:27700).

Parameters:

  • gdf (gpd.GeoDataFrame) – Input GeoPandas GeoDataFrame.

  • resolution (int | str) – The BNG resolution expressed either as a metre-based integer or as a string label.

Keyword Arguments:

reset_index (bool) – Whether to reset the index of the resulting GeoDataFrame, defaults to True.

Returns:

A new GeoDataFrame with one row per BNGIndexedGeometry object, containing three columns bng_ref, is_core, and geometry corresponding to the BNGIndexedGeometry object properties.

Return type:

gpd.GeoDataFrame

Raises:

  • BNGResolutionError – If an invalid resolution is provided.

  • BNGExtentError – If the coordinates of a Point geometry are outside of the BNG index system extent.

  • TypeError – If the input is not a GeoPandas GeoDataFrame.

  • ValueError – If the GeoDataFrame CRS is not equal to “EPSG:27700”

  • ValueError – If an active geometry column is not set in the GeoDataFrame.

  • ValueError – If the geometry type is not supported.

Examples

>>> import geopandas as gpd
>>> import pandas as pd
>>> df = pd.DataFrame({
...             "id": ["0", "1", "2"],
...             "geometry": [
...                 "POLYGON((530000 180000, 535000 180000, 535000 185000,
                     530000 185000, 530000 180000))",
...                 "POLYGON((540000 190000, 545000 190000, 545000 195000,
                    540000 195000, 540000 190000))",
...                 "POLYGON((550000 200000, 555000 200000, 555000 205000,
                    550000 205000, 550000 200000))"
...             ]
... })
>>> gdf = gpd.GeoDataFrame(df, geometry=gpd.GeoSeries.from_wkt(df["geometry"]),
                           crs="EPSG:27700")
>>> gdf_to_bng_intersection_explode(gdf, resolution="1km")
    id                                            bng_ref
0   0  BNGReference(bng_ref_formatted=TQ 31 80, resol...
1   0  BNGReference(bng_ref_formatted=TQ 30 82, resol...
2   0  BNGReference(bng_ref_formatted=TQ 33 84, resol...
3   0  BNGReference(bng_ref_formatted=TQ 34 80, resol...
4   0  BNGReference(bng_ref_formatted=TQ 33 80, resol...
..  ...                                                ...
70  2  BNGReference(bng_ref_formatted=TL 52 01, resol...
71  2  BNGReference(bng_ref_formatted=TL 52 03, resol...
72  2  BNGReference(bng_ref_formatted=TL 50 04, resol...
73  2  BNGReference(bng_ref_formatted=TL 50 03, resol...
74  2  BNGReference(bng_ref_formatted=TL 54 01, resol...
    is_core                                       geometry
0   True  POLYGON ((532000 180000, 532000 181000, 531000...
1   True  POLYGON ((531000 182000, 531000 183000, 530000...
2   True  POLYGON ((534000 184000, 534000 185000, 533000...
3   True  POLYGON ((535000 180000, 535000 181000, 534000...
4   True  POLYGON ((534000 180000, 534000 181000, 533000...
..   ...                                                ...
70  True  POLYGON ((553000 201000, 553000 202000, 552000...
71  True  POLYGON ((553000 203000, 553000 204000, 552000...
72  True  POLYGON ((551000 204000, 551000 205000, 550000...
73  True  POLYGON ((551000 203000, 551000 204000, 550000...
74  True  POLYGON ((555000 201000, 555000 202000, 554000...
[75 rows x 4 columns]

See also

geom_to_bng_intersection to index Shapely geometries directly.