isopolygons =========== .. py:module:: isopolygons .. autoapi-nested-parse:: Isopolygon calculation module for service area analysis. This module provides functionality for calculating isopolygons around facilities using different methods and services. An isopolygon represents the area that can be reached within a specific distance (isodistance) or time (isochrone) from a facility. The module contains an abstract base class IsopolygonCalculator and its implementations for different calculation methods. .. rubric:: Examples Calculate isochrones around facilities using OpenStreetMap: >>> from pisa.administrative_area import AdministrativeArea >>> from pisa.facilities import Facilities >>> from pisa.osm_road_network import OsmRoadNetwork >>> from pisa.isopolygons import OsmIsopolygonCalculator >>> >>> # Get administrative area and facilities >>> admin_area = AdministrativeArea("Timor-Leste", admin_level=1) >>> boundaries = admin_area.get_admin_area_boundaries("Baucau") >>> facilities = Facilities(admin_area_boundaries=boundaries) >>> existing_facilities = facilities.get_existing_facilities() >>> >>> # Create a road network for travel time calculations >>> road_network = OsmRoadNetwork( >>> admin_area_boundaries=boundaries, >>> mode_of_transport="walking", >>> distance_type="travel_time" >>> ) >>> graph = road_network.get_osm_road_network() >>> >>> # Calculate isochrones (5, 10, 15 minutes walking) >>> isopolygon_calculator = OsmIsopolygonCalculator( >>> facilities_df=existing_facilities, >>> distance_type="travel_time", >>> distance_values=[5, 10, 15], >>> road_network=graph >>> ) >>> isopolygons = isopolygon_calculator.calculate_isopolygons() .. note:: To implement a new way of calculating isopolygons (e.g., using Google Maps), create a class that inherits from IsopolygonCalculator and implements calculate_isopolygons. .. seealso:: :obj:`facilities` Module for retrieving facility locations :obj:`osm_road_network` Module for retrieving and processing road networks :obj:`population_served_by_isopolygons` Module for analyzing population coverage Attributes ---------- .. autoapisummary:: isopolygons.logger Classes ------- .. autoapisummary:: isopolygons.IsopolygonCalculator isopolygons.OsmIsopolygonCalculator isopolygons.MapboxIsopolygonCalculator Module Contents --------------- .. py:data:: logger .. py:class:: IsopolygonCalculator(facilities_df: pandas.DataFrame, distance_type: str, distance_values: int | list[int]) Bases: :py:obj:`abc.ABC` Abstract base class for isopolygon calculation. .. py:attribute:: facilities_df .. py:attribute:: distance_type .. py:attribute:: distance_values .. py:method:: calculate_isopolygons() -> pandas.DataFrame :abstractmethod: Calculate isopolygons for the specified facilities. This abstract method must be implemented by subclasses to provide the actual implementation of isopolygon calculation using specific data sources and algorithms. Specific implementations should provide detailed error handling and logging appropriate to their data sources and algorithms. :returns: DataFrame containing isopolygons with the following structure: - Each row represents a facility from facilities_df - One column named ``ID_{distance}`` for each distance value in distance_values, where {distance} is the distance value in meters or minutes - Each cell contains a Shapely ``Polygon`` or ``MultiPolygon`` representing the area that can be reached within the corresponding distance :rtype: pandas.DataFrame :raises NotImplementedError: If this method is not implemented by a subclass .. py:class:: OsmIsopolygonCalculator(facilities_df: pandas.DataFrame, distance_type: str, distance_values: list[int], road_network: networkx.MultiDiGraph, node_buffer: float = 0.001, edge_buffer: float = 0.0005) Bases: :py:obj:`IsopolygonCalculator` OpenStreetMap-based implementation of isopolygon calculation. This implementation uses OpenStreetMap road network data to calculate isopolygons (isochrones or isodistances) around facilities. It leverages the NetworkX and OSMnx libraries for network analysis. This implementation performs network-based calculations on an OSM road network, which provides accurate results but may be computationally intensive for large areas or many facilities. :param facilities_df: DataFrame containing facility locations with ``longitude`` and ``latitude`` columns :type facilities_df: pandas.DataFrame :param distance_type: Type of distance to calculate (``length`` or ``travel_time``) :type distance_type: str :param distance_values: List of distance values in meters (for ``length``) or minutes (for ``travel_time``) :type distance_values: list[int] :param road_network: Road network graph to use for calculations :type road_network: networkx.MultiDiGraph :param node_buffer: Buffer distance to apply around network nodes. (default: ``0.001``) :type node_buffer: float, optional :param edge_buffer: Buffer distance to apply around network edges. (default: ``0.0005``) :type edge_buffer: float, optional .. seealso:: :obj:`IsopolygonCalculator` Abstract base class :obj:`MapboxIsopolygonCalculator` Mapbox API-based implementation .. py:attribute:: road_network .. py:attribute:: node_buff :value: 0.001 .. py:attribute:: edge_buff :value: 0.0005 .. py:attribute:: nearest_nodes_dict .. py:method:: calculate_isopolygons() -> pandas.DataFrame Calculate isopolygons for each facility at different distances. This method generates isopolygons (areas reachable within specific travel times or distances) for each facility using the OpenStreetMap road network data. :returns: DataFrame containing isopolygons with the following structure: - Each row represents a facility from facilities_df - One column named ``ID_{distance}`` for each distance value in distance_values, where {distance} is the distance value in meters or minutes - Each cell contains a Shapely ``Polygon`` or ``MultiPolygon`` representing the area that can be reached within the corresponding distance :rtype: pandas.DataFrame .. rubric:: Notes - Distances are computed with respect to the nearest node to the facility, not the facility itself - The method creates network "skeletons" and then buffers nodes and edges separately with different buffer sizes to create accurate isopolygons .. py:class:: MapboxIsopolygonCalculator(facilities_df: pandas.DataFrame, distance_type: str, distance_values: list[int], mode_of_transport: str, mapbox_api_token: str, base_url: str = 'https://api.mapbox.com/isochrone/v1/') Bases: :py:obj:`IsopolygonCalculator` Mapbox-based implementation of isopolygon calculation. This implementation uses the Mapbox Isochrone API to calculate isopolygons (isochrones or isodistances) around facilities. :param facilities_df: DataFrame containing facility locations with ``longitude`` and ``latitude`` columns :type facilities_df: pandas.DataFrame :param distance_type: Type of distance to calculate (``length`` or ``travel_time``) :type distance_type: str :param distance_values: List of distance values in meters (for ``length``) or minutes (for ``travel_time``) Maximum of 4 values allowed by the Mapbox API :type distance_values: list[int] :param mode_of_transport: The mode of transport to use (must be one of ``driving``, ``walking``, ``cycling``) :type mode_of_transport: str :param mapbox_api_token: A valid Mapbox API access token with Isochrone API permissions :type mapbox_api_token: str :param base_url: The base URL for the Mapbox Isochrone API, default is 'https://api.mapbox.com/isochrone/v1/' :type base_url: str, optional .. seealso:: :obj:`IsopolygonCalculator` Abstract base class :obj:`OsmIsopolygonCalculator` OSM-based implementation with precise node/edge buffering .. rubric:: Notes From Mapbox docs: When providing geographic coordinates to a Mapbox API, they should be formatted in the order longitude, latitude and specified as decimal degrees in the WGS84 coordinate system. This pattern matches existing standards, including GeoJSON and KML. This implementation is subject to Mapbox API rate limits and requires a valid Mapbox account and access token. .. py:attribute:: mapbox_api_token .. py:attribute:: route_profile .. py:attribute:: distance_values .. py:attribute:: base_url :value: 'https://api.mapbox.com/isochrone/v1/' .. py:attribute:: contour_type :value: 'contours_meters' .. py:method:: calculate_isopolygons() -> pandas.DataFrame Calculate isopolygons for all facilities using the Mapbox API. This method generates isopolygons (areas reachable within specific travel times or distances) for each facility using the Mapbox Isochrone API. :returns: DataFrame containing isopolygons with the following structure: - Each row represents a facility from facilities_df - One column named ``ID_{distance}`` for each distance value in distance_values, where {distance} is the distance value in meters or minutes - Each cell contains a Shapely ``Polygon`` or ``MultiPolygon`` representing the area that can be reached within the corresponding distance :rtype: pandas.DataFrame .. rubric:: Notes - Requires a valid Mapbox API token with appropriate permissions - Subject to Mapbox API rate limits (300 requests per minute) - Makes one API request per facility (not per distance value) - The API returns GeoJSON features that are converted to Shapely geometries