---
name: starsim_data
description: >-
  Demographic data and contact matrices for disease modeling with Starsim. Use
  when writing Python code that uses the starsim_data package.
license: MIT AND GPL-3.0-only AND CC-BY-3.0-IGO AND CC-BY-4.0
compatibility: Requires Python >=3.11.
---

# Starsim Data

Demographic data and contact matrices for disease modeling with Starsim

## Installation

```bash
pip install starsim_data
```

## API overview

### Dataclasses

Data-holding classes

- `registry.Dataset`
- `registry.Source`

### Functions

Public functions

- `load`: Load data for a location
- `fetch`: Fetch a store this package publishes but does not bundle, caching it for next time
- `download`: Download UN WPP data that is not packaged, caching it for next time
- `plot`: Plot data for a location, as a quick check before it goes into a model
- `choropleth`: Draw a filled map of an administrative value -- the geometry version of `plot(which='nodes')`
- `provenance`: Return where a dataset came from: source, license, citation and build details
- `registry.datasets`
- `registry.dataset`
- `registry.unregister_dataset`
- `registry.get_layout`
- `registry.data_dir`
- `registry.refresh`
- `load_nodes`: Load the node table for a location: centroids, areas, p-codes and hierarchy
- `distances`: Great-circle distances between node centroids -- the input a gravity model needs
- `adjacency`: Which administrative units share a border: a square boolean matrix
- `node_name`: Render an administrative unit's name in this package's canonical style
- `download_shapes`: Download administrative boundaries with full geometry from their publisher, and cache them
- `list_shape_sources`: Return the boundary sources as a dataframe: coverage, levels and license
- `download_nodes`: The node table with `population` filled in, from WorldPop, at any level and year
- `download_raster`: Download a WorldPop 1 km gridded-population raster for a country, and cache it
- `aggregate_raster`: Sum a raster inside each polygon: zonal statistics, keyed by an attribute
- `rescale_to_national`: Scale node populations so they sum to this package's national WPP total
- `list_datasets`: Return the available datasets: contact sources plus WPP demographic series
- `list_locations`: Return the sorted locations available in dataset `which`
- `list_revisions`: Return the bundled UN WPP revisions, oldest first; the last is the default
- `list_fetchable`: Return the datasets `fetch()` can retrieve: the stores published with this package
- `list_downloadable`: Return the datasets `download()` can retrieve
- `resolve`: Resolve a location string to its canonical key
- `location_info`: Return the metadata row for a location, as a `sciris.objdict`
- `list_all_locations`: Return every canonical location name known to the package, sorted
- `parse_level`: Parse an administrative level into an integer
- `register_dataset`: Add a dataset to the registry
- `register_layout`: Register a function that turns a stored array into a dataframe
- `cache_dir`: Return the directory where downloaded data is cached
- `cache_info`: Return a dataframe of what is currently cached: file, size, source URL and date
- `cache_provenance`: Return the recorded provenance for a cached file, or None if there is none
- `cached_download`: Download `url` into the cache, or return the existing path if already cached
- `clear_cache`: Delete cached downloads. Bundled data is never touched

### Constants

Module-level constants and data

- `options`: Settings for `starsim_data`; the instance to use is `starsim_data.options`

## Resources

- [Full documentation](https://starsimhub.github.io/starsim_data/)
- [llms.txt](llms.txt) — Indexed API reference for LLMs
- [llms-full.txt](llms-full.txt) — Comprehensive documentation for LLMs
- [Source code](https://github.com/starsimhub/starsim_data)
