facilities

Facility data retrieval and management module for accessibility analysis.

This module provides functionality for retrieving, managing, and analyzing facility location data within specified administrative areas. It supports extracting facility data from OpenStreetMap (OSM), generating potential facility locations through grid sampling, and preparing data for accessibility and optimization analyses.

Examples

Retrieve existing facilities and generate potential facility locations:

>>> from pisa.administrative_area import AdministrativeArea
>>> from pisa.facilities import Facilities
>>>
>>> # Get administrative area boundaries
>>> admin_area = AdministrativeArea("Timor-Leste", admin_level=1)
>>> boundaries = admin_area.get_admin_area_boundaries("Baucau")
>>>
>>> # Create a facilities object
>>> facilities = Facilities(admin_area_boundaries=boundaries)
>>>
>>> # Get existing facilities from OpenStreetMap
>>> existing = facilities.get_existing_facilities()
>>> print(f"Found {len(existing)} existing facilities")
>>>
>>> # Generate potential facility locations (grid points)
>>> potential = facilities.estimate_potential_facilities(spacing=0.05)
>>> print(f"Generated {len(potential)} potential facility locations")

See also

administrative_area

Module for retrieving administrative area boundaries

population

Module for population data processing

isopolygons

Module for calculating service areas around facilities

Attributes

logger

Classes

Facilities

Retrieve and manage facility location data for a given administrative area.

Module Contents

facilities.logger
class facilities.Facilities

Retrieve and manage facility location data for a given administrative area.

This class provides functionality to retrieve existing facilities within a specified administrative area from various data sources (currently supporting OpenStreetMap).

Parameters:

  • admin_area_boundaries (Polygon or MultiPolygon) – The geographical boundaries of the administrative area for which to retrieve facilities

  • data_src (str, optional) – The data source from which to retrieve facility data. Currently supported: - “osm”: OpenStreetMap (default: osm)

  • osm_tags (dict, optional) – Dictionary of OpenStreetMap tags to identify facilities of interest (e.g., {'amenity': 'hospital'}). (default: OSM_TAGS)

Notes

The default OSM_TAGS are defined in the constants module and typically target health facilities. To use different facility types, provide custom osm_tags when creating the Facilities object.

See also

AdministrativeArea

Class for retrieving administrative area boundaries

IsopolygonCalculator

Class for calculating service areas around facilities

Examples

>>> from pisa.administrative_area import AdministrativeArea
>>> from pisa.facilities import Facilities
>>>
>>> # Get an administrative area for a specific country and region
>>> admin_area = AdministrativeArea("Timor-Leste", admin_level=1)
>>> boundaries = admin_area.get_admin_area_boundaries("Baucau")
>>>
>>> # Get hospital facilities within the administrative area
>>> facilities = Facilities(admin_area_boundaries=boundaries)
>>> existing_facilities = facilities.get_existing_facilities()
admin_area_boundaries: shapely.Polygon | shapely.MultiPolygon
data_src: str = 'osm'
osm_tags: dict
get_existing_facilities() → pandas.DataFrame

Retrieve existing facilities from the specified data source.

This method acts as a dispatcher that calls the appropriate data source-specific method based on the data_src attribute of the Facilities instance.

Returns:

DataFrame containing facilities information with columns:

  • osmid (index): Facility identifier (e.g., OSM ID for OpenStreetMap data)

  • longitude: Longitude coordinate of the facility

  • latitude: Latitude coordinate of the facility

Return type:

pandas.DataFrame

Raises:

NotImplementedError – If the specified data source is not implemented

Notes

Currently, only the osm (OpenStreetMap) data source is implemented. To support additional data sources, implement new methods and update this dispatcher method accordingly, or refactor to use an abstract base class.

estimate_potential_facilities(spacing: float = 0.05) → geopandas.GeoDataFrame

Create a grid of potential facility locations within the administrative area.

This method generates a regular grid of points within the administrative area boundaries that can be used as potential locations for new facilities in optimization scenarios.

Parameters:

spacing (float) – The distance between adjacent points in the grid, in coordinate units (degrees). Smaller values create a denser grid with more potential facility locations.

Returns:

GeoDataFrame containing potential facility locations with columns:

  • longitude: Longitude coordinate of the potential facility

  • latitude: Latitude coordinate of the potential facility

Return type:

geopandas.GeoDataFrame

Notes

The grid is created by:

  1. Finding the bounding box of the administrative area

  2. Creating a regular grid covering the entire bounding box

  3. Clipping the grid to include only points within the actual administrative area boundaries

The resulting grid points are spaced at regular intervals determined by the spacing parameter.