Skip to main content

Related projects

🧠0% 🤖100%

Almost all the data in this package is public, and other projects package it for modelers too. What differs between them is mostly how you get it: whether the data comes with the package or from a server, whether you get a dataframe or a folder of files, and how much of the model is set up for you.

Two projects in particular shaped this one. For the original data sources themselves (coverage, updates, licenses and limitations), see Data sources; this page is about the packages that sit between those sources and a model.

The two this package builds on

epydemix-data

epydemix-data is the data behind epydemix, the ISI Foundation’s Python package for stochastic compartmental modeling and calibration. It has age distributions and contact matrices for more than 3,500 regions, as folders of CSV files on GitHub.

What this package took from it. The contact matrices here (prem2017, prem2021, mistry2021 and mistry2021_us, plus the US state populations) come from epydemix-data’s carefully cleaned-up files, keeping the national and US-state ones. Assembling them from the papers’ original spreadsheets is tedious work, and epydemix-data had already done it well. This package also borrowed the idea of a single list of locations and the data available for each, and of tying each package version to an exact version of the data.

Where the two differ. epydemix-data reads its files from GitHub by default, unless you have downloaded a local copy. ssd.load() works offline, because the data comes with the package. Each choice has its advantages: a collection of files on GitHub can hold 3,500 regions and four contact sources, which a package can’t, while bundled data is instant, works offline and is the same for everyone using the same version.

The scope differs in both directions:

  • epydemix-data has more contact data: state and province matrices for other countries, all 3,144 US counties, a fourth source (litvinova_2025), and US matrices by sex and by race/ethnicity. This package has national and US-state matrices only.
  • This package has more demographic data. epydemix-data has one age distribution per location, which is what a compartmental model needs to get started. Here there are five UN WPP series from 1950 to 2100 (births, deaths by age and sex, migration, population, and fertility by age), because an agent-based model with births and deaths needs rates over time, not just a starting age structure.
  • This package adds geography. epydemix-data has no boundaries, node table or population grids.

The licenses differ too. epydemix-data is GPL-3.0 as a whole. Here the code is MIT and each dataset keeps its original license (ssd.provenance(which).license): the Prem matrices are GPL-3.0, mistry2021 is Apache-2.0, and the WPP data is CC BY 3.0 IGO. See NOTICE.md for details.

laser-init

laser-init sets up a spatial model for LASER. It is a command-line tool rather than a library: laser-init NGA 2 2000 2025 downloads boundaries, WorldPop population and UN WPP data for Nigeria at admin level 2, works out the population of each unit, and writes a folder with the boundaries, demographic CSVs, a config file, plots, a PDF report, a record of where the data came from, and a runnable SEIR model script.

What this package took from it. The spatial data here follows laser-init’s approach: the three boundary sources and when to prefer each, trying UNOCHA then geoBoundaries with GADM only on request, and adding up WorldPop’s population grid within each unit. Much of the boundary and population material in Data sources is adapted from laser-init’s documentation. Keeping a record of where each piece of data came from was also its idea.

Where the two differ. laser-init sets up a working model; this package returns dataframes and stops there. laser-init also downloads everything on its first run, which with its default boundary source is 1–2 GB. Here the node table (centroids, areas, populations, p-codes and borders for 184 countries at levels 0 and 1) is bundled, which covers most of what a metapopulation model needs with no download and no extra libraries. Boundary shapes, finer levels and population grids are still downloaded when you need them. laser-init’s demographics are birth and death rates and a survival curve for one country and period, whereas load() returns the full WPP series for every country. Both are MIT-licensed.

The three side by side

starsim_data epydemix-data laser-init
Form Python library Git-hosted CSV tree + loader in epydemix Command-line tool
You get Dataframes A Population object A directory of files and a model script
Internet needed No, for bundled data Yes, unless downloaded first Yes
Demographics Five UN WPP series, 1950–2100 One age distribution per location Birth and death rates, age distribution, survival curve
Contact matrices 3 sources, national and US state 4 sources, national to US county None
Geography Node table bundled; boundaries and population grids downloaded None Boundaries and population grids downloaded
Locations 187 countries, 51 US states 3,500+ regions Any one country per run
Generates a model No No Yes
License MIT code, per-dataset data licenses GPL-3.0 MIT

Each is best for something different. For a compartmental model of a US county, or of another country’s provinces, epydemix-data has contact data this package doesn’t. For a spatial LASER model of Nigeria running as soon as possible, laser-init will get you there faster than building one from load_nodes(). This package is aimed at Starsim models that need national demographic rates and contact matrices, offline and reproducibly, with subnational geography when you want it.

Other places these data come from

Other projects that package data for epidemic modeling:

Contact matrices

Project Language What it provides
contactdata R (CRAN) The Prem 2017 and 2021 matrices for 177 countries. The closest R equivalent to this package’s contact matrices, and a good choice if matrices are all you need.
socialmixr R (CRAN) Contact matrices computed directly from contact surveys (POLYMOD and the wider socialcontactdata.org collection), rather than estimated for countries without a survey. Covers a few dozen surveys rather than every country.
mobs-lab/mixing-patterns Data repository The original Mistry 2021 matrices and the synthetic populations they came from. The source of both mistry2021 here and epydemix-data’s copy.
synthpops Python Builds synthetic populations with household, school and workplace networks, rather than providing matrices. A contact matrix summarizes who mixes with whom; a synthetic population spells it out person by person.

The main difference in this group is estimated versus measured. Prem 2017 and 2021 estimate contact patterns for countries without their own survey, from household composition and age structure; socialmixr computes matrices only where a survey exists. The estimates cover almost every country and are what most models use; measured matrices are better where a survey exists and the choice of matrix matters for your results.

Demographics

Project Language What it provides
wpp2024 and wpp2024extra R (GitHub) The UN WPP 2024 release as R data packages, including annual data by single year of age and projection uncertainty ranges. The most complete packaging of WPP in any language; this package’s download() covers part of the same ground.
UN WPP Data Portal API The official source; needs a free access token. download() uses the UN’s public files instead, so you don’t need one.
National statistical offices, DHS, IPUMS Various Subnational demographics, which WPP doesn’t have. If your model needs province-level fertility or mortality, look here.

Geography and population

Project Language What it provides
geoBoundaries Data + API Open administrative boundaries for nearly every country. Used directly by download_shapes().
HDX and hdx-python-api Python The Humanitarian Data Exchange, home of the UNOCHA boundaries and most subnational health data labeled with p-codes. The node table has p-codes so you can join it to data from here.
pygadm Python GADM boundaries, which go down to the finest administrative levels. Note the non-commercial license, which is why this package downloads GADM only on request and never redistributes it.
WorldPop and rasterstats Data + Python Population grids, and a tool for adding them up within boundaries. download_nodes() does this for you; rasterstats is the general tool if you need something else.

Choosing between them

Most of these projects use the same underlying data, so a few rules of thumb:

  • Use whichever is closest to your modeling framework. They mostly draw on the same few sources, so the difference is convenience rather than accuracy: pick the one that gives you data in the form your model wants.
  • Don’t mix packages for the same data in one analysis. Two packages may both offer “the Prem 2021 matrix for Kenya” but differ in age-group labels, scaling or which release they use. Pick one and note which.
  • Check what has been left out. Every package here includes only part of its sources. This one leaves out subnational contact matrices, for example, and bundles only the Medium WPP projection; Data sources lists what is missing.
  • Record what you used. Whichever you choose, note the version and where the data came from; see Provenance and reproducibility.