iduedu 0.1.0__py3-none-any.whl

iduedu/__init__.py

@@ -0,0 +1,11 @@
+"""
+IduEdu
+========
+
+IduEdu is a Python package for the creation and manipulation of complex city networks from OpenStreetMap.
+
+Homepage https://github.com/DDonnyy/IduEdu.
+"""
+from ._config import config
+from ._api import *
+from ._version import VERSION as __version__

iduedu/_api.py

@@ -0,0 +1,7 @@
+# pylint: disable=unused-import
+from .modules.downloaders import get_boundary
+from .modules.drive_walk_builder import get_drive_graph, get_walk_graph
+from .modules.intermodal_builder import get_intermodal_graph
+from .modules.matrix_builder import get_adj_matrix_gdf_to_gdf
+from .modules.pt_walk_joiner import join_pt_walk_graph
+from .modules.public_transport_builder import get_all_public_transport_graph, get_single_public_transport_graph

iduedu/_config.py

@@ -0,0 +1,58 @@
+import sys
+from typing import Literal
+
+from loguru import logger
+
+
+class Config:
+    """
+    A configuration class to manage global settings for the application, such as Overpass API URL, timeouts, and logging options.
+
+    Attributes
+    ----------
+    overpass_url : str
+        URL for accessing the Overpass API. Defaults to "http://lz4.overpass-api.de/api/interpreter".
+    timeout : int or None
+        Timeout in seconds for API requests. If None, no timeout is applied.
+    enable_tqdm_bar : bool
+        Enables or disables progress bars (via tqdm). Defaults to True.
+    logger : Logger
+        Logging instance to handle application logging.
+
+    Methods
+    -------
+    change_logger_lvl(lvl: Literal["TRACE", "DEBUG", "INFO", "WARN", "ERROR"])
+        Changes the logging level to the specified value.
+    set_overpass_url(url: str)
+        Sets a new Overpass API URL.
+    set_timeout(timeout: int)
+        Sets the timeout for API requests.
+    set_enable_tqdm(enable: bool)
+        Enables or disables progress bars in the application.
+    """
+    def __init__(
+        self,
+        overpass_url="http://lz4.overpass-api.de/api/interpreter",
+        timeout=None,
+        enable_tqdm_bar=True,
+    ):
+        self.overpass_url = overpass_url
+        self.timeout = timeout
+        self.enable_tqdm_bar = enable_tqdm_bar
+        self.logger = logger
+
+    def change_logger_lvl(self, lvl: Literal["TRACE", "DEBUG", "INFO", "WARN", "ERROR"]):
+        self.logger.remove()
+        self.logger.add(sys.stderr, level=lvl)
+
+    def set_overpass_url(self, url: str):
+        self.overpass_url = url
+
+    def set_timeout(self, timeout: int):
+        self.timeout = timeout
+
+    def set_enable_tqdm(self, enable: bool):
+        self.enable_tqdm_bar = enable
+
+
+config = Config()

iduedu/_version.py

@@ -0,0 +1 @@
+VERSION = "0.1.0"

iduedu/enums/drive_enums.py

@@ -0,0 +1,73 @@
+from enum import Enum
+from typing import Literal
+
+
+class RegistrationStatus(Enum):
+    """
+    Enum for registration status of the road.
+    """
+
+    FEDERAL = 1
+    REGIONAL = 2
+    LOCAL = 3
+
+
+class HighwayType(Enum):
+    """
+    Enum of highway types. Properties contain registration status & max speeds
+    """
+
+    MOTORWAY = "motorway"
+    TRUNK = "trunk"
+    PRIMARY = "primary"
+    SECONDARY = "secondary"
+    TERTIARY = "tertiary"
+    UNCLASSIFIED = "unclassified"
+    RESIDENTIAL = "residential"
+    MOTORWAY_LINK = "motorway_link"
+    TRUNK_LINK = "trunk_link"
+    PRIMARY_LINK = "primary_link"
+    SECONDARY_LINK = "secondary_link"
+    TERTIARY_LINK = "tertiary_link"
+    LIVING_STREET = "living_street"
+
+    @property
+    def reg_status(self) -> Literal[1, 2, 3]:
+        reg_status = {
+            HighwayType.MOTORWAY: RegistrationStatus.FEDERAL,
+            HighwayType.TRUNK: RegistrationStatus.FEDERAL,
+            HighwayType.PRIMARY: RegistrationStatus.REGIONAL,
+            HighwayType.SECONDARY: RegistrationStatus.REGIONAL,
+            HighwayType.TERTIARY: RegistrationStatus.LOCAL,
+            HighwayType.UNCLASSIFIED: RegistrationStatus.LOCAL,
+            HighwayType.RESIDENTIAL: RegistrationStatus.LOCAL,
+            HighwayType.MOTORWAY_LINK: RegistrationStatus.FEDERAL,
+            HighwayType.TRUNK_LINK: RegistrationStatus.FEDERAL,
+            HighwayType.PRIMARY_LINK: RegistrationStatus.REGIONAL,
+            HighwayType.SECONDARY_LINK: RegistrationStatus.REGIONAL,
+            HighwayType.TERTIARY_LINK: RegistrationStatus.LOCAL,
+            HighwayType.LIVING_STREET: RegistrationStatus.LOCAL,
+        }
+        return reg_status[self].value
+
+    @property
+    def max_speed(self) -> float:
+        """
+        Average speed in m/min.
+        """
+        speeds = {  # km/h
+            HighwayType.MOTORWAY: 110,
+            HighwayType.TRUNK: 90,
+            HighwayType.PRIMARY: 60,
+            HighwayType.SECONDARY: 60,
+            HighwayType.TERTIARY: 60,
+            HighwayType.UNCLASSIFIED: 40,
+            HighwayType.RESIDENTIAL: 40,
+            HighwayType.MOTORWAY_LINK: 90,
+            HighwayType.TRUNK_LINK: 90,
+            HighwayType.PRIMARY_LINK: 60,
+            HighwayType.SECONDARY_LINK: 60,
+            HighwayType.TERTIARY_LINK: 60,
+            HighwayType.LIVING_STREET: 20,
+        }
+        return speeds[self] * 1000 / 60  # metres per minute

iduedu/enums/pt_enums.py

@@ -0,0 +1,25 @@
+from enum import Enum
+
+
+class PublicTrasport(Enum):
+    """
+    Enumeration class for edge types in graphs.
+    """
+
+    SUBWAY = "subway"
+    BUS = "bus"
+    TRAM = "tram"
+    TROLLEYBUS = "trolleybus"
+
+    @property
+    def avg_speed(self) -> float:
+        """
+        Average speed in m/min.
+        """
+        speeds = {  # km/h
+            PublicTrasport.SUBWAY: 40,
+            PublicTrasport.BUS: 20,
+            PublicTrasport.TRAM: 20,
+            PublicTrasport.TROLLEYBUS: 18,
+        }
+        return speeds[self] * 1000 / 60

iduedu/modules/downloaders.py

@@ -0,0 +1,126 @@
+import geopandas as gpd
+import osm2geojson
+import osmnx as ox
+import pandas as pd
+import requests
+from shapely import MultiPolygon, Polygon, unary_union
+
+from iduedu._config import config
+
+logger = config.logger
+
+
+class RequestError(RuntimeError):
+    def __init__(self, message, status_code=None, reason=None, response_text=None, response_content=None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.reason = reason
+        self.response_text = response_text
+        self.response_content = response_content
+
+    def __str__(self):
+        return f"{super().__str__()} (status: {self.status_code}, reason: {self.reason})"
+
+
+def get_boundary_by_osm_id(osm_id) -> MultiPolygon | Polygon:
+    overpass_query = f"""
+            [out:json];
+                    (
+                        relation({osm_id});
+                    );
+            out geom;
+            """
+    logger.debug(f"Downloading territory bounds with osm_id <{osm_id}> ...")
+    result = requests.get(config.overpass_url, params={"data": overpass_query}, timeout=config.timeout)
+    if result.status_code == 200:
+        json_result = result.json()
+        boundary = osm2geojson.json2geojson(json_result)
+        boundary = gpd.GeoDataFrame.from_features(boundary["features"]).set_crs(4326)
+        poly = unary_union(boundary.geometry)
+        return poly
+    raise RequestError(
+        message=f"Request failed with status code {result.status_code}, reason: {result.reason}",
+        status_code=result.status_code,
+        reason=result.reason,
+        response_text=result.text,
+        response_content=result.content,
+    )
+
+
+def get_boundary_by_name(territory_name: str) -> Polygon | MultiPolygon:
+    logger.debug(f"Downloading territory bounds with name <{territory_name}> ...")
+    place = ox.geocode_to_gdf(territory_name)
+    return unary_union(place.geometry)
+
+
+def get_boundary(
+    osm_id: int | None = None, territory_name: str | None = None, polygon: Polygon | MultiPolygon | None = None
+) -> Polygon:
+    """
+    Retrieve the boundary polygon for a given territory, either by OSM ID, territory name, or an existing polygon.
+    If a MultiPolygon is provided, it will be converted to a convex hull.
+
+    Parameters
+    ----------
+    osm_id : int, optional
+        OpenStreetMap ID of the territory to retrieve the boundary for.
+        Either this or `territory_name` must be provided.
+    territory_name : str, optional
+        Name of the territory to retrieve the boundary for. Either this or `osm_id` must be provided.
+    polygon : Polygon | MultiPolygon, optional
+        A custom polygon or MultiPolygon to use instead of querying by `osm_id` or `territory_name`.
+
+    Returns
+    -------
+    Polygon
+        The boundary polygon for the specified territory.
+        If a MultiPolygon was provided, it will return the convex hull.
+
+    Raises
+    ------
+    ValueError
+        If neither `osm_id`, `territory_name`, nor `polygon` are provided.
+
+    Examples
+    --------
+    >>> boundary = get_boundary(osm_id=123456)
+    >>> boundary = get_boundary(territory_name="New York")
+    >>> boundary = get_boundary(polygon=some_polygon)
+    """
+
+    if osm_id is None and territory_name is None and polygon is None:
+        raise ValueError("Either osm_id or name or polygon must be specified")
+    if osm_id:
+        polygon: Polygon = get_boundary_by_osm_id(osm_id)
+    elif territory_name:
+        polygon: Polygon = get_boundary_by_name(territory_name)
+
+    if isinstance(polygon, MultiPolygon):
+        polygon: Polygon = polygon.convex_hull
+
+    return polygon
+
+
+def get_routes_by_poly(polygon: Polygon, public_transport_type: str) -> pd.DataFrame:
+    polygon_coords = " ".join(f"{y} {x}" for x, y in polygon.exterior.coords[:-1])
+    overpass_query = f"""
+        [out:json];
+                (
+                    relation(poly:"{polygon_coords}")['route'='{public_transport_type}'];
+                );
+        out geom;
+        """
+    logger.debug(f"Downloading routes from OSM with type <{public_transport_type}> ...")
+    result = requests.post(config.overpass_url, data={"data": overpass_query}, timeout=config.timeout)
+    if result.status_code == 200:
+        json_result = result.json()["elements"]
+        data = pd.DataFrame(json_result)
+        data["transport_type"] = public_transport_type
+        return data
+    raise RequestError(
+        message=f"Request failed with status code {result.status_code}, reason: {result.reason}",
+        status_code=result.status_code,
+        reason=result.reason,
+        response_text=result.text,
+        response_content=result.content,
+    )

iduedu/modules/drive_walk_builder.py

@@ -0,0 +1,247 @@
+import re
+
+import geopandas as gpd
+import networkx as nx
+import osmnx as ox
+import pandas as pd
+from shapely import MultiPolygon, Polygon, unary_union
+from tqdm.auto import tqdm
+
+from iduedu import config
+from iduedu.enums.drive_enums import HighwayType
+from iduedu.modules.downloaders import get_boundary
+from iduedu.utils.utils import estimate_crs_for_bounds
+
+logger = config.logger
+
+BASE_FILTER = "['highway'~'" + "|".join([h.value for h in HighwayType]) + "']"
+
+
+def highway_type_to_reg(highway_type) -> int:
+    """
+    Determine the reg_status based on highway type.
+    """
+    try:
+        if isinstance(highway_type, list):
+            reg_values = [HighwayType[ht.upper()].reg_status for ht in highway_type]
+            return min(reg_values)
+        return HighwayType[highway_type.upper()].reg_status
+    except KeyError:
+        return 3
+
+
+def determine_reg(name_roads, highway_type=None) -> int:
+    """
+    Determine the reg_status based on road_name.
+    """
+
+    if isinstance(name_roads, list):
+        for item in name_roads:
+            if re.match(r"^[МАР]", str(item)):
+                return 1
+            if re.match(r"^\d.*[A-Za-zА-Яа-я]", str(item)):
+                return 2
+        return 3
+    if pd.isna(name_roads):
+        # Выставление значения по типу дороги, если значение NaN
+        if highway_type:
+            return highway_type_to_reg(highway_type)
+        return 3
+    if re.match(r"^[МАР]", str(name_roads)):
+        return 1
+    if re.match(r"^\d.*[A-Za-zА-Яа-я]", str(name_roads)):
+        return 2
+    return 3
+
+
+def get_max_speed(highway_types) -> float:
+    """
+    Determine the speed based on road_name.
+    """
+    # Проверяем, является ли highway_types списком.
+    try:
+        if isinstance(highway_types, list):
+            max_speeds = []
+            for ht in highway_types:
+                try:
+                    highway_enum = HighwayType[ht.upper()]
+                    max_speeds.append(highway_enum.max_speed)
+                except KeyError:
+                    logger.debug(f"{ht} not found in HighwayType enum, skipping.")
+            if max_speeds:
+                return max(max_speeds)
+            else:
+                logger.debug("No valid highway types provided, returning 40 km/h.")
+                return 40 * 1000 / 60
+        return HighwayType[highway_types.upper()].max_speed
+    except KeyError:
+        return 40 * 1000 / 60
+
+
+def get_drive_graph_by_poly(
+    polygon: Polygon | MultiPolygon, additional_edgedata=None, road_filter: str = None
+) -> nx.MultiDiGraph:
+    if additional_edgedata is None:
+        additional_edgedata = []
+    if not road_filter:
+        road_filter = BASE_FILTER
+    if isinstance(polygon, MultiPolygon):
+        polygon = unary_union(polygon)
+        if isinstance(polygon, MultiPolygon):
+            polygon = polygon.convex_hull
+
+    graph = ox.graph_from_polygon(
+        polygon,
+        network_type="drive",
+        custom_filter=road_filter,
+        truncate_by_edge=False,
+    )
+    local_crs = estimate_crs_for_bounds(*polygon.bounds).to_epsg()
+
+    nodes, edges = ox.graph_to_gdfs(graph)
+    edges: gpd.GeoDataFrame
+    edges.reset_index(inplace=True)
+    if "ref" not in edges.columns:
+        edges["ref"] = pd.NA
+    edges["reg"] = edges.apply(lambda row: determine_reg(row["ref"], row["highway"]), axis=1)
+
+    nodes.to_crs(local_crs, inplace=True)
+    nodes[["x", "y"]] = nodes.apply(lambda row: (row.geometry.x, row.geometry.y), axis=1, result_type="expand")
+    edges.to_crs(local_crs, inplace=True)
+
+    edges["maxspeed"] = edges["highway"].apply(get_max_speed)
+
+    edges[["length_meter", "time_min"]] = edges.apply(
+        lambda row: (round(row.geometry.length, 3), round(row.geometry.length / row.maxspeed, 3)),
+        axis=1,
+        result_type="expand",
+    )
+    edgesdata = ["u", "v", "key", "length_meter", "time_min", "geometry"] + additional_edgedata
+
+    edges = edges[edgesdata]
+
+    edges.set_index(["u", "v", "key"], inplace=True)
+    graph = ox.graph_from_gdfs(nodes, edges)
+    graph.graph["crs"] = local_crs
+    logger.debug('Done!')
+    return graph
+
+
+def get_drive_graph(
+    osm_id: int | None = None,
+    territory_name: str | None = None,
+    polygon: Polygon | MultiPolygon | None = None,
+    additional_edgedata=None,
+):
+    """
+    Generate a road network graph for driving within the specified territory or polygon.
+    Optionally, include additional edge data such as highway type, max speed, registration status and road name.
+
+    Parameters
+    ----------
+    osm_id : int, optional
+        OpenStreetMap ID of the territory to build the graph for. Either this or `territory_name` must be provided.
+    territory_name : str, optional
+        Name of the territory to build the graph for. Either this or `osm_id` must be provided.
+    polygon : Polygon | MultiPolygon, optional
+        A custom polygon or MultiPolygon to define the area for the road network. Must be in CRS 4326.
+    additional_edgedata : list[str], optional
+        List of additional edge data attributes to include in the graph. Possible values include
+        ['highway', 'maxspeed', 'reg', 'ref', 'name'] or any other, that exist in OSM. Defaults to None.
+
+    Returns
+    -------
+    networkx.Graph
+        A road network graph for the specified territory or polygon, with optional additional edge data.
+
+    Examples
+    --------
+    >>> drive_graph = get_drive_graph(osm_id=1114252)
+    >>> drive_graph = get_drive_graph(territory_name="Санкт-Петербург", additional_edgedata=['highway', 'maxspeed'])
+    >>> drive_graph = get_drive_graph(polygon=some_polygon, additional_edgedata=['name', 'ref'])
+
+    Notes
+    -----
+    Road speeds are defined in `iduedu.enums.drive_enums.py`.
+    The CRS for the graph is estimated based on the bounds of the provided/downloaded polygon, stored in G.graph['crs'].
+    """
+
+    polygon = get_boundary(osm_id, territory_name, polygon)
+
+    return get_drive_graph_by_poly(polygon, additional_edgedata=additional_edgedata)
+
+
+def get_walk_graph(
+    osm_id: int | None = None,
+    territory_name: str | None = None,
+    polygon: Polygon | MultiPolygon | None = None,
+    walk_speed: float = 5 * 1000 / 60,
+):
+    """
+    Generate a pedestrian road network graph within the specified territory or polygon.
+    The graph's edges includes calculated walking times based on the specified walking speed.
+
+    Parameters
+    ----------
+    osm_id : int, optional
+        OpenStreetMap ID of the territory to build the walking graph for.
+        Either this or `territory_name` must be provided.
+    territory_name : str, optional
+        Name of the territory to build the walking graph for. Either this or `osm_id` must be provided.
+    polygon : Polygon | MultiPolygon, optional
+        A custom polygon or MultiPolygon to define the area for the pedestrian network. Must be in CRS 4326.
+    walk_speed : float, optional
+        Walking speed in meters per minute. Defaults to 5 km/h (approximately 83.33 meters per minute).
+
+    Returns
+    -------
+    networkx.Graph
+        A pedestrian road network graph with edge lengths and walking times for the specified territory or polygon.
+
+    Examples
+    --------
+    >>> walk_graph = get_walk_graph(osm_id=1114252)
+    >>> walk_graph = get_walk_graph(territory_name="Санкт-Петербург", walk_speed=5)
+    >>> walk_graph = get_walk_graph(polygon=some_polygon)
+
+    Notes
+    -----
+    The CRS for the graph is estimated based on the bounds of the provided/downloaded polygon, stored in G.graph['crs'].
+    """
+
+    polygon = get_boundary(osm_id, territory_name, polygon)
+
+    logger.debug("Downloading walk graph from OSM ...")
+    graph = ox.graph_from_polygon(polygon, network_type="walk", truncate_by_edge=False, simplify=True)
+    local_crs = estimate_crs_for_bounds(*polygon.bounds).to_epsg()
+
+    nodes, edges = ox.graph_to_gdfs(graph)
+    nodes.to_crs(local_crs, inplace=True)
+    nodes[["x", "y"]] = nodes.apply(lambda row: (row.geometry.x, row.geometry.y), axis=1, result_type="expand")
+    nodes = nodes[["x", "y"]]
+    edges.reset_index(inplace=True)
+    edges.to_crs(local_crs, inplace=True)
+    tqdm.pandas(desc="Calculating the weights of the graph ...", disable=not config.enable_tqdm_bar)
+    edges[["length_meter", "time_min"]] = edges.progress_apply(
+        lambda row: (round(row.geometry.length, 3), round(row.geometry.length / walk_speed, 3)),
+        axis=1,
+        result_type="expand",
+    )
+    edges["type"] = "walk"
+    edges = edges[
+        [
+            "u",
+            "v",
+            "key",
+            "length_meter",
+            "time_min",
+            "type",
+            "geometry",
+        ]
+    ]
+    edges.set_index(["u", "v", "key"], inplace=True)
+    graph = ox.graph_from_gdfs(nodes, edges)
+    graph.graph["crs"] = local_crs
+    graph.graph["walk_speed"] = walk_speed
+    logger.debug('Done!')
+    return graph

iduedu/modules/intermodal_builder.py

@@ -0,0 +1,86 @@
+import concurrent.futures
+
+import networkx as nx
+from shapely import MultiPolygon, Polygon
+
+from iduedu import config
+from iduedu.modules.downloaders import get_boundary
+from iduedu.modules.drive_walk_builder import get_walk_graph
+from iduedu.modules.pt_walk_joiner import join_pt_walk_graph
+from iduedu.modules.public_transport_builder import get_all_public_transport_graph
+
+logger = config.logger
+
+
+def get_intermodal_graph(
+    osm_id: int | None = None,
+    territory_name: str | None = None,
+    polygon: Polygon | MultiPolygon | None = None,
+    clip_by_bounds: bool = False,
+    keep_routes_geom: bool = True,
+) -> nx.Graph:
+    """
+    Generate an intermodal transport graph that combines public transport and pedestrian networks,
+    with platforms serving as connection points between the two graphs.
+
+    Parameters
+    ----------
+    osm_id : int, optional
+        OpenStreetMap ID of the territory. Either this or `territory_name` must be provided.
+    territory_name : str, optional
+        Name of the territory to generate the intermodal transport network for.
+        Either this or `osm_id` must be provided.
+    polygon : Polygon | MultiPolygon, optional
+        A custom polygon or MultiPolygon defining the area for the intermodal network. Must be in CRS 4326.
+    clip_by_bounds : bool, optional
+        If True, clips the public transport network to the bounds of the provided polygon. Defaults to False.
+    keep_routes_geom : bool, optional
+
+    Returns
+    -------
+    nx.Graph
+        An intermodal network graph combining public transport and pedestrian routes, where public transport platforms
+        are linked to nearby walking routes.
+
+    Raises
+    ------
+    ValueError
+        If no valid `osm_id`, `territory_name`, or `polygon` is provided.
+
+    Warnings
+    --------
+    Logs a warning if the public transport graph is empty and only returns the pedestrian graph.
+
+    Examples
+    --------
+    >>> intermodal_graph = get_intermodal_graph(osm_id=1114252, clip_by_bounds=True)
+    >>> intermodal_graph = get_intermodal_graph(territory_name="Санкт-Петербург", polygon=some_polygon)
+
+    Notes
+    -----
+    The function concurrently downloads and processes both the pedestrian and public transport graphs,
+    then combines them using platforms as connection points.
+    If the public transport graph is empty, only the pedestrian graph is returned.
+    The CRS for the graph is estimated based on the bounds of the provided/downloaded polygon, stored in G.graph['crs'].
+    """
+
+    boundary = get_boundary(osm_id, territory_name, polygon)
+    with concurrent.futures.ThreadPoolExecutor() as executor:
+        walk_graph_future = executor.submit(get_walk_graph, polygon=boundary)
+        logger.debug("Started downloading and parsing walk graph...")
+        pt_graph_future = executor.submit(
+            get_all_public_transport_graph,
+            polygon=boundary,
+            clip_by_bounds=clip_by_bounds,
+            keep_geometry=keep_routes_geom,
+        )
+        logger.debug("Started downloading and parsing public trasport graph...")
+        pt_g = pt_graph_future.result()
+        logger.debug("Public trasport graph done!")
+        walk_g = walk_graph_future.result()
+        logger.debug("Walk graph done!")
+    if len(pt_g.nodes()) == 0:
+        logger.warning("Public trasport graph is empty! Returning only walk graph.")
+        return walk_g
+    intermodal = join_pt_walk_graph(pt_g, walk_g)
+    return intermodal