isopolygons

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.

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.

Attributes

logger

Classes

`IsopolygonCalculator`	Abstract base class for isopolygon calculation.
`OsmIsopolygonCalculator`	OpenStreetMap-based implementation of isopolygon calculation.
`MapboxIsopolygonCalculator`	Mapbox-based implementation of isopolygon calculation.

Module Contents

isopolygons.logger

class isopolygons.IsopolygonCalculator(facilities_df: pandas.DataFrame, distance_type: str, distance_values: int | list[int])

Bases: abc.ABC

Abstract base class for isopolygon calculation.

facilities_df

distance_type

distance_values

abstract calculate_isopolygons() → pandas.DataFrame

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

Return type:

pandas.DataFrame

Raises:

NotImplementedError – If this method is not implemented by a subclass

class isopolygons.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: 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.

Parameters:

facilities_df (pandas.DataFrame) – DataFrame containing facility locations with longitude and latitude columns
distance_type (str) – Type of distance to calculate (length or travel_time)
distance_values (list[int]) – List of distance values in meters (for length) or minutes (for travel_time)
road_network (networkx.MultiDiGraph) – Road network graph to use for calculations
node_buffer (float, optional) – Buffer distance to apply around network nodes. (default: 0.001)
edge_buffer (float, optional) – Buffer distance to apply around network edges. (default: 0.0005)