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_sizes_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.

generate_household_head_age_by_size(hha_by_size_counts, hha_brackets, hh_size, single_year_age_distr)

Generate the age of the head of the household, also known as the reference person of the household, conditional on the size of the household.

Parameters:

• 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.
• hh_size (int) – The household size.
• single_year_age_distr (dict) – The age distribution.

Returns:

Age of the head of the household or reference person.

generate_living_alone(hh_sizes, hha_by_size_counts, hha_brackets, single_year_age_distr)

Generate the ages of those living alone.

Parameters:

• 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.
• single_year_age_distr (dict) – The age distribution.

Returns:

An array of households of size 1 where each household is a row and the value in the row is the age of the household member.

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_living_alone_method_2(hh_sizes, hha_by_size, hha_brackets, age_count)

Generate the ages of those living alone.

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.
• age_distr (dict) – The age distribution.

Returns:

An array of households of size 1 where each household is a row and the value in the row is the age of the household member.

generate_larger_household_sizes(hh_sizes)

Create a list of the households larger than 1 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_head_ages(larger_hh_size_array, hha_by_size, hha_brackets, ages_left_to_assign)

Generate the ages of the heads of households for households larger than 2.

generate_larger_households_method_2(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.
• larger_homes_age_count (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

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