visualisation

Data visualization module for spatial accessibility analysis.

This module provides functions for creating interactive maps and visualizations of facilities, population data, and isopolygons (service areas). It helps in visualizing spatial relationships between facilities and population, service coverage areas, and optimization scenarios.

The visualizations use Folium (based on Leaflet.js) to create interactive web maps that can be displayed in notebooks, web applications, or exported as HTML files.

Examples

Create interactive maps for facilities and population:

>>> from pisa.administrative_area import AdministrativeArea
>>> from pisa.facilities import Facilities
>>> from pisa.population import WorldpopPopulation
>>> from pisa.visualisation import plot_facilities, plot_population
>>>
>>> # Get administrative area and data
>>> admin_area = AdministrativeArea("Timor-Leste", admin_level=1)
>>> boundaries = admin_area.get_admin_area_boundaries("Baucau")
>>> country_code = admin_area.get_iso3_country_code()
>>>
>>> # Get facilities data
>>> facilities = Facilities(admin_area_boundaries=boundaries)
>>> existing_facilities = facilities.get_existing_facilities()
>>>
>>> # Get population data
>>> population = WorldpopPopulation(
>>>     admin_area_boundaries=boundaries,
>>>     iso3_country_code=country_code
>>> )
>>> population_gdf = population.get_population_gdf()
>>>
>>> # Create interactive maps
>>> facility_map = plot_facilities(existing_facilities, boundaries)
>>> population_map = plot_population(population_gdf, boundaries)

See also

facilities

Module for facility data processing

population

Module for population data processing

isopolygons

Module for generating service area polygons

Functions

plot_facilities(→ folium.Map)	Plot facilities on an interactive map with administrative area boundaries.
plot_population_heatmap(→ folium.Map)	Create a heatmap visualization of population density.
plot_population(→ folium.Map)	Plot population points on an interactive map.
plot_isochrones(→ folium.Map)	Plot isochrones/isopolygons for multiple facilities on an interactive map.
plot_results(→ folium.Map)	Plot optimization results showing existing and proposed facility locations.

Module Contents

visualisation.plot_facilities(df_facilities: pandas.DataFrame, admin_area_boundaries: shapely.geometry.MultiPolygon | shapely.geometry.Polygon, df_potential_facilities: pandas.DataFrame | None = None, tiles='OpenStreetMap') → folium.Map

Plot facilities on an interactive map with administrative area boundaries.

This function creates a Folium map showing existing facilities as blue circle markers, and optionally potential facilities as orange circle markers, within the context of administrative area boundaries.

Parameters:

• df_facilities (pandas.DataFrame) –

  DataFrame containing information about existing facilities. Must have columns:

  • latitude: Latitude coordinate of the facility

  • longitude: Longitude coordinate of the facility

• admin_area_boundaries (MultiPolygon or Polygon) – Shapely geometry representing the boundaries of the administrative area

• df_potential_facilities (pandas.DataFrame, optional) –

  DataFrame containing information about potential facility locations. Must have columns:

  • latitude: Latitude coordinate of the potential facility

  • longitude: Longitude coordinate of the potential facility

• tiles (str, optional) – The tile provider for the base map. Any valid Folium tile provider name can be used. See folium.Map documentation for available options. (default: OpenStreetMap)

Returns:

Interactive Folium map with administrative boundaries and facility markers

Return type:

folium.Map

visualisation.plot_population_heatmap(df_population: pandas.DataFrame, admin_area_boundaries: shapely.geometry.MultiPolygon | shapely.geometry.Polygon, tiles='OpenStreetMap') → folium.Map

Create a heatmap visualization of population density.

This function generates an interactive Folium map displaying population density as a heatmap within the specified administrative area boundaries.

Parameters:

• df_population (pandas.DataFrame) –

  DataFrame containing population data. Must have columns:

  • latitude: Latitude coordinate

  • longitude: Longitude coordinate

  • population: Population value (intensity for the heatmap)

• admin_area_boundaries (MultiPolygon or Polygon) – Shapely geometry representing the boundaries of the administrative area

• tiles (str, optional) – The tile provider for the base map. Any valid Folium tile provider name can be used. See folium.Map documentation for available options. (default: OpenStreetMap)

Returns:

Interactive Folium map with population heatmap visualization

Return type:

folium.Map

visualisation.plot_population(df_population: pandas.DataFrame, admin_area_boundaries: shapely.geometry.MultiPolygon | shapely.geometry.Polygon, random_sample_n: int | None = None, tiles='OpenStreetMap') → folium.Map

Plot population points on an interactive map.

This function creates a Folium map showing population points as circle markers, with size and opacity reflecting the relative population values.

Parameters:

• df_population (pandas.DataFrame) –

  DataFrame containing population data. Must have columns:

  • latitude: Latitude coordinate

  • longitude: Longitude coordinate

  • population: Population value at that point

• admin_area_boundaries (MultiPolygon or Polygon) – Shapely geometry representing the boundaries of the administrative area

• random_sample_n (int, optional) – Number of population points to randomly sample and display. If None, all points will be displayed (can be performance-intensive for large datasets) (default: None)

• tiles (str, optional) – The tile provider for the base map. Any valid Folium tile provider name can be used. See folium.Map documentation for available options. (default: OpenStreetMap)

Returns:

Interactive Folium map with population points displayed

Return type:

folium.Map

visualisation.plot_isochrones(df_isopolygons: pandas.DataFrame, admin_area_boundaries: shapely.geometry.MultiPolygon | shapely.geometry.Polygon, tiles: str = 'OpenStreetMap') → folium.Map

Plot isochrones/isopolygons for multiple facilities on an interactive map.

This function creates a Folium map displaying isopolygons (areas reachable within specific travel times or distances) around facilities, with different colors for each facility and varying opacity for different time/distance thresholds.

Parameters:

• df_isopolygons (pandas.DataFrame) –

  DataFrame containing isopolygon geometries. Should have:

  • Index representing unique facility identifiers

  • Columns named ID_X where X is the distance/time threshold (e.g., ID_10 for 10-minute isochrone)

  • Each cell contains a Shapely Polygon or MultiPolygon

• admin_area_boundaries (MultiPolygon or Polygon) – Shapely geometry representing the boundaries of the administrative area

• tiles (str, optional) – The tile provider for the base map. Any valid Folium tile provider name can be used. See folium.Map documentation for available options. (default: OpenStreetMap)

Returns:

Interactive Folium map with isopolygons visualized

Return type:

folium.Map

visualisation.plot_results(open_locations: list, current: pandas.DataFrame, total_fac: pandas.DataFrame, admin_area_boundaries: shapely.geometry.MultiPolygon | shapely.geometry.Polygon) → folium.Map

Plot optimization results showing existing and proposed facility locations.

This function creates a Folium map displaying the results of a facility location optimization model, showing both existing facilities and proposed new facilities.

Parameters:

• open_locations (list) – List of facility identifiers (matching indices in total_fac) that are selected as part of the optimization solution (both existing and new)

• current (pandas.DataFrame) – DataFrame containing information about existing facilities, with a column Cluster_ID that identifies each facility

• total_fac (pandas.DataFrame) –

  DataFrame containing information about all facility locations (both existing and potential). Must have:

  • Index matching the identifiers in open_locations

  • Columns latitude and longitude for facility coordinates

• admin_area_boundaries (MultiPolygon or Polygon) – Shapely geometry representing the boundaries of the administrative area

Returns:

Interactive Folium map showing optimization results with markers

Return type:

folium.Map

Notes

• Existing facilities are shown with blue hospital icons

• Proposed new facilities are shown with purple question mark icons