pyregeon 0.1.0

Reusable Python utilities to work with geospatial regions.

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)

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

• This package was created with the martibosch/cookiecutter-geopy-package project template.