Skip to main content

rasters

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 them

Which 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'))