rasters
Gridded population, and how to turn it into node populations.
This is the step that turns a boundary file into a metapopulation. load_nodes() gives you where each administrative unit is and how big it is; what it cannot give you, without a download, is how many people live in each one below the national level. That number comes from summing a 1 km gridded population raster inside each unit’s polygon:
import starsim_data as ssd
nodes = ssd.download_nodes('kenya', level=1) # the node table, with population filled in
ssd.distances('kenya', level=1) # ... and the distances between themWhich is everything a gravity model needs: P_i, P_j and D_ij.
Requires the [spatial] extra (pip install starsim_data[spatial]), because reading polygons and clipping rasters needs geopandas and rastertoolkit. Rasters are cached like every other download; WorldPop’s server is slow, so the first call for a country takes a while and later ones do not.
A caution worth carrying: WorldPop’s constrained estimates are modeled, not counted, and they will not equal the UN WPP national total for the same year – for Kenya 2020 they come out about 1% low. If a model needs the national total to match WPP exactly, rescale: nodes.population *= wpp_total / nodes.population.sum().
Functions
| Name | Description |
|---|---|
| aggregate_raster | Sum a raster inside each polygon: zonal statistics, keyed by an attribute. |
| download_nodes | The node table with population filled in, from WorldPop, at any level and year. |
| download_raster | Download a WorldPop 1 km gridded-population raster for a country, and cache it. |
| rescale_to_national | Scale node populations so they sum to this package’s national WPP total. |
aggregate_raster
rasters.aggregate_raster(raster, shapes, by='pcode', nearest=None)Sum a raster inside each polygon: zonal statistics, keyed by an attribute.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| raster | str / Path | a GeoTIFF, e.g. from download_raster(). | required |
| shapes | GeoDataFrame | polygons, e.g. from download_shapes(). | required |
| by | str | the column of shapes to key the result on. | 'pcode' |
| nearest | float | if given, also count a cell whose center is in no polygon but within this distance (in degrees) of one, for the nearest: boundaries are simplified at the coast, so otherwise a coastal city or a small island loses its people. | None |
Returns
| Name | Type | Description |
|---|---|---|
| dict | {key: total} for each polygon. |
Raises
| Type | Description |
|---|---|
| ImportError | if the [spatial] extra is not installed. |
| ValueError | if by is not a column of shapes. |
Example
import starsim_data as ssd
gdf = ssd.download_shapes('kenya', level=1)
ssd.aggregate_raster(ssd.download_raster('kenya'), gdf)download_nodes
rasters.download_nodes(
location,
level=1,
year=None,
source=None,
refresh=False,
verbose=None,
)The node table with population filled in, from WorldPop, at any level and year.
load_nodes() is instant and offline, with populations for 2020 at levels 0 and 1. This downloads the boundaries and the population raster for a country, sums the raster inside each unit, and returns the same table with the numbers filled in.
At a bundled level, the boundaries are downloaded from whichever source the bundled node table used for this country, so the p-codes line up and the join is exact rather than by name. At a finer level (2 and up), the table is built from the boundaries themselves, as the bundled one is, and which units share a border is worked out too and kept in .attrs['borders'], for adjacency(nodes=...).
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| location | str | location name, ISO-2/ISO-3 code, official name or alias. | required |
| level | int / str | administrative level (default 1). | 1 |
| year | int | population year (default: the node table’s, so level 0 and level 1 are for the same year). | None |
| source | str | override the boundary source; see list_shape_sources(). Leaving this alone is usually right – see above. | None |
| refresh | bool | re-download even if the files are already cached. | False |
| verbose | bool | report progress (default: options.verbose). |
None |
Returns
| Name | Type | Description |
|---|---|---|
sciris.dataframe: the node table for this location and level, with population |
||
filled and population_source / population_year recorded in |
||
.attrs['provenance']. |
Raises
| Type | Description |
|---|---|
| ImportError | if the [spatial] extra is not installed. |
| KeyError | if the location, its boundaries, or its raster cannot be found. |
Example
import starsim_data as ssd
nodes = ssd.download_nodes('kenya', level=1)download_raster
rasters.download_raster(location, year=None, refresh=False, verbose=None)Download a WorldPop 1 km gridded-population raster for a country, and cache it.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| location | str | location name, ISO-2/ISO-3 code, official name or alias. | required |
| year | int | the year to download (2000-2030). Defaults to the year the bundled node table uses for national population, so the two are comparable. | None |
| refresh | bool | re-download even if the file is already cached. | False |
| verbose | bool | report progress (default: options.verbose). |
None |
Returns
| Name | Type | Description |
|---|---|---|
| pathlib.Path: the cached GeoTIFF. |
Raises
| Type | Description |
|---|---|
| ValueError | if the year is outside WorldPop’s range. |
| KeyError | if WorldPop has no raster for this country and year. |
Example
import starsim_data as ssd
ssd.download_raster('kenya', year=2020)rescale_to_national
rasters.rescale_to_national(nodes, location=None, year=None)Scale node populations so they sum to this package’s national WPP total.
WorldPop and UN WPP disagree by a percent or two, and which one is “right” depends on the question. This makes the choice explicit rather than leaving two national totals silently in play.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| nodes | dataframe | a node table with population filled, from download_nodes(). |
required |
| location | str | the location; taken from the table if not given. | None |
| year | int | the WPP year to match; taken from the table’s provenance if not given. | None |
Returns
| Name | Type | Description |
|---|---|---|
sciris.dataframe: a copy with population rescaled. |
Example
import starsim_data as ssd
nodes = ssd.rescale_to_national(ssd.download_nodes('kenya'))