synthpops.households module

Functions for generating households

class Household(hhid=None, reference_uid=None, reference_age=None, **kwargs)

Bases: synthpops.base.LayerGroup

A class for individual households and methods to operate on each.

Parameters:kwargs (dict) – data dictionary of the household

Class constructor for empty household.

Parameters:

• **hhid (int) – household id
• **member_uids (np.array) – ids of household members
• **reference_uid (int) – id of the reference person
• **reference_age (int) – age of the reference person

validate()

Check that information supplied to make a household is valid and update to the correct type if necessary.

get_household(pop, hhid)

Return household with id: hhid.

Parameters:

• pop (sp.Pop) – population
• hhid (int) – household id number

Returns:

A populated household.

Return type:

sp.Household

add_household(pop, household)

Add a household to the list of households.

Parameters:

• pop (sp.Pop) – population
• household (sp.Household) – household with at minimum the hhid, member_uids, member_ages, reference_uid, and reference_age.

initialize_empty_households(pop, n_households=None)

Array of empty households.

Parameters:

• pop (sp.Pop) – population
• n_households (int) – the number of households to initialize

populate_households(pop, households, age_by_uid)

Populate all of the households. Store each household at the index corresponding to it’s hhid.

Parameters:

• pop (sp.Pop) – population
• households (list) – list of lists where each sublist represents a household and contains the ids of the household members
• age_by_uid (dict) – dictionary mapping each person’s id to their age

generate_household_size_count_from_fixed_pop_size(N, hh_size_distr)

Given a number of people and a household size distribution, generate the number of homes of each size needed to place everyone in a household.

Parameters:

• N (int) – The number of people in the population.
• hh_size_distr (dict) – The distribution of household sizes.

Returns:

An array with the count of households of size s at index s-1.

assign_uids_by_homes(homes, id_len=16, use_int=True)

Assign IDs to everyone in order by their households.

Parameters:

• homes (array) – The generated synthetic ages of household members.
• id_len (int) – The length of the UID.
• use_int (bool) – If True, use ints for the uids of individuals; otherwise use strings of length ‘id_len’.

Returns:

A copy of the generated households with IDs in place of ages, and a dictionary mapping ID to age.

generate_age_count(n, age_distr)

Generate a stochastic count of people for each age given the age distribution (age_distr) and number of people to generate (n).

Parameters:

• n (int) – number of people to generate
• age_distr (list or np.ndarray) – single year age distribution

Returns:

A dictionary with the count of people to generate for each age given an age distribution and the number of people to generate.

Return type:

dict

generate_age_count_multinomial(n, age_distr)

Generate a stochastic count of people for each age given the age distribution (age_distr) and number of people to generate (n).

Parameters:

• n (int) – number of people to generate
• age_distr (list or np.ndarray) – single year age distribution

Returns:

A dictionary with the count of people to generate for each age given an age distribution and the number of people to generate.

Return type:

dict

generate_household_head_ages(household_sizes, hha_by_size, hha_brackets, ages_left_to_assign)

Generate the head of household ages conditional on household size and the expected ages of people in the population.

Parameters:

• household_sizes (np.array) – Array of household sizes to be generated
• hha_by_size (matrix) – A matrix in which each row contains the age distribution of the reference person for household size s at index s-1.
• hha_brackets (dict) – The age brackets for the heads of household.
• ages_left_to_assign (dic) – The counter of ages for the generated population left to place in a residence

Returns:

An array of head of household ages, updated counter of the ages in the population left to place in a residence.

generate_household_sizes(hh_sizes)

Create a list of the household sizes in random order so that as individuals are placed by age into homes running out of specific ages is not systemically an issue for any given household size unless certain sizes greatly outnumber households of other sizes.

Parameters:hh_sizes (array) – The count of household size s at index s-1. Returns:An array of household sizes to be generated and place people into households. Return type:Np.array

generate_larger_households_fixed_ages(larger_hh_size_array, larger_hha_chosen, hha_brackets, cm_age_brackets, cm_age_by_brackets, household_matrix, ages_left_to_assign, homes_dic)

Assign people to households larger than one person (excluding special residences like long term care facilities or agricultural workers living in shared residential quarters).

Parameters:

• hh_sizes (array) – The count of household size s at index s-1.
• hha_by_size (matrix) – A matrix in which each row contains the age distribution of the reference person for household size s at index s-1.
• hha_brackets (dict) – The age brackets for the heads of household.
• cm_age_brackets (dict) – The age brackets for the contact matrix.
• cm_age_by_brackets (dict) – A dictionary mapping age to the age bracket range it falls within.
• household_matrix (dict) – The age-specific contact matrix for the household ontact setting.
• ages_left_to_assign (dict) – Age count of people left to place in households larger than one person.

Returns:

A dictionary of households by age indexed by household size.

Return type:

dict

generate_all_households_fixed_ages(n_remaining, hh_sizes, hha_by_size, hha_brackets, cm_age_brackets, cm_age_by_brackets, contact_matrices, ages_left_to_assign)

Generate the ages of those living in households together. First create households of people living alone, then larger households. For households larger than 1, a reference individual’s age is sampled conditional on the household size, while all other household members have their ages sampled conditional on the reference person’s age and the age mixing contact matrix in households for the population under study. Fix the count of ages in the population before placing individuals in households so that the age distribution of the generated population is fixed to closely match the age distribution from data on the population.

Parameters:

• n_remaining (int) – The number of people in the population left to place in a residence.
• hh_sizes (array) – The count of household size s at index s-1.
• hha_by_size_counts (matrix) – A matrix in which each row contains the age distribution of the reference person for household size s at index s-1.
• hha_brackets (dict) – The age brackets for the heads of household.
• cm_age_brackets (dict) – The dictionary mapping age bracket keys to age bracket range matching the household contact matrix.
• cm_age_by_brackets (dict) – The dictionary mapping age to the age bracket range it falls within matching the household contact matrix.
• contact_matrices (dict) – The dictionary of the age-specific contact matrix for different physical contact settings.
• ages_left_to_assign (dict) – Age count of people left to place in households larger than one person.

Returns:

An array of all households where each household is a row and the values in the row are the ages of the household members. The first age in the row is the age of the reference individual. Households are randomly shuffled by size.

generate_larger_households_infer_ages(size, larger_household_sizes, heads_of_larger_households, hha_brackets, cm_age_brackets, cm_age_by_brackets, household_matrix, adjusted_age_dist, p=0.15)

Generate ages of those living in households of greater than one individual. Reference individual is sampled conditional on the household size. All other household members have their ages sampled conditional on the reference person’s age and the age mixing contact matrix in households for the population under study.

Parameters:

• size (int) – The household size.
• hh_sizes (array) – The count of household size s at index s-1.
• hha_by_size_counts (matrix) – A matrix in which each row contains the age distribution of the reference person for household size s at index s-1.
• hha_brackets (dict) – The age brackets for the heads of household.
• cm_age_brackets (dict) – The dictionary mapping age bracket keys to age bracket range matching the household contact matrix.
• cm_age_by_brackets (dict) – The dictionary mapping age to the age bracket range it falls within matching the household contact matrix.
• household_matrix (dict) – Age-specific contact matrix for contacts in the household setting.
• single_year_age_distr (dict) – The age distribution.

Returns:

An array of households for size size where each household is a row and the values in the row are the ages of the household members. The first age in the row is the age of the reference individual.

generate_all_households_infer_ages(n, n_remaining, hh_sizes, hha_by_size, hha_brackets, cm_age_brackets, cm_age_by_brackets, contact_matrices, adjusted_age_dist, ages_left_to_assign)

Generate the ages of those living in households together. First create households of people living alone, then larger households. For households larger than 1, a reference individual’s age is sampled conditional on the household size, while all other household members have their ages sampled conditional on the reference person’s age and the age mixing contact matrix in households for the population under study.

Parameters:

• n (int) – The number of people in the population.
• n_remaining (int) – The number of people in the population left to place in a residence.
• hh_sizes (array) – The count of household size s at index s-1.
• hha_by_size_counts (matrix) – A matrix in which each row contains the age distribution of the reference person for household size s at index s-1.
• hha_brackets (dict) – The age brackets for the heads of household.
• cm_age_brackets (dict) – The dictionary mapping age bracket keys to age bracket range matching the household contact matrix.
• cm_age_by_brackets (dict) – The dictionary mapping age to the age bracket range it falls within matching the household contact matrix.
• contact_matrices (dict) – The dictionary of the age-specific contact matrix for different physical contact settings.
• ages_left_to_assign (dict) – Age count of people left to place in households larger than one person.

Returns:

An array of all households where each household is a row and the values in the row are the ages of the household members. The first age in the row is the age of the reference individual. Households are randomly shuffled by size.

Note

This method is not guaranteed to model the population age distribution well automatically. The method called inside, generate_larger_households_infer_ages uses the method ltcf_resample_age to fit Seattle, Washington populations with long term care facilities generated. For a method that matches the age distribution well for populations in general, please use generate_all_households_fixed_ages.

The following contains an example of how you may resample from an age range that is over produced and instead sample ages from an age range that is under produced in your population. This kind of customization may be necessary when your age mixing matrix and the population you are interested in modeling differ in important but subtle ways. For example, generally household age mixing matrices reflect mixing patterns for households composed of families. This means household age mixing matrices do not generally cover college or university aged individuals living together. Without this customization, this algorithm tends to under produce young adults. This method also has a tendency to underproduce the elderly, and does not explicitly model the elderly living in nursing homes. Customizations like this should be considered in context of the specific population and culture you are trying to model. In some cultures, it is common to live in non-family households, while in others family households are the most common and include multi-generational family households. If you are unsure of how to proceed with customizations please take a look at the references listed in the overview documentation for more information.

get_all_households(homes_dic)

Get all households in a list, randomly assorted.

Parameters:homes_dic (dict) – A dictionary of households by age indexed by household size Returns:A random ordering of households with the ages of the individuals. Return type:list

get_household_sizes(popdict)

Get household sizes for each household in the popdict.

Parameters:popdict (dict) – population dictionary Returns:Dictionary of the generated household size for each household. Return type:dict

get_household_heads(popdict)

Get the id of the head of each household.

Parameters:popdict (dict) – population dictionary Returns:Dictionary of the id of the head of the household for each household. Return type:dict

Note

In static populations the id of the head of the household is the minimum id of the household members. With vital dynamics turned on and populations growing or changing households over time, this method will need to change and the household head or reference person will need to be specified at creation and when those membership events occur.

get_household_head_ages_by_size(pop)

Calculate the count of households by size and the age of the head of the household, assuming the minimal household members id is the id of the head of the household.

Parameters:pop (sp.Pop) – population object Returns:An array with rows as household size and columns as household head age brackets. Return type:np.ndarray

get_generated_household_size_distribution(household_sizes)

Get household size distribution.

Parameters:household_sizes (dict) – size of each generated household Returns:Dictionary of the generated household size distribution. Return type:dict