Skip to main content

Provenance and reproducibility

🧠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']
('Kenya', 'deaths')

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.