Skip to main content

Changelog

🧠0% 🤖100%

What’s new in each version of starsim_data. The data is versioned along with the code: any change to the included data is a new version, so a given version always gives the same data.

Version 2.2.2 (2026-11-11)

  • Republishes 2.2.1 through the release workflow, so that PyPI can verify where it was built. There are no other changes.
  • The documentation is rebuilt after each release, so it always shows the latest version.

Version 2.2.1 (2026-11-11)

  • ssd.options.pandas = True (or STARSIM_DATA_PANDAS=1) makes every function return plain pandas DataFrames instead of Sciris dataframes.
  • ssd.load('kenya', which='contacts') is another way to ask for the default contact matrices ('prem').
  • The documentation’s home page is now the README, followed by Getting started.
  • ssd.list_datasets(detailed=True) now gives a short table (name, description, access and location count) that fits in a default pandas display; detailed='full' gives every column, as detailed=True used to.
  • The README lists every function and what it gives you.
  • The build scripts’ --check no longer writes anything: it rebuilds into a temporary folder and fails if the result differs from the committed data, so CI now catches data that has drifted from its sources. build_nodes.py stops if a geospatial dependency is missing, rather than writing a node table with no subnational populations.

Version 2.2.0 (2026-10-30)

  • The function name says where data comes from. ssd.fetch() now gets only the data this package publishes but doesn’t include to save space (prem2017, mistry2021, mistry2021_us and population_us), which is the same for everyone on a version. Data that comes straight from the organization that publishes it has its own function, ssd.download(), e.g. ssd.download('kenya', which='deaths', years=(2000, 2025)) for annual UN data. download_shapes(), download_nodes() and download_raster() do the same for boundaries and WorldPop. These servers are outside this package’s control, so they may be slow or unavailable.
  • Existing code keeps working: fetch() of UN data, and fetch_shapes(), fetch_nodes() and fetch_raster(), still work, with a warning that the data is coming from an external source.
  • ssd.list_datasets(tier=...) now has three tiers to match: 0 for bundled, 1 for fetched and 2 for downloaded.

Version 2.1.0 (2026-10-29)

  • Age-specific fertility rates. ssd.load('nigeria', which='fertility') gives the UN’s fertility rates by 5-year age group of mother, in births per 1,000 women per year, for all 187 countries. This is what ss.Pregnancy needs, just as births (the crude birth rate) is what ss.Births needs. ssd.fetch('nigeria', which='fertility') gives the same for every year, or for another UN projection.
  • ssd.list_datasets(detailed=True) says whether each dataset is bundled (included in the package), fetched (published by this package and downloaded the first time it’s used) or downloaded (from the organization that publishes it).
  • The documentation looks more like Starsim’s, and each page shows how much of it was written by a human and how much by AI.
  • ssd.__version__ now gives the right version.

Version 2.0.0 (2026-10-22)

  • Contact matrices for 187 countries by default. ssd.load('kenya') gives the contact matrices of Prem et al. 2021, and for the ten countries that study left out (such as Japan and Australia), those of Prem et al. 2017. Use which='prem2021' for the 2021 study alone.
  • A smaller package. The other contact matrices, prem2017 and mistry2021, are downloaded the first time you use them, e.g. ssd.fetch('france', which='mistry2021').
  • Subnational populations and borders, offline. ssd.load_nodes('kenya', level=1) gives the population of every state or province (from WorldPop, for 2020), and ssd.adjacency('kenya', level=1) says which of them share a border.
  • Finer levels on request. ssd.fetch_nodes('kenya', level=2) gives the same information for districts, e.g. Kenya’s 290 sub-counties.
  • US states. ssd.fetch('United States:Massachusetts', which='mistry2021_us') gives a state’s contact matrices (Mistry et al. 2021), and which='population_us' its population by single year of age (US Census Bureau, 2023).
  • Downloads are more reliable.
  • Requires Sciris 3.5.2 or later.

Version 1.0.0 (2026-08-08)

Merged with the laser-init project, adding geography for spatial models.

Finding data

  • Countries by any name. 'USA', 'KEN', "CĂ´te d'Ivoire", 'DRC' and official names, abbreviations and translations all work. A name that isn’t recognized gives an error with suggestions, never a guess. ssd.resolve(), ssd.location_info() and ssd.list_all_locations() show how names are matched.
  • Citations travel with the data. ssd.provenance(which) gives each dataset’s source, license and citation, and every dataframe carries the same in df.attrs['provenance'].
  • UN data by revision. load() uses the newest UN WPP revision included; revision= picks another, and ssd.list_revisions() lists them. A new UN release will be added alongside, rather than changing data already in use.

More data

  • fetch(), for UN data that isn’t included: annual rather than every 10 years, full life tables (qx, lx, ex, …) and other projections (High, Low, …), e.g. ssd.fetch('kenya', which='life_table', years=2020). No UN account is needed. Downloads are saved on your computer and reused; ssd.cache_info() and ssd.clear_cache() manage them.
  • ssd.plot(), to check data by eye: ssd.plot('kenya') draws the age pyramid, birth rate, mortality curve and contact matrix.
  • ssd.options, for settings such as where downloads are saved and how much is printed.

Geography

  • The node table. ssd.load_nodes('kenya', level=1) gives every state or province of 184 countries, with its location, area, place in the hierarchy and the pcode that subnational health data uses. It is included in the package, and needs no extra software.
  • ssd.distances(), the distances between them, which together with populations is what a gravity model needs.
  • Boundaries and population grids, with the optional [spatial] packages: ssd.fetch_shapes() for boundaries from UNOCHA, geoBoundaries or GADM (only on request, as it is for non-commercial use only), ssd.fetch_nodes() for populations from WorldPop, and ssd.choropleth() for maps. ssd.rescale_to_national() makes WorldPop’s populations add up to the UN’s national total.
  • A documentation website, covering every dataset, where it comes from, and how this package relates to others.

Version 0.1.0

First release: UN WPP demographics and contact matrices (prem2017, prem2021 and mistry2021), read with load().