synthpops.households module¶

Functions for generating households

synthpops.households.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.

synthpops.households.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.

synthpops.households.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.

synthpops.households.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.

synthpops.households.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

synthpops.households.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.

synthpops.households.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

synthpops.households.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.

synthpops.households.generate_larger_households_method_2(larger_hh_size_array, larger_hha_chosen, hha_brackets, cm_age_brackets, cm_age_by_brackets_dic, 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_dic (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

synthpops.households.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