# 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()](../api/loaders.md#starsim_data.loaders.provenance) shows it, for fetched datasets too, without downloading anything:

``` python
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()](../api/loaders.md#starsim_data.loaders.load) returns:

``` python
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.'

``` python
deaths.attrs['location'], deaths.attrs['dataset']
```

    ('Kenya', 'deaths')

Provenance for every dataset is available at once:

``` python
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.

``` python
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](https://github.com/starsimhub/starsim_data/blob/main/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](datasources.md#gadm).

## Downloaded data

Data downloaded from its original publisher (with [download()](../api/downloading.md#starsim_data.downloading.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:

``` python
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()](../api/fetching.md#starsim_data.fetching.fetch) and [download()](../api/downloading.md#starsim_data.downloading.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()](../api/loaders.md#starsim_data.loaders.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](building-the-data.md).

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

``` 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](https://github.com/starsimhub/starsim_data/blob/main/NOTICE.md) gives the complete text for each source.
