# 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](datasources.md); this page is about the packages that sit between those sources and a model.

## The two this package builds on

### epydemix-data

[epydemix-data](https://github.com/epistorm/epydemix-data) is the data behind [epydemix](https://github.com/epistorm/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](https://github.com/starsimhub/starsim_data/blob/main/NOTICE.md) for details.

### laser-init

[laser-init](https://github.com/laser-base/laser-init) sets up a spatial model for [LASER](https://github.com/laser-base/laser-generic). 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](datasources.md) 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()](../api/loaders.md#starsim_data.loaders.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()](../api/nodes.md#starsim_data.nodes.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`](https://github.com/socialcontactdata/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`](https://github.com/epiforecasts/socialmixr) | R (CRAN) | Contact matrices computed directly from contact surveys (POLYMOD and the wider [socialcontactdata.org](http://socialcontactdata.org) collection), rather than estimated for countries without a survey. Covers a few dozen surveys rather than every country. |
| [`mobs-lab/mixing-patterns`](https://github.com/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`](https://github.com/synthpops/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`](https://github.com/PPgp/wpp2024) and [`wpp2024extra`](https://github.com/PPgp/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()](../api/downloading.md#starsim_data.downloading.download) covers part of the same ground. |
| [UN WPP Data Portal](https://population.un.org/dataportal/) | API | The official source; needs a free access token. [download()](../api/downloading.md#starsim_data.downloading.download) uses the UN's public files instead, so you don't need one. |
| National statistical offices, [DHS](https://dhsprogram.com), [IPUMS](https://international.ipums.org) | 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](https://github.com/wmgeolab/geoBoundaries) | Data + API | Open administrative boundaries for nearly every country. Used directly by [download_shapes()](../api/shapes.md#starsim_data.shapes.download_shapes). |
| [HDX](https://data.humdata.org) and [`hdx-python-api`](https://pypi.org/project/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`](https://pypi.org/project/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](https://hub.worldpop.org) and [`rasterstats`](https://pypi.org/project/rasterstats/) | Data + Python | Population grids, and a tool for adding them up within boundaries. [download_nodes()](../api/rasters.md#starsim_data.rasters.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](datasources.md) lists what is missing.
- **Record what you used.** Whichever you choose, note the version and where the data came from; see [Provenance and reproducibility](provenance.md).
