🧠5% 🤖95%
The data in this package comes from other organizations, under several different licenses, and the numbers a model produces depend on which version of which source it used. This page shows how to find out where a dataset came from, how to cite it, and how to make an analysis reproducible.
Attribution travels with the data
Every dataset records its source, URL, license and citation, along with when and by which package version it was built. provenance() shows it, for fetched datasets too, without downloading anything:
import starsim_data as ssd
ssd.provenance('prem2021')
sc.objdict(
dataset = 'prem2021',
n_locations = 177,
source = 'Prem et al. 2021',
source_url = 'https://github.com/kieshaprem/synthetic-contact-matrices',
via = 'https://github.com/epistorm/epydemix-data',
license = 'GPL-3.0',
citation = 'Prem K, Zandvoort K van, Klepac P, et al. Projecting contact matrices in 177 geographical regions: An update and comparison with empirical data for the COVID-19 era. PLoS Comput Biol 17(7): e1009098 (2021).',
note = '16x16 matrices; 5-year age groups (0-4, 5-9, ..., 75+).',
built = '2026-08-07T17:19:19+00:00',
builder = 'scripts/build_hdf5.py',
package_version = '0.1.0',
git = {'branch': 'laser-init-merge', 'hash': '5aea7cb', 'date': '2026-08-07T12:16:58-04:00'},
)
The same record is attached to every dataframe load() returns:
deaths = ssd.load('kenya', which='deaths')
deaths.attrs['provenance'].citation
'United Nations, Department of Economic and Social Affairs, Population Division (2024). World Population Prospects 2024.'
deaths.attrs['location'], deaths.attrs['dataset']
Provenance for every dataset is available at once:
sorted(ssd.provenance().keys())
['adjacency',
'births',
'deaths',
'fertility',
'migration',
'nodes',
'population',
'prem',
'prem2021']
Licenses
The data is not covered by this package’s MIT license; each dataset keeps its original license.
ssd.list_datasets(detailed='full')[['dataset', 'access', 'license']]
|
dataset |
access |
license |
| 0 |
adjacency |
bundled |
unocha: CC BY 3.0 IGO; geoboundaries: CC BY 4.0 |
| 1 |
births |
bundled |
CC BY 3.0 IGO |
| 2 |
deaths |
bundled |
CC BY 3.0 IGO |
| 3 |
fertility |
bundled |
CC BY 3.0 IGO |
| 4 |
indicators |
downloaded |
CC BY 3.0 IGO |
| 5 |
life_table |
downloaded |
CC BY 3.0 IGO |
| 6 |
migration |
bundled |
CC BY 3.0 IGO |
| 7 |
mistry2021 |
fetched |
Apache-2.0 |
| 8 |
mistry2021_us |
fetched |
Apache-2.0 |
| 9 |
nodes |
bundled |
unocha: CC BY 3.0 IGO; geoboundaries: CC BY 4.... |
| 10 |
population |
bundled |
CC BY 3.0 IGO |
| 11 |
population_us |
fetched |
Public domain |
| 12 |
prem |
bundled |
GPL-3.0 |
| 13 |
prem2017 |
fetched |
GPL-3.0 |
| 14 |
prem2021 |
bundled |
GPL-3.0 |
NOTICE.md has the full attribution text, and the licenses/ folder in the repository has the original license texts.
GADM boundaries are licensed for non-commercial use only. This package never uses GADM unless you ask for it by name, and never redistributes anything derived from it; if you download it, following its terms is up to you. See Data sources.
Downloaded data
Data downloaded from its original publisher (with download() and the download_*() functions) is saved on your computer, along with a note of where and when it was downloaded. ssd.cache_info() lists everything saved so far:
ssd.cache_info()
# file size url downloaded
# wpp/WPP2024_Demographic_Indicators_Medium.csv.gz 16.557 MB https://population.un.org/... 2026-08-07T19:31:36+00:00
Dataframes returned by fetch() and download() carry the same information in df.attrs['provenance'].
Making an analysis reproducible
Four steps, most important first.
Pin the package version. Everything bundled or fetched is the same for everyone using a given version of the package, so pinning the version (for example starsim_data==2.2.0 in your requirements file) fixes the demographics, the contact matrices and the node table together.
Pin the WPP revision. load(..., revision=2024) fixes the UN WPP release. Without it, load() uses the most recent revision in the package, so a future version could change what your script reads. Older revisions are kept when new ones are added, so a pinned revision stays available.
Record what was downloaded. Data downloaded from its original publisher depends on when you downloaded it, since publishers revise their files. Saving the output of ssd.cache_info() with your results records what you used and when.
Record the boundary source. Different boundary sources don’t always divide a country up the same way, so two analyses that used different sources aren’t directly comparable. The source is in nodes.source and in the provenance of any downloaded boundaries.
If you’re curious how the bundled data is built from its sources, and how that is checked, see Building the data.
Citation
Cite the original sources, not just this package: UN World Population Prospects 2024 for the demographics, the relevant paper for each contact-matrix source you use, and UNOCHA and geoBoundaries for the node table. The citations are available in Python:
{name: ssd.provenance(name).citation[:80] + '...'
for name in ['deaths', 'prem2021', 'mistry2021']}
{'deaths': 'United Nations, Department of Economic and Social Affairs, Population Division (...',
'prem2021': 'Prem K, Zandvoort K van, Klepac P, et al. Projecting contact matrices in 177 geo...',
'mistry2021': 'Mistry D, Litvinova M, Pastore y Piontti A, et al. Inferring high-resolution hum...'}
NOTICE.md gives the complete text for each source.