Regionalizers¶

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.convert_to_regions_gdf ¶

convert_to_regions_gdf(
    geometry: Union[
        BaseGeometry, Iterable[BaseGeometry], gpd.GeoSeries, gpd.GeoDataFrame
    ],
    index_column: Optional[str] = None,
) -> gpd.GeoDataFrame

Convert any geometry to a regions GeoDataFrame.

PARAMETER	DESCRIPTION
`geometry`	Geo objects to convert. TYPE: `Union[BaseGeometry, Iterable[BaseGeometry], GeoSeries, GeoDataFrame]`
`index_column`	Name of the column used to define the index. If None, will rename the existing index. Defaults to None. TYPE: `Optional[str]` DEFAULT: `None`

RETURNS	DESCRIPTION
`GeoDataFrame`	gpd.GeoDataFrame: Regions gdf with proper index definition.

Source code in srai/geometry.py

def convert_to_regions_gdf(
    geometry: Union[BaseGeometry, Iterable[BaseGeometry], gpd.GeoSeries, gpd.GeoDataFrame],
    index_column: Optional[str] = None,
) -> gpd.GeoDataFrame:
    """
    Convert any geometry to a regions GeoDataFrame.

    Args:
        geometry (Union[BaseGeometry, Iterable[BaseGeometry], gpd.GeoSeries, gpd.GeoDataFrame]): Geo
            objects to convert.
        index_column (Optional[str], optional): Name of the column used to define the index.
            If None, will rename the existing index. Defaults to None.

    Returns:
        gpd.GeoDataFrame: Regions gdf with proper index definition.
    """
    return _convert_to_internal_format(
        geometry=geometry, destination_index_name=REGIONS_INDEX, index_column=index_column
    )

srai.regionalizers.geocode_to_region_gdf ¶

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.

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
`GeoDataFrame`	gpd.GeoDataFrame: GeoDataFrame with geocoded regions.

References

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

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