Skip to main content

downloading

downloading

Download data from the organizations that publish it.

load() is instant, offline and frozen: decadal snapshots of the Medium variant, which is what almost every model needs, and the default contact matrices (prem2021). fetch() adds the stores this package publishes with its releases. download() covers what neither of those has, straight from the UN:

Unlike the bundled and fetched data, this depends on a server this package does not control, which may be slow, change its files or be unavailable; the name says so at the call site. (download_shapes(), download_raster() and download_nodes() are the same for the spatial sources.)

It works by downloading the UN’s bulk CSVs – the same files laser-init uses – into the local cache and filtering them per call. No API token is needed (the WPP Data Portal API requires one; these files do not). The downloads are large, from 17 MB for the indicator file to 145 MB per half of the abridged life table, so they are cached and reused; see cache_info() and clear_cache().

For the five series that are also bundled, download returns exactly the schema load returns, so the two are interchangeable apart from resolution. life_table and indicators have no bundled counterpart and return the upstream shape.

import starsim_data as ssd
ssd.download('kenya', which='deaths', years=(2000, 2025))     # annual mx, not decadal
ssd.download('kenya', which='life_table', years=2020)         # qx, lx, ex, ...
ssd.download('kenya', which='births', variant='High')         # a different projection
ssd.download('kenya', which='indicators', years=(2020, 2030)) # CDR, TFR, LEx, IMR, ...

Functions

Name Description
download Download UN WPP data that is not packaged, caching it for next time.
list_downloadable Return the datasets download() can retrieve.

download

downloading.download(
    location,
    which='deaths',
    years=None,
    variant=DEFAULT_VARIANT,
    revision=None,
    refresh=False,
    verbose=None,
)

Download UN WPP data that is not packaged, caching it for next time.

Unlike load() and fetch(), this reaches the UN’s own server on a cache miss, which this package does not control: it may be slow, or revise its files. The name says so at the call site; see provenance() for pinning what was used.

Parameters

Name Type Description Default
location str location name, ISO-2/ISO-3 code, official name or alias, exactly as for load(). WPP is national, so not a subnational unit. required
which str 'births', 'deaths', 'migration', 'population', 'fertility' (the bundled series, at annual resolution), 'life_table' (the complete abridged life table), or 'indicators' (every WPP indicator). See list_downloadable(). 'deaths'
years int / tuple / list a single year; a 2-tuple (start, end), treated as an inclusive range; or an explicit list of years. None means all of 1950-2100, which for life tables means downloading both halves (~290 MB). None
variant str the projection variant, e.g. 'Medium' (default), 'High', 'Low', 'Constant fertility'. Life tables are Medium-only upstream. DEFAULT_VARIANT
revision str / int the WPP release to download, e.g. 2024. Defaults to the newest revision bundled with this package. 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
sciris.dataframe: for the five bundled series, exactly the schema load()
returns. For life_table, `[Time, Sex, AgeGrpStart, mx, qx, px, lx, dx, Lx, Sx,
Tx, ex, ax]with a glossary in.attrs[‘columns’]. Forindicators,Time`
plus every indicator column. Provenance is in .attrs['provenance'].

Raises

Type Description
ValueError if which, years, variant or revision cannot be satisfied.
KeyError if the location is unknown.

Example

import starsim_data as ssd
d = ssd.download('kenya', which='deaths', years=(2020, 2024))
lt = ssd.download('KEN', which='life_table', years=2020)

list_downloadable

downloading.list_downloadable()

Return the datasets download() can retrieve.

Example

import starsim_data as ssd
'life_table' in ssd.list_downloadable() # Returns True