Skip to main content

Starsim Data

License: MIT

Demographic data, contact matrices and administrative geography for disease modeling with Starsim, ready to use with one function call and no internet connection.

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', kind='home')         # a contact matrix for household contacts
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')                      # check it by eye before it goes into a model

Countries can be named however you like: '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'). A name that isn't recognized gives an error with suggestions, rather than a guess.

Documentation: https://starsim.org/starsim_data

Installation

pip install starsim_data

What's included

ssd.load() returns a dataframe that works like a pandas one.

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
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

The default, prem2021, is the authors' update of prem2017, using more surveys and newer data; for the ten countries it dropped (such as Japan and Australia), the default falls back to prem2017. The other 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; ssd.list_locations('mistry2021') lists the ones that are.

Geography

For spatial models, the node table describes each country and its states or provinces, for 184 countries: where each one is, how big it is, 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() never uses the internet, so it is instant, works offline, and gives everyone the same data for a given version of the package. Data that isn't included comes one of two ways, and the function name tells you which:

  • fetch() downloads data that this package prepares and publishes, but doesn't include to save space: the contact matrices above. It is the same for everyone on a version.
  • download() gets data from the organization that publishes it, 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 saved on your computer and reused next time; 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. Related projects compares them, and other ways of getting the same data.

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 keeps its original licenses: the UN WPP data is under CC BY 3.0 IGO, and the contact matrices under GPL-3.0 (prem2017, prem2021) and Apache-2.0 (mistry2021). 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).

Metadata

Release files for starsim-data 2.2.0

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.0
File Size Uploaded Provenance Actions
starsim_data-2.2.0.tar.gz 2.6 MB With provenance Details for starsim_data-2.2.0.tar.gz

Built distribution (wheel)

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

Total release size: 4.9 MB

Release files / starsim_data-2.2.0.tar.gz

Download URL starsim_data-2.2.0.tar.gz
Size 2.6 MB
Tags Source
SHA-256 checksum
How to use checksums
0d32f30cfd4d74e1a20098882151f4075c416cdfec9b54967806f56e14191d89
BLAKE2b-256 checksum
How to use checksums
2e37da4a55c9dd3a9f3cfec03892e5e65f43cbb147568ae8386e9b8005889668
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 Oct 30, 2026.

Transparency log

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

Download URL starsim_data-2.2.0-py3-none-any.whl
Size 2.3 MB
Tags Python 3
SHA-256 checksum
How to use checksums
2fb2f41b144dec6b4ae0033ef0ec9b4a3623229096a5c24398d6c2e8b93cd4c1
BLAKE2b-256 checksum
How to use checksums
a78a3f30f93681131560dcf77f63478ce29e09cc8d2d82adb703c36a8d908a03
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 Oct 30, 2026.

Transparency log

Security for starsim-data 2.2.0

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.0.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 Oct 30, 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