data

data

Data by place: ages, populations, birth and death rates, contact matrices, and administrative units

ss.data.age('Kenya')                    # The age_data of ss.People: counts by 5-year age group ('world' needs no download)
ss.data.population('Kenya', year=2020)  # By age and sex (also for a US state, e.g. 'United States:Massachusetts')
ss.data.rates('Kenya', 'deaths')        # Birth, death, fertility, or net migration rates, by year
ss.data.contacts('Kenya', layer='home') # A contact matrix by age
ss.data.geography('Kenya', level=1)     # Administrative units, with populations and positions

These are tables. The model objects that take a place by name read them from here: ss.population('Kenya'), ss.geo.geography('Kenya', level=1), ss.contacts('Kenya'), ss.Births(birth_rate='Kenya'), ss.Deaths(death_rate='Kenya'), and ss.Pregnancy(fertility_rate='Kenya'). The data comes from starsim_data (https://github.com/starsimhub/starsim_data), which bundles what is small and common and fetches the rest on demand. Each lookup returns the data with a record of where it came from (ref; for a table, in .attrs['ref']), which sim.describe() shows.

Used with: agents and compartments; declared and coded modules

Functions

Name	Description
age	The ages of a place’s people, as the age_data of ss.People: counts by 5-year age group
age_edges	The lower edge of each age group from its label (‘0-4’, ‘75+’, or ‘3’), as floats: the inverse of age_labels()
age_labels	The label of each age group from its lower edge, as a stratification by age labels them, e.g. ‘0-4’, ‘5-9’, and ‘75+’ (a single year is ‘3’)
age_split	The fraction of people in each age group, from counts by 5-year age group, with ages uniform within each
contacts	A contact matrix by age for a named place, for ss.contacts('Kenya')
geography	The administrative units of a place, for ss.geo.geography('Kenya', level=1)
population	The population of a named place by age and sex, for ss.population('Kenya', year=2024)
rates	The UN World Population Prospects birth, death, fertility, or net migration rates of a named place, for ss.Births(birth_rate='Kenya'), ss.Deaths(death_rate='Kenya'), and ss.Pregnancy(fertility_rate='Kenya')
starsim_data	The starsim_data package, which has the data by place, imported when it is first used

age

data.age(place='world', year=None)

The ages of a place’s people, as the age_data of ss.People: counts by 5-year age group

Parameters

Name	Type	Description	Default
place	str	a country, by name or code, or ‘world’ (the world’s population in 2024, which needs no download)	'world'
year	int	the year (default: the year of the data); not for ‘world’	None

Examples

ppl = ss.People(10_000, age_data=ss.data.age('Kenya', year=2020))

age_edges

data.age_edges(labels)

The lower edge of each age group from its label (‘0-4’, ‘75+’, or ‘3’), as floats: the inverse of age_labels()

age_labels

data.age_labels(edges)

The label of each age group from its lower edge, as a stratification by age labels them, e.g. ‘0-4’, ‘5-9’, and ‘75+’ (a single year is ‘3’)

age_split

data.age_split(edges, ages, counts)

The fraction of people in each age group, from counts by 5-year age group, with ages uniform within each

Parameters

Name	Type	Description	Default
edges	array	the lower edge of each age group; the last is open-ended	required
ages	array	the lower edge of each 5-year group of the counts	required
counts	array	the number of people in each	required

contacts

data.contacts(place, study=None, layer='all')

A contact matrix by age for a named place, for ss.contacts('Kenya')

The studies (all but the first are downloaded on first use):

• ‘prem2021’: Prem et al. 2021, bundled; 177 places
• ‘prem’: Prem 2021, with Prem 2017 for the places it lacks; 187 places
• ‘prem2017’: Prem et al. 2017; 152 places
• ‘mistry2021’: Mistry et al. 2021, by single year of age; 36 places
• ‘mistry2021_us’: Mistry et al. 2021 for the 50 US states and DC, by single year of age

Parameters

Name	Type	Description	Default
place	str	a country, by name or code; or a US state, e.g. ‘United States:Massachusetts’	required
study	str	the study the matrix is from (see above); by default, for a country, Prem 2021 where it has the country (bundled, so no download), else Prem 2017 (e.g. for Japan and Australia); for a US state, ‘mistry2021_us’	None
layer	str	the setting: ‘all’, ‘home’, ‘school’, ‘work’, or ‘community’, e.g. ‘school’ to model school closures	'all'

Returns

Name	Type	Description
		A dataframe of the contacts a day that a person in each age group (a row) has with people in each (a column), with the groups labeled ‘0-4’, ‘5-9’, …, ‘75+’ (or by single year of age), and where it came from in .attrs['ref']; ss.contacts() takes it

Examples

school = ss.data.contacts('Kenya', layer='school')
school.loc['10-14', '10-14'] # Contacts a day of a child aged 10-14 at school with children aged 10-14
mixing = ss.contacts(school) # The same as ss.contacts('Kenya', layer='school')

geography

data.geography(place, level=1, year=None, places=None)

The administrative units of a place, for ss.geo.geography('Kenya', level=1)

Parameters

Name	Type	Description	Default
place	str / list	a country, by name or code (‘Kenya’, ‘KE’, ‘KEN’), or several	required
level	int / str	the administrative level: 0 for each country, 1 for its first-level units (counties, provinces, states), 2 for the next	1
year	int	the year of the populations (default: those bundled, without a download)	None
places	list	only these units, by name, dot_name (‘Kenya:Nairobi’), or p-code	None

Returns

Name	Type	Description
		A dict of names, pop, lat, lon, area (km²), codes (p-codes), adjacency (or None), and ref

population

data.population(place, year=None, revision=None)

The population of a named place by age and sex, for ss.population('Kenya', year=2024)

For a country, the UN World Population Prospects give it every ten years (1950 to 2100); a year in between is interpolated linearly, group by group. For a US state, the US Census gives it for 2023 only, by single year of age to 84+, and not by sex: it is grouped by 5 years (the last group, 80+, is taken to end at 85, as ss.People reads it), and split evenly between women and men.

Parameters

Name	Type	Description	Default
place	str	a country, by name or code; or a US state, e.g. ‘United States:Massachusetts’ (downloaded on first use)	required
year	int	the year (default: the year of the WPP revision, e.g. 2024); a US state has only 2023, which is used with a note for any other	None
revision	str	the WPP revision (default: the latest bundled); not for a US state	None

Returns

Name	Type	Description
		A dataframe of the number of women and of men (columns female and male) in each 5-year age group (the index, labeled ‘0-4’, ‘5-9’, …, ‘100+’, or ‘80+’ for a US state), with where it came from in .attrs['ref']

Examples

pop = ss.data.population('Kenya', year=2024)
pop.loc['0-4'].sum() # Children under 5
pop.attrs['ref']['study'] # The source

rates

data.rates(place, which, revision=None)

The UN World Population Prospects birth, death, fertility, or net migration rates of a named place, for ss.Births(birth_rate='Kenya'), ss.Deaths(death_rate='Kenya'), and ss.Pregnancy(fertility_rate='Kenya')

The rates are:

• ‘births’: crude birth rates per 1,000 people, by year
• ‘deaths’: death rates per person, by year, sex, and age
• ‘fertility’: age-specific fertility rates per 1,000 women, by year and 5-year age group
• ‘migration’: crude net migration rates per 1,000 people, by year (arrivals less departures)

Parameters

Name	Type	Description	Default
place	str	a country, by name or code	required
which	str	‘births’, ‘deaths’, ‘fertility’, or ‘migration’ (see above)	required
revision	str	the WPP revision (default: the latest bundled)	None

starsim_data

data.starsim_data()

The starsim_data package, which has the data by place, imported when it is first used