overlay

overlay(df, target, extensive=(), intensive=(), source=None, id_col='geo_id')

Area-weighted interpolation of a panel onto non-nested units.

Parameters

Name Type Description Default
df pd.DataFrame Panel with geo_id, optionally year, and the variables required
target A scale id or a GeoDataFrame with id_col and polygons (e.g. a grid) required
extensive Counts/totals (population, GDP): split by the share of each source unit’s area falling in the target, then summed ()
intensive Rates/averages (GDP per capita, HDI): area-weighted mean over the parts of source units inside the target ()
source The source scale or GeoDataFrame (default: inferred from geo_id) None

Notes

Assumes values are spread uniformly within each source unit. Returns one row per target unit (and year), with geo_id holding the target ids.

Example

!pip install -q geo4bolivia
import geo4bolivia as geo
import plotly.express as px
import geopandas as gpd
import numpy as np
from shapely.geometry import box

crs = geo.config()["equal_area_crs"]       # metres, equal area
x0, y0, x1, y1 = geo.boundaries("country").to_crs(crs).total_bounds
size = 50_000                              # 50 km cells
cells = [box(x, y, x + size, y + size) for x in np.arange(x0, x1, size)
         for y in np.arange(y0, y1, size)]
grid = gpd.GeoDataFrame({"cell": range(len(cells))}, geometry=cells, crs=crs)
grid = grid.to_crs("EPSG:4326")
pop = geo.load("sdg", variables="population", years=2024)
cells = geo.overlay(pop, grid, extensive=["population"], id_col="cell")
px.histogram(cells, x="population", title="Population on a 50 km grid")