population

Population data retrieval and processing module for geographic analysis.

This module provides classes and functions for retrieving, processing, and analyzing population data from various sources such as Facebook’s Data for Good and WorldPop. It includes an abstract base class that defines the common interface, and concrete implementations for specific data sources.

The module supports retrieving population data within specified administrative boundaries, aggregating the data at different resolutions, and preparing it for accessibility analysis with facilities.

Examples

Retrieve and process population data from WorldPop:

>>> from pisa.administrative_area import AdministrativeArea
>>> from pisa.population import WorldpopPopulation
>>>
>>> # Get administrative area boundaries
>>> admin_area = AdministrativeArea("Timor-Leste", admin_level=1)
>>> boundaries = admin_area.get_admin_area_boundaries("Baucau")
>>> country_code = admin_area.get_iso3_country_code()
>>>
>>> # Create a population object and retrieve data
>>> population = WorldpopPopulation(
>>>     admin_area_boundaries=boundaries,
>>>     iso3_country_code=country_code
>>> )
>>>
>>> # Get processed population data as a GeoDataFrame
>>> population_gdf = population.get_population_gdf()
>>> print(f"Total population: {population_gdf['population'].sum()}")

Classes

`Population`	Abstract base class for Population data retrieval and processing.
`FacebookPopulation`	Population data from Facebook's High Resolution Population Density Maps.
`WorldpopPopulation`	Population data from WorldPop global population data.

Module Contents

class population.Population

Bases: abc.ABC

Abstract base class for Population data retrieval and processing.

This class provides the core functionality for retrieving and processing population data for a specified administrative area. Subclasses must implement the method get_population_data() to support different data sources.

Parameters:

admin_area_boundaries (Polygon or MultiPolygon) – The geographical boundaries of the administrative area for which to retrieve population data
iso3_country_code (str) – The ISO3 country code for the administrative area (e.g., TLS for Timor-Leste)
population_resolution (int, optional) – The decimal precision to which latitude and longitude coordinates are rounded for aggregation purposes (default: 5)

admin_area_boundaries: shapely.Polygon | shapely.MultiPolygon

iso3_country_code: str

population_resolution: int = 5

get_population_gdf() → geopandas.GeoDataFrame

Get aggregated population data for the administrative area as a GeoDataFrame.

This method integrates the population data retrieval workflow by:

Retrieving raw population data using the specific implementation of the get_population_data() method

Aggregating the population data based on the specified resolution

Returns:

Aggregated population data with columns:

longitude: Rounded longitude coordinate

latitude: Rounded latitude coordinate

population: Total population at the coordinate

geometry: Point geometry representing the coordinate

ID: Unique identifier for each point

Return type:

geopandas.GeoDataFrame

class population.FacebookPopulation

Bases: Population

Population data from Facebook’s High Resolution Population Density Maps.

This class retrieves and processes population data from Facebook’s Data for Good program, which provides high-resolution population density maps. The data is accessed via the Humanitarian Data Exchange (HDX) platform.

The class follows the same initialization pattern as its parent class Population.