osm_road_network
================

.. py:module:: osm_road_network

.. autoapi-nested-parse::

   OpenStreetMap road network data retrieval and processing module.

   This module provides functionality for accessing and processing road network data from OpenStreetMap (OSM)
   for various transportation modes (driving, walking, cycling). It serves as the foundation for service area
   calculations and travel time/distance analyses in the PISA package.

   .. rubric:: Examples

   Retrieve and process a road network for walking travel time analysis:

   >>> from pisa.administrative_area import AdministrativeArea
   >>> from pisa.osm_road_network import OsmRoadNetwork
   >>>
   >>> # Get administrative area boundaries
   >>> admin_area = AdministrativeArea("Timor-Leste", admin_level=1)
   >>> boundaries = admin_area.get_admin_area_boundaries("Baucau")
   >>>
   >>> # Create a road network for walking travel time analysis
   >>> road_network = OsmRoadNetwork(
   >>>     admin_area_boundaries=boundaries,
   >>>     mode_of_transport="walking",
   >>>     distance_type="travel_time"
   >>> )
   >>>
   >>> # Get the processed network with travel time attributes
   >>> graph = road_network.get_osm_road_network()
   >>>
   >>> # Check some network statistics
   >>> print(f"Number of nodes: {len(graph.nodes)}")
   >>> print(f"Number of edges: {len(graph.edges)}")

   .. seealso::

      :obj:`isopolygons`
          Module for calculating service areas using road networks

      :obj:`administrative_area`
          Module for defining the geographic scope of the road network



Attributes
----------

.. autoapisummary::

   osm_road_network.logger


Classes
-------

.. autoapisummary::

   osm_road_network.OsmRoadNetwork


Module Contents
---------------

.. py:data:: logger

.. py:class:: OsmRoadNetwork(admin_area_boundaries: shapely.Polygon | shapely.MultiPolygon, mode_of_transport: str, distance_type: str, fallback_speed: int | float | None = None)

   Class to retrieve and process OpenStreetMap road network data.

   :param admin_area_boundaries: The geography of the administrative area object.
   :type admin_area_boundaries: Polygon | MultiPolygon
   :param mode_of_transport: The mode of transport for which the road network is required.
   :type mode_of_transport: str
   :param distance_type: The type of distance to be calculated.
   :type distance_type: str
   :param fallback_speed: The speed to be used for road types where OSM does not provide a speed attribute.
                          If not provided, osmnx will do the imputation (recommended).
   :type fallback_speed: int | float | None


   .. py:attribute:: admin_area_boundaries


   .. py:attribute:: distance_type


   .. py:attribute:: network_type


   .. py:method:: get_osm_road_network() -> networkx.MultiDiGraph

      Get the processed OpenStreetMap road network for the administrative area.

      This method retrieves the OSM road network for the specified administrative area and processes it according to
      the configured distance type. If the distance type is ``travel_time``, travel times are added to the network edges.

      :returns:

                NetworkX MultiDiGraph representing the road network with appropriate attributes:

                    - If distance_type is ``length``, the graph has ``length`` attributes on edges (in meters)
                    - If distance_type is ``travel_time``, the graph has ``travel_time`` attributes on edges (in minutes)
      :rtype: nx.MultiDiGraph