Skip to content

Regionalizers

This module contains regionalizers, which are used to divide space before analysis.

Embedding methods available in srai operate on a regions, which can be defined in many ways. In this module, we aggregate different regionalization methods under a common Regionalizer interface. We include both pre-defined spatial indexes (e.g. H3 or S2), data-based ones (e.g. Voronoi) and OSM- based ones (e.g. administrative boundaries).

Classes

Functions

srai.regionalizers.geocode_to_region_gdf(
    query, by_osmid=False
)

Geocode a query to the regions_gdf unified format.

This functions is a wrapper around the ox.geocode_to_gdf[1] function from the osmnx library. For parameters description look into the source documentation.

PARAMETER DESCRIPTION
query

Query string(s) or structured dict(s) to geocode.

TYPE: Union[str, List[str], Dict[str, Any]]

by_osmid

Flag to treat query as an OSM ID lookup rather than text search. Defaults to False.

TYPE: bool DEFAULT: False

RETURNS DESCRIPTION
gpd.GeoDataFrame

gpd.GeoDataFrame: GeoDataFrame with geocoded regions.
References
  1. https://osmnx.readthedocs.io/en/stable/osmnx.html#osmnx.geocoder.geocode_to_gdf

Examples:

Download geometry for a city

>>> from srai.regionalizers import geocode_to_region_gdf
>>> geocode_to_region_gdf("Wrocław, PL")
                                                  geometry
region_id
Wrocław, Lower Silesian Voivodeship, Poland  POLYGON ((...

Download geometries for multiple cities

>>> geocode_to_region_gdf(["New York City", "Washington, DC"])
                                                            geometry
region_id
New York, United States                          MULTIPOLYGON (((...
Washington, District of Columbia, United States  POLYGON ((...

Use OSM relation IDs to get geometries.

>>> geocode_to_region_gdf(["R175342", "R5750005"], by_osmid=True)
                                                         geometry
region_id
Greater London, England, United Kingdom             POLYGON ((...
Sydney, Council of the City of Sydney, New Sout...  POLYGON ((...
Source code in srai/regionalizers/geocode.py 
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
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
def geocode_to_region_gdf(
    query: Union[str, list[str], dict[str, Any]], by_osmid: bool = False
) -> gpd.GeoDataFrame:
    """
    Geocode a query to the `regions_gdf` unified format.

    This functions is a wrapper around the `ox.geocode_to_gdf`[1] function from the `osmnx` library.
    For parameters description look into the source documentation.

    Args:
        query (Union[str, List[str], Dict[str, Any]]): Query string(s) or structured dict(s)
            to geocode.
        by_osmid (bool, optional): Flag to treat query as an OSM ID lookup rather than text search.
            Defaults to False.

    Returns:
        gpd.GeoDataFrame: GeoDataFrame with geocoded regions.

    References:
        1. https://osmnx.readthedocs.io/en/stable/osmnx.html#osmnx.geocoder.geocode_to_gdf

    Examples:
        Download geometry for a city
        >>> from srai.regionalizers import geocode_to_region_gdf
        >>> geocode_to_region_gdf("Wrocław, PL")
                                                          geometry
        region_id
        Wrocław, Lower Silesian Voivodeship, Poland  POLYGON ((...

        Download geometries for multiple cities

        >>> geocode_to_region_gdf(["New York City", "Washington, DC"])
                                                                    geometry
        region_id
        New York, United States                          MULTIPOLYGON (((...
        Washington, District of Columbia, United States  POLYGON ((...

        Use OSM relation IDs to get geometries.

        >>> geocode_to_region_gdf(["R175342", "R5750005"], by_osmid=True)
                                                                 geometry
        region_id
        Greater London, England, United Kingdom             POLYGON ((...
        Sydney, Council of the City of Sydney, New Sout...  POLYGON ((...
    """
    import_optional_dependencies(
        dependency_group="osm",
        modules=["osmnx"],
    )

    import osmnx as ox

    geocoded_gdf = ox.geocode_to_gdf(query=query, by_osmid=by_osmid, which_result=None)
    regions_gdf = (
        geocoded_gdf[["display_name", "geometry"]]
        .rename(columns={"display_name": REGIONS_INDEX})
        .set_index(REGIONS_INDEX)
    )
    return regions_gdf