PyPI version fury.io Documentation Status CI/CD pre-commit.ci status codecov GitHub license

pyregeon#

Reusable Python utilities to work with geospatial regions.

pyregeon stands for Python Region Geospatial utilities

Usage#

The main idea of pyregeon is to make it as easy as possible to associate any Python object to a geospatial region. The first approach is with the object-oriented RegionMixin. We can set the region property attribute to any object that inherits from RegionMixin, e.g.:

from pyregeon import RegionMixin


class MyAnalysisCase(..., RegionMixin):
    # optionally define a `crs` or `CRS` attribute
    pass


analysis = MyAnalysisCase(...)
analysis.region = "Lausanne, Switzerland"

The region property setter accepts the following values:

  • A string with a place name (Nominatim query) to geocode (requires osmnx).

  • A sequence with the west, south, east and north bounds.

  • A geometric object, e.g., shapely geometry, or a sequence of geometric objects (polygon or multi-polygon). In such a case, the value is passed as the data argument of the GeoSeries constructor, and needs to be in the same CRS as the one provided through the crs argument.

  • A geopandas geo-series or geo-data frame.

  • A filename or URL, a file-like object opened in binary (‘rb’) mode, or a Path object that will be passed to geopandas.read_file.

Then, the processed region attribute can be accessed as a geo-data frame:

analysis.region
geometry bbox_west bbox_south bbox_east bbox_north place_id osm_type osm_id lat lon class type place_rank importance addresstype name display_name
0 MULTIPOLYGON (((6.58387 46.55187, 6.58632 46.5... 6.583868 46.454873 6.720814 46.602577 83952532 relation 1685018 46.521827 6.632702 boundary administrative 16 0.6941 city Lausanne Lausanne, District de Lausanne, Vaud, Switzerland

Note that when setting region to a naive geometry, i.e, without associated coordinate reference system (CRS), the setter will try to retrieve a CRS by looking whether the object has a crs or CRS attribute (in that order). In absence of these, a ValueError will be raised.

With the region attribute properly set, we can also generate regular grids using the generate_regular_grid_gser method:

import contextily as cx

res = 0.05
ax = analysis.generate_regular_grid_gser(res).plot(alpha=0.5, edgecolor="black")
cx.add_basemap(ax, crs=analysis.region.crs, attribution=False)

lausanne-grid

Alternatively, it is possible to use the standalone pyregeon.generate_regular_grid_gser function without any class by prepending a geo-series with the region as first positional argument (and optionally providing the crs keyword argument if the provided geo-series is naive).

See the API documentation for more details or the multiurbanpy library for an example use case of pyregeon.

Installation#

pip install pyregeon

Acknowledgements#