synthpops.sampling module¶

Sample distributions, either from real world data or from uniform distributions

synthpops.sampling.set_seed(seed=None)¶: Reset the random seed – complicated because of Numba

synthpops.sampling.sample_single_dict(distr_keys, distr_vals)¶

Sample from a distribution.

Parameters: distr (dict or np.ndarray) – distribution
Returns: A single sampled value from a distribution.

synthpops.sampling.sample_single_arr(distr)¶

Sample from a distribution.

Parameters: distr (dict or np.ndarray) – distribution
Returns: A single sampled value from a distribution.

synthpops.sampling.resample_age(age_dist_vals, age)¶

Resample age from single year age distribution.

Parameters

single_year_age_distr (arr) – age distribution, ordered by age
age (int) – age as an integer

Returns

Resampled age as an integer.

synthpops.sampling.sample_from_range(distr, min_val, max_val)¶

Sample from a distribution from min_val to max_val, inclusive.

Parameters

distr (dict) – distribution with integer keys
min_val (int) – minimum of the range to sample from
max_val (int) – maximum of the range to sample from

Returns

A sampled number from the range min_val to max_val in the distribution distr.

synthpops.sampling.sample_bracket(distr, brackets)¶

Sample bracket from a distribution (potentially absolete).

Parameters: distr (dict or np.ndarray) – distribution for bracket keys
Returns: A sampled bracket from a distribution.

synthpops.sampling.sample_n(nk, distr)¶

Sample nk values from a distribution

Parameters

nk (int) – number of samples
distr (dict or np.ndarray) – distribution

Returns

A dictionary with the count for n samples from a distribution

synthpops.sampling.sample_contact_age(age, age_brackets, age_by_brackets_dic, age_mixing_matrix, single_year_age_distr=None)¶

Sample the age of a contact from age mixing patterns. Age of contact is uniformly drawn from the age bracket sampled from the age mixing matrix, unless single_year_age_distr is available.

Parameters

age (int) – age of reference individual
age_brackets (dict) – dictionary mapping age bracket keys to age bracket range
age_mixing_matrix (matrix) – age specific contact matrix
single_year_age_distr (dict) – age distribution by single year ages if available

Returns

Age of contact by age of individual sampled from an age mixing matrix.

synthpops.sampling.sample_n_contact_ages(n_contacts, age, age_brackets, age_by_brackets_dic, age_mixing_matrix_dic, weights_dic, single_year_age_distr=None)¶

Sample the age of n_contacts contacts from age mixing patterns. Age of each contact is uniformly drawn from the age bracket sampled from the age mixing matrix, unless single_year_age_distr is available. Combines setting specific weights to create an age mixing matrix from which contact ages are sampled.

Parameters

n_contacts (int) – number of contacts to draw ages for
age (int) – age of reference individual
age_brackets (dict) – dictionary mapping age bracket keys to age bracket range
age_by_brackets_dic (dict) – dictionary mapping age to the age bracket range it falls in
age_mixing_matrix_dic (dict) – dictionary of age specific contact matrix for different physical contact settings
weights_dic (dict) – weights to combine contact matrices
single_year_age_distr (dict) – age distribution by single year ages if available

Returns

List of ages of n_contacts contacts by age of individual sampled from a combined age mixing matrix.

synthpops.sampling.sample_n_contact_ages_with_matrix(n_contacts, age, age_brackets, age_by_brackets_dic, age_mixing_matrix, single_year_age_distr=None)¶

Sample the age of n_contacts contacts from age mixing matrix. Age of each contact is uniformly drawn from the age bracket sampled from the age mixing matrix, unless single_year_age_distr is available.

Parameters

n_contacts (int) – number of contacts to draw ages for
age (int) – age of reference individual
age_brackets (dict) – dictionary mapping age bracket keys to age bracket range
age_by_brackets_dic (dict) – dictionary mapping age to the age bracket range it falls in
age_mixing_matrix (matrix) – age specific contact matrix
weights_dic (dict) – weights to combine contact matrices
single_year_age_distr (dict) – age distribution by single year ages if available

Returns

List of ages of n_contacts contacts by age of individual sampled from an age mixing matrix.

synthpops.sampling.get_n_contact_ids_by_age(contact_ids_by_age_dic, contact_ages, age_brackets, age_by_brackets_dic)¶

Get ids for the contacts with ages in contact_ages.

Parameters

contact_ids_by_age_dic (dict) – dictionary mapping lists of ids to the age of individuals with those ids
contact_ages (list) – list of integer ages
age_brackets (dict) – dictionary mapping age bracket keys to age bracket range
age_by_brackets_dic (dict) – dictionary mapping age to the age bracket range it falls in

Return set of ids of n_contacts sampled from an age mixing matrix, where potential contacts are chosen from a list of contact ids by age

synthpops.sampling.pt(rate)¶

Results of a Poisson trial

Parameters: rate (float) – Poisson rate

Returns result (bool) of Poisson trial.

synthpops.sampling.get_age_sex(gender_fraction_by_age, age_bracket_distr, age_brackets, min_age=0, max_age=100, age_mean=40, age_std=20)¶

Sample a person’s age and sex based on gender and age census data defined for age brackets. Else, return random age and sex.

Parameters

gender_fraction_by_age (dict) – dictionary of the fractions for two genders by age bracket
age_bracket_distr (dict) – : distribution of ages by brackets
age_brackets (dict) – dictionary mapping age bracket keys to age bracket range
min_age (int) – minimum age to draw
max_age (int) – maximum age to draw
age_mean (int) – mean of age distribution
age_std (int) – standard deviation of age distribution

Returns

Sampled age (float), sex (int; 0 for female, 1 for male)

synthpops.sampling.get_age_sex_n(gender_fraction_by_age, age_bracket_distr, age_brackets, n_people=1, min_age=0, max_age=100)¶

Sample n_people peoples’ age and sex from gender and age census data defined for age brackets. Else, return random ages and sex. Two lists ordered by age bracket so that people from the first age bracket show up at the front of both lists and people from the last age bracket show up at the end.

Parameters

gender_fraction_by_age (dict) – dictionary of the fractions for two genders by age bracket
age_bracket_distr (dict) – : distribution of ages by brackets
age_brackets (dict) – dictionary mapping age bracket keys to age bracket range
n_people (int) – number of people to draw age and sex for
min_age (int) – minimum age to draw
max_age (int) – maximum age to draw
age_mean (int) – mean of age distribution
age_std (int) – standard deviation of age distribution

Returns

Two lists of sampled ages (float) and sexes (int; 0 for female, 1 for male) ordered by age bracket so that people from the first age bracket show up at the front of both lists and people from the last age bracket show up at the end.

synthpops.sampling.get_seattle_age_sex(datadir, location='seattle_metro', state_location='Washington', country_location='usa')¶

Sample a person’s age and sex based on US gender and age census data defined for age brackets, with defaults set to Seattle, Washington.

Parameters

datadir (string) – file path to the data directory
location (string) – name of the location
state_location (string) – name of the state the location is in
country_location (string) – name of the country the location is in

Returns

Sampled age (float), sex (int; 0 for female, 1 for male)

synthpops.sampling.get_seattle_age_sex_n(datadir, location='seattle_metro', state_location='Washington', country_location='usa', n_people=10000.0)¶

Sample n_people peoples’ age and sex based on US gender and age census data defined for age brackets, with defaults set to Seattle, Washington.

Parameters

datadir (string) – file path to the data directory
location (string) – name of the location
state_location (string) – name of the state the location is in
country_location (string) – name of the country the location is in
n_people (float or int) – number of people to draw age and sex for

Returns

Two lists of sampled ages (float) and sexes (int; 0 for female, 1 for male) ordered by age bracket so that people from the first age bracket show up at the front of both lists and people from the last age bracket show up at the end.

synthpops.sampling.get_usa_age_sex(datadir, location='seattle_metro', state_location='Washington', country_location='usa')¶

Sample a person’s age and sex based on US gender and age census data defined for age brackets, with defaults set to Seattle, Washington.

Parameters

datadir (string) – file path to the data directory
location (string) – name of the location
state_location (string) – name of the state the location is in
country_location (string) – name of the country the location is in

Returns

Sampled age (float), sex (int; 0 for female, 1 for male)

synthpops.sampling.get_usa_age_sex_n(datadir, location='seattle_metro', state_location='Washington', country_location='usa', n_people=10000.0)¶

Sample n_people peoples’ age and sex based on US gender and age census data defined for age brackets, with defaults set to Seattle, Washington.

Parameters

datadir (string) – file path to the data directory
location (string) – name of the location
state_location (string) – name of the state the location is in
country_location (string) – name of the country the location is in
n_people (float or int) – number of people to draw age and sex for

Returns

Two lists of sampled ages (float) and sexes (int; 0 for female, 1 for male) ordered by age bracket so that people from the first age bracket show up at the front of both lists and people from the last age bracket show up at the end.

synthpops.sampling.get_usa_age_n(datadir, sexes, location='seattle_metro', state_location='Washington', country_location='usa')¶

Sample n_people peoples’ age based on list of sexes supplied and US gender and age census data defined for age brackets, with defaults set to Seattle, Washington.

Parameters

datadir (string) – file path to the data directory
sexes (list) – list of sexes
location (string) – name of the location
state_location (string) – name of the state the location is in
country_location (string) – name of the country the location is in
n_people (float or int) – number of people to draw age and sex for

Returns

Two lists of sampled ages (float) and sexes (int; 0 for female, 1 for male) ordered by age bracket so that people from the first age bracket show up at the front of both lists and people from the last age bracket show up at the end.

synthpops.sampling.get_usa_sex_n(datadir, ages, location='seattle_metro', state_location='Washington', country_location='usa')¶

Sample n_people peoples’ sex based on list of ages supplied and US gender and age census data defined for age brackets, with defaults set to Seattle, Washington.

Parameters

datadir (string) – file path to the data directory
ages (list) – list of ages
location (string) – name of the location
state_location (string) – name of the state the location is in
country_location (string) – name of the country the location is in
n_people (float or int) – number of people to draw age and sex for

Returns

Two lists of sampled ages (float) and sexes (int; 0 for female, 1 for male) ordered by age bracket so that people from the first age bracket show up at the front of both lists and people from the last age bracket show up at the end.

synthpops.sampling.get_age_n(datadir, n, location='seattle_metro', state_location='Washington', country_location='usa', age_brackets_file=None, age_bracket_distr_file=None, age_brackets=None, age_bracket_distr=None)¶

Sample n_people peoples’ age based on age census data defined for age brackets, with defaults set to Seattle, Washington.

Parameters

datadir (string) – file path to the data directory
n (float or int) – number of people to draw age and sex for
location (string) – name of the location
state_location (string) – name of the state the location is in
country_location (string) – name of the country the location is in
age_brackets_file (string) – user file path to get age brackets from
age_bracket_distr_file (string) – user file path to get age distribution by brackets from
age_brackets (dict) – dictionary mapping age bracket keys to age bracket range
age_bracket_distr (dict) – : distribution of ages by brackets

Returns

List of sampled ages (float) ordered by age bracket so that people from the first age bracket show up at the front of the list and people from the last age bracket show up at the end.

synthpops.sampling.get_mortality_rates_filepath(path)¶

Get file path to mortality rates.

Parameters: path (string) – path to folder containing mortality rates by age brackets data.
Returns: The filepath to mortality rates by age bracket.

synthpops.sampling.get_mortality_rates_by_age_bracket(file_path)¶

Get mortality rates by age bracket

Parameters: file_path (string) – path to mortality rates by age bracket data.
Returns: A dictionary of mortality rates by age bracket.

synthpops.sampling.get_mortality_rates_by_age(mortality_rate_by_age_bracket, mortality_age_brackets)¶

Get mortality rates by age

Parameters

mortality_rate_by_age_bracket (dict) – dictionary of mortality rates by age bracket
mortality_age_brackets (dict) – dictionary of age brackets for raw mortality rate data

Returns

A dictionary of mortality rates by age.

synthpops.sampling.calc_death(person_age, mortality_rates)¶

Binomial draw of whether or not an individual succumbs to disease.

Parameters

person_age (int) – age of the ill individual.
mortality_rates (dict) – dictionary of mortality rates by age

Returns

Bool representing the results of a binomial test; 1 for death, 0 for staying alive.