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

geocode_to_region_gdf

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
Source code in srai/regionalizers/geocode.py 
10
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
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
    """
    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