Skip to main content

Starsim Data

This package provides demographic data, contact matrices, and administrative geography for Starsim (although it can of course be used for other applications as well). Commonly used data are available offline, while more detailed data are downloaded and cached.

import starsim_data as ssd

ssd.list_datasets()                    # What's available
ssd.load('kenya', which='deaths')      # UN mortality rates by age and sex
ssd.load('kenya', which='contacts')    # A contact matrix
ssd.load_nodes('kenya', level=1)       # Kenya's 47 counties: locations, areas, populations
ssd.provenance('prem')                 # Where the data came from, and how to cite it
ssd.plot('kenya')                      # See what the data look like before

Location naming is flexible: 'Kenya', 'kenya', 'KE', 'KEN' and 'Republic of Kenya' all work, as do common abbreviations ('USA', 'UK', 'DRC') and names with or without accents ("Côte d'Ivoire", 'cote divoire').

Documentation: https://starsim.org/starsim_data

Installation

Note: starsim_data is installed as part of Starsim, so typically you don't need to install it separately.

pip install starsim_data # Standard usage
pip install starsim_data[spatial] # For geospatial data/mapping

What's included

Everything is reached through a handful of functions. All of them take a location ('kenya') and return a dataframe, except where noted:

Function What it gives you Internet?
load(loc, which=...) Demographics and contact matrices bundled in the package (below) Never
load_nodes(loc, level=...) Subnational units: names, p-codes, centers, areas, populations Never
distances(loc, level=...), adjacency(...) Distances between those units, and which share a border Never
fetch(loc, which=...) Contact matrices not bundled for space, and US state populations First use only
download(loc, which=...) UN data not bundled: every year, life tables, all indicators, other projections First use only
download_shapes(), download_nodes(), download_raster() Boundary shapes (a GeoDataFrame), finer levels and other years, WorldPop grids (a file path); need [spatial] First use only
plot(loc) A quick look at the data, as a figure Never
choropleth(loc, level=...) A map of the units, colored by population; needs [spatial] First use only
provenance(which) Source, license and citation for a dataset Never
list_datasets(), list_locations(which), resolve(loc) What's available, and which location a name resolves to Never

ssd.list_datasets(detailed=True) lists every dataset with a short description, whether it is bundled, fetched or downloaded, and how many locations it covers. Anything fetched or downloaded is cached, so it is only downloaded once.

Demographics (UN World Population Prospects 2024)

From the UN World Population Prospects 2024 (WPP), for 187 countries, every 10 years from 1950 to 2100, using the UN's main (Medium) projection:

which= What it is Age groups Columns
births Crude birth rate (per 1,000) — Time, CBR
deaths Mortality rate by age and sex 5-year (0, 1–4, 5–9, …, 100+) Time, Sex, AgeGrpStart, mx
migration Crude net migration rate (per 1,000) — Time, CNMR
population Population by age and sex 5-year (0–4, …, 100+) Time, Sex, AgeGrp, Value
fertility Age-specific fertility rate (per 1,000 women) 5-year age of mother (10–14, …, 50–54) Time, AgeGrpStart, ASFR

These go straight into Starsim: deaths into ss.Deaths, births into ss.Births, fertility into ss.Pregnancy, and population gives the starting age structure.

Annual data, full life tables, other UN indicators and other projections (High, Low, …) aren't included, but can be downloaded from the UN (see below). There is no subnational demographic data, and migration is a crude rate only, as the UN publishes it.

Contact matrices

The average number of daily contacts between age groups, for five settings (all, home, work, school, community), chosen with kind=. Rows and columns are labeled by the youngest age in each group, so M.loc[25, 30] is contacts between 25–29 and 30–34 year olds. These were adapted from the excellent epydemix-data project.

which= Included Age groups Countries Study
contacts or prem (default) ✅ 5-year (0–4, …, 75+) 187 prem2021, plus prem2017 for the ten countries it lacks
prem2021 ✅ 5-year 177 Prem et al. 2021
prem2017 ⬇️ fetch() 5-year 152 Prem et al. 2017
mistry2021 ⬇️ fetch() single year (0–84+) 36 Mistry et al. 2021
mistry2021_us ⬇️ fetch() single year (0–84+) 50 US states and DC Mistry et al. 2021

prem2021 is the authors' update of prem2017, using more surveys and newer data. The default (contacts, listed by list_datasets() as prem) uses prem2021, and falls back to prem2017 for the ten countries it dropped (such as Japan and Australia). The fetched sources are a few MB each, and are downloaded the first time you use them:

ssd.fetch('japan', which='prem2017', kind='home')
ssd.fetch('france', which='mistry2021')                                # single years of age
ssd.fetch('United States:Massachusetts', which='mistry2021_us')        # a US state
ssd.fetch('United States:Massachusetts', which='population_us')        # its population by single year of age

Not every country is in every source. You can use e.g. ssd.list_locations('mistry2021') to list which ones are.

Geography

For spatial models, the node table describes each country and its states or provinces, for 184 countries: basic geography, how many people live there, and which others it borders. It is included in the package and needs no extra software:

ssd.load_nodes('kenya', level=1)       # 47 counties: name, latitude/longitude, area, population
ssd.distances('kenya', level=1)        # distances between them, in km
ssd.adjacency('kenya', level=1)        # which counties share a border

Populations are the UN's for countries and WorldPop's 2020 estimates for states and provinces. Each unit has a pcode, the code that most subnational health data uses for it, so you can join your own data on. Together, populations and distances are what a gravity model of travel between places needs.

Maps, finer levels (districts, sub-counties) and other years need the optional geospatial packages, and are downloaded on demand:

pip install starsim_data[spatial]
ssd.download_shapes('kenya', level=2)   # boundaries of Kenya's 290 sub-counties
ssd.download_nodes('kenya', level=2)    # the node table for them, with WorldPop populations
ssd.choropleth('kenya', level=1)        # a map, colored by population

Boundaries come from UNOCHA or geoBoundaries. GADM is also available, but only if you ask for it (source='gadm'), because its license allows non-commercial use only.


Data that isn't included

load() uses data bundled in the package. For data that isn't included, there are two "tiers" of download:

  • fetch() downloads data that this package stores on GitHub as a release asset, but doesn't bundle with the install for space reasons. These are the contact matrices above, plus US state population sizes.
  • download() downloads data directly from the original source, such as the UN. These servers are outside this package's control, so they may be slow, change their data, or be unavailable. download_shapes(), download_nodes() and download_raster() do the same for boundaries and WorldPop.
ssd.download('kenya', which='deaths', years=(2000, 2025))   # annual rather than every 10 years
ssd.download('kenya', which='life_table', years=2020)       # the full life table: qx, lx, ex, ...
ssd.download('kenya', which='births', variant='High')       # the UN's High projection
ssd.download('kenya', which='indicators', years=2020)       # TFR, life expectancy, IMR and ~50 more

The UN's files are large (up to a few hundred MB), so everything downloaded is cached; ssd.cache_info() shows what has been saved, and ssd.clear_cache() deletes it.

Checking the data

ssd.plot('kenya') draws the age pyramid, birth rate, mortality curve and contact matrix for a country, and ssd.plot('kenya', which='deaths', year=2050) draws just one. It's meant to catch the wrong country or the wrong units before they reach a simulation, not to make publication figures.

Citing

Please cite the sources of the data you use: the UN World Population Prospects 2024 for demographics, the contact-matrix study for each source you use, and WorldPop and the boundary source for geography. ssd.provenance() gives the citation and license for each dataset, and every dataframe carries the same in df.attrs['provenance']:

ssd.provenance('mistry2021').citation   # 'Mistry D, Litvinova M, ...'
ssd.provenance('deaths').license        # 'CC BY 3.0 IGO'

NOTICE.md has the full attributions.

This package builds on two others: epydemix-data, where the contact matrices come from, and laser-init, which sets up spatial models for LASER and is where the approach to boundaries and populations comes from. See Related projects for more information.

Contributing

CONTRIBUTING.md covers changing the code or the data, building the documentation, and making a release.

License

The code is licensed under the MIT License. The data itself is licensed under several different licenses. The UN WPP data is under CC BY 3.0 IGO, the contact matrices under GPL-3.0 (prem2017, prem2021) and Apache-2.0 (mistry2021), and the node table under CC BY 3.0 IGO (UNOCHA) and CC BY 4.0 (geoBoundaries, WorldPop). See NOTICE.md and licenses/ for details.

AI disclosure

Many tokens (mainly from Claude Opus 5.5) were harmed in the making of this repo. We believe in transparency around AI use. On most pages you will see a small marker like "🧠5% 🤖95%". This means that humans wrote 5% of the content, and AI wrote the other 95% (hover for details). We know reading AI-generated text can get tiring, so our long-term goal is to replace as much of it as possible.

Metadata

Release files for starsim-data 2.2.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for starsim-data 2.2.2
File Size Uploaded Provenance Actions
starsim_data-2.2.2.tar.gz 2.6 MB With provenance Details for starsim_data-2.2.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for starsim-data 2.2.2
File Interpreter ABI Platform Actions
starsim_data-2.2.2-py3-none-any.whl Python 3 none any Details for starsim_data-2.2.2-py3-none-any.whl

Total release size: 4.9 MB

Release files / starsim_data-2.2.2.tar.gz

Download URL starsim_data-2.2.2.tar.gz
Size 2.6 MB
Tags Source
SHA-256 checksum
How to use checksums
025fe870ada741c5ae767721e3e5c59153658c31732888f6cc0bea96bc1f0998
BLAKE2b-256 checksum
How to use checksums
4ea849d3056d7e10c8b82625122461938fe552c97ba7fc064cc94f4c213e5b2c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / starsim_data-2.2.2-py3-none-any.whl

Download URL starsim_data-2.2.2-py3-none-any.whl
Size 2.3 MB
Tags Python 3
SHA-256 checksum
How to use checksums
31c5cbc3d27209e99896e9c229547db3966468b1304ed1b86ee33b123b921e90
BLAKE2b-256 checksum
How to use checksums
cf8705c911ca22713007a3a850413b78e349fb443eacf7cf9d9184f92310110f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Security for starsim-data 2.2.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for starsim_data-2.2.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page