aggregate
aggregate
Moving data between spatial scales.
aggregategoes up a nested hierarchy (e.g. municipality -> province -> country) using the published crosswalks and per-variable rules.overlaymoves data between scales that do not nest (grids, custom zones, historical boundaries) by area-weighted interpolation.
Functions
| Name | Description |
|---|---|
| aggregate | Aggregate a panel up to a coarser, nested scale (or to several at once). |
| overlay | Area-weighted interpolation of a panel onto non-nested units. |
| overlay_weights | Area of every source-target intersection, in an equal-area projection. |
aggregate
aggregate.aggregate(
df,
to,
dataset=None,
rules=None,
variables=None,
weights=None,
ref=None,
)Aggregate a panel up to a coarser, nested scale (or to several at once).
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| df | pd.DataFrame | Panel with geo_id, optionally year, and variable columns |
required |
| to | Target scale id, or a list of them (e.g. ["department", "country"]), each containing the source scale (see geo.ancestors) |
required | |
| dataset | str | None | Take each variable’s geo:aggregation rule from this dataset’s metadata |
None |
| rules | dict | None | Explicit rules that override the metadata, e.g. {"y": "weighted_mean:pop"} |
None |
| variables | Variables to aggregate (default: every numeric column except ids and year, leaving out, with a warning, those without a rule) | None |
|
| weights | pd.DataFrame | None | Extra columns to join on geo_id (and year if present) for weighted_mean rules whose weight is not already in df. When the dataset’s metadata names where a weight lives (geo:weights, e.g. census population), it is loaded automatically. |
None |
Returns
| Name | Type | Description |
|---|---|---|
| pandas.DataFrame | One row per target unit (and year) with n_units, the number of source units with data for at least one of the variables, and coverage, their share of all the source units in the target (1.0 when every unit has data). With a list of targets, the results are stacked with a scale column. |
overlay
aggregate.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.
overlay_weights
aggregate.overlay_weights(source, target, id_col='geo_id')Area of every source-target intersection, in an equal-area projection.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| source | Scale ids, or GeoDataFrames with id_col and polygons |
required | |
| target | Scale ids, or GeoDataFrames with id_col and polygons |
required | |
| id_col | str | The id column of GeoDataFrame inputs | 'geo_id' |
Returns
| Name | Type | Description |
|---|---|---|
| pandas.DataFrame | Columns geo_id_from, geo_id_to, area_km2, share_of_from (the part of the source unit inside the target) and share_of_to. |
Example
!pip install -q geo4bolivia
import geo4bolivia as geo
import plotly.express as px
df = geo.load("sdg04", variables="index_sdg4")
up = geo.aggregate(df, to=["department", "country"], dataset="sdg04")
up = geo.add_names(up[up["scale"] == "department"])
px.bar(up, x="name", y="index_sdg4", color="year", barmode="group",
labels=geo.labels(up), title="Education index by department (weighted)")