june.distributors.household_distributor¶
-
exception
june.distributors.household_distributor.
HouseholdError
¶ class for throwing household related errors
-
__init__
(*args, **kwargs)¶ Initialize self. See help(type(self)) for accurate signature.
-
with_traceback
()¶ Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
-
args
¶
-
-
class
june.distributors.household_distributor.
HouseholdDistributor
(first_kid_parent_age_differences: dict, second_kid_parent_age_differences: dict, couples_age_differences: dict, number_of_random_numbers=1000, kid_max_age=17, student_min_age=18, student_max_age=25, old_min_age=65, old_max_age=99, adult_min_age=18, adult_max_age=64, young_adult_min_age=18, young_adult_max_age=35, max_age_to_be_parent=64, max_household_size=8, allowed_household_compositions: dict = None)¶ Tool to populate areas with households and fill them with the correct composition based on census data. The most important function is “distribute_people_to_households” which takes people in an area and fills them into households.
- first_kid_parent_age_differences:
dictionary where keys are the age differences between a mother and her FIRST kid. The values are the probabilities of each age difference.
- second_kid_parent_age_differences:
dictionary where keys are the age differences between a mother and her SECOND kid. The values are the probabilities of each age difference.
- couples_age_differences:
dictionary where keys are the age differences between a woman and a man at the time of marriage. A value of 20 means that the man is 20 years older than the woman. The values are the probabilities of each age difference.
- number_of_random_numbers:
Number of random numbers required. This should be set to the number of people living in the area, minimum.
-
__init__
(first_kid_parent_age_differences: dict, second_kid_parent_age_differences: dict, couples_age_differences: dict, number_of_random_numbers=1000, kid_max_age=17, student_min_age=18, student_max_age=25, old_min_age=65, old_max_age=99, adult_min_age=18, adult_max_age=64, young_adult_min_age=18, young_adult_max_age=35, max_age_to_be_parent=64, max_household_size=8, allowed_household_compositions: dict = None)¶ Tool to populate areas with households and fill them with the correct composition based on census data. The most important function is “distribute_people_to_households” which takes people in an area and fills them into households.
- first_kid_parent_age_differences:
dictionary where keys are the age differences between a mother and her FIRST kid. The values are the probabilities of each age difference.
- second_kid_parent_age_differences:
dictionary where keys are the age differences between a mother and her SECOND kid. The values are the probabilities of each age difference.
- couples_age_differences:
dictionary where keys are the age differences between a woman and a man at the time of marriage. A value of 20 means that the man is 20 years older than the woman. The values are the probabilities of each age difference.
- number_of_random_numbers:
Number of random numbers required. This should be set to the number of people living in the area, minimum.
-
_add_to_household
(household: june.groups.household.Household, person: june.demography.person.Person, subgroup=None) → None¶ Adds person to household and assigns them the correct subgroup.
-
_check_if_age_dict_is_empty
(people_dict: dict, age: int) → bool¶ Given a people_dict that contains a list of people for each age, it deletes the age key if the number of people of that age is 0.
- people_dict:
dictionary with age as keys and list of people of that age as values.
- age:
age to check if empty.
-
_check_if_household_is_full
(household: june.groups.household.Household)¶ Checks if a household is full or has the maximum household size allowed by the Distributor.
- household:
the household to check.
-
_check_if_oldpeople_left
(men_by_age: dict, women_by_age: dict) → bool¶ Checks whether there are still old people without an allocated household.
- area:
the area to check.
-
_create_household
(area: june.geography.geography.Area, type=None, max_household_size: int = inf) → june.groups.household.Household¶ Creates household in the area.
- area:
Area in which to create the household.
- communal:
Whether it is a communal establishment (True) or not (False).
- max_household_size:
Maximum number of people allowed in the household.
-
_create_people_dicts
(area: june.geography.geography.Area)¶ Creates dictionaries with the men and women per age key living in the area.
-
_find_household_for_kid
(priority_lists)¶ Finds a suitable household for a kid. It first tries to search for a place in priority_lists[0], then 1, etc.
- priority_lists:
list of lists of households. The list should be sorted according to priority allocation.
-
_find_household_for_nonkid
(priority_lists)¶ Finds a suitable household for a person over 18 years old (who can live alone). It first tries to search for a place in priority_lists[0], then 1, etc.
- priority_lists:
list of lists of households. The list should be sorted according to priority allocation.
-
_get_closest_person_of_age
(first_dict: dict, second_dict: dict, age: int, min_age=0, max_age=100) → june.demography.person.Person¶ Tries to find the person with the closest age in first dict inside the min_age and max_age. If it fails, it looks into the second_dict. If it fails again it returns None.
- first_dict:
dictionary with lists of people by age as keys. This is the first dictionary to look for a suitable person.
- second_dict:
dictionary with lists of people by age as keys. This is the second dictionary to look for a suitable person.
- age:
the target age of the person.
- min_age:
minimum age the person should have.
- max_age:
maximum age the person should have.
-
_get_matching_parent
(kid: june.demography.person.Person, men_by_age: dict, women_by_age: dict) → june.demography.person.Person¶ Given a person under 18 years old (strictly), it finds a matching mother with an age difference sampled for the known mother-firstkid age distribution read in the __init__ function.
- kid:
The person to look a parent for.
- men_by_age
men left to allocate by age key
- women_by_age
women left to allocate by age key
- area:
The area in which to look for a parent.
-
_get_matching_partner
(person: june.demography.person.Person, men_by_age, women_by_age, under_65=False, over_65=False) → june.demography.person.Person¶ Given a person, it finds a suitable partner with similar age and opposite sex. The age difference is sampled from an observed distribution of age differences in couples in the US and the UK, and it read by __init__. We first try to look for a female parent, as it is more common to have a single mother than a single father.
- person:
the person instance to find a partner for.
- men_by_age
men left to allocate by age key
- women_by_age
women left to allocate by age key
- area:
the area where to look for a partner.
- under_65:
whether to restrict the search for a partner under 65 years old.
- over_65:
whether to restrict the search for a partner over 65 years old.
-
_get_matching_second_kid
(parent: june.demography.person.Person, men_by_age: dict, women_by_age: dict) → june.demography.person.Person¶ Given a parent, it finds a person under 18 years old with an age difference matching the distribution of age difference between a mother and their second kid.
- parent:
the parent (usually mother) to match with her second kid.
- men_by_age
men left to allocate by age key
- women_by_age
women left to allocate by age key
- area:
area in which to look for the kid.
-
_get_random_person_in_age_bracket
(men_by_age: dict, women_by_age: dict, min_age=0, max_age=100) → june.demography.person.Person¶ Returns a random person of random sex within the specified age bracket (inclusive).
- men_by_age
men left to allocate by age key
- women_by_age
women left to allocate by age key
- area:
The area to look at.
- min_age:
The minimum age the person should have.
- max_age:
The maximum age the person should have.
-
_refresh_random_numbers_list
(n=1000) → None¶ Samples one million age differences for couples and parents-kids. Sampling in batches makes the code much faster. They are converted to lists so they can be popped.
-
_remove_household_from_all_lists
(household, lists: list) → None¶ Removes the given households from all the lists in lists.
- household
an instance of Household.
- lists
list of lists of households.
-
distribute_people_and_households_to_areas
(areas: List[june.geography.geography.Area], number_households_per_composition_filename: str = PosixPath('/home/sadie/JUNE/data/input/households/household_composition_ew.csv'), n_students_filename: str = PosixPath('/home/sadie/JUNE/data/input/households/n_students_ew.csv'), n_people_in_communal_filename: str = PosixPath('/home/sadie/JUNE/data/input/households/n_communal_ew.csv'))¶ Distributes households and people into households for the given areas list. The households are stored in area.households.
- areas
list of instances of Area
- number_households_per_composition_filename
path to the data file containing the number of households per household composition per area
- n_students_filename
path to file containing the number of students per area
- n_people_in_communal_filename
path to file containing the number of people living in communal establishments per area
-
distribute_people_to_households
(men_by_age, women_by_age, area: june.geography.geography.Area, number_households_per_composition: list, n_students: int, n_people_in_communal: int) → june.groups.household.Households¶ Given a populated output area, it distributes the people to households. The instance of the Area class, area, should have two dictionary attributes,
men_by_age
andwomen_by_age
. The keys of the dictionaries are the ages and the values are the Person instances. The process of creating these dictionaries is done in people_distributor.py. Thenumber_households_per_composition
argument is a dictionary containing the number of households per each composition. We obtain this from the nomis dataset and should be read by the inputs class in the world init.- area:
area from which to take people and distribute households.
- number_households_per_composition:
dictionary containing the different possible household compositions and the number of households with that composition as key. Example: The area E00062207 has this configuration: number_households_per_composition = { “0 0 0 0 1” : 15 “0 0 0 1 0” : 20 “0 0 0 0 2” : 11 “0 0 0 2 0” : 24 “1 0 >=0 2 0” : 12 “>=2 0 >=0 2 0” : 9 “0 0 >=1 2 0” : 6 “1 0 >=0 1 0” : 5 “>=2 0 >=0 1 0” : 3 “0 0 >=1 1 0” : 7 “1 0 >=0 >=1 >=0” : 0 “>=2 0 >=0 >=1 >=0” : 1 “0 >=1 0 0 0” : 0 “0 0 0 0 >=2” : 0 “0 0 >=0 >=0 >=0” : 1 “>=0 >=0 >=0 >=0 >=0” : 0 } The encoding follows the rule “1 2 3 4 5” = 1 kid, 2 students (that live in student households), 3 young adults, 4 adults, and 5 old people.
- n_students:
the number of students living this area.
- n_people_in_communal:
the number of people living in communal establishments in this area.
-
fill_all_communal_establishments
(men_by_age, women_by_age, n_establishments: int, n_people_in_communal: int, area: june.geography.geography.Area) → List[june.groups.household.Household]¶ Fils all comunnal establishments with the remaining people that have not been allocated somewhere else.
- n_establishments:
number of communal establishments.
- n_people_in_communal:
number of people in each communal establishment
- area:
the area in which to put the household
-
fill_all_student_households
(men_by_age: dict, women_by_age: dict, area: june.geography.geography.Area, n_students: int, student_houses_number: int) → List[june.groups.household.Household]¶ Creates and fills all student households with people in the appropriate age bin (18-25 by default).
- area:
The area in which to create and fill the households.
- n_students:
Number of students in this area. Found in the NOMIS data.
- student_houses_number:
Number of student houses in this area.
-
fill_families_households
(men_by_age: dict, women_by_age: dict, n_households: int, kids_per_house: int, parents_per_house: int, old_per_house: int, area: june.geography.geography.Area, max_household_size=inf, extra_people_lists=()) → List[june.groups.household.Household]¶ - Creates and fills households with families. The strategy is the following:
Put the first kid in the household.
Find a parent for the kid based on the age difference between parents and their first kid.
Find a partner for the first parent, based on age differences at time of marriage.
Add a second kid using the age difference with the mother.
Fill an extra old person if necessary for multigenerational families.
- area:
The area in which to create and fill the households.
- n_households:
Number of households.
- kids_per_house:
Number of kids (<18) in the house.
- old_per_house:
Number of old people in the house.
- extra_people_lists:
Tuple of lists where the created households will be added to be used later to allocate unallocated people.
- max_household_size:
The maximum size of the created households.
-
fill_nokids_households
(men_by_age, women_by_age, adults_per_household: int, n_households: int, area: june.geography.geography.Area, extra_people_lists=(), max_household_size=inf) → List[june.groups.household.Household]¶ Fils households with one or two adults.
- adults_per_household:
number of adults to fill in the household can be one or two.
- n_households:
number of households with this configuration
- area:
the area in which to put the household
- extra_people_lists:
whether to include the created households in a list for extra people to be put in.
- max_household_size:
maximum size of the created households.
-
fill_oldpeople_households
(men_by_age, women_by_age, people_per_household: int, n_households: int, area: june.geography.geography.Area, extra_people_lists=(), max_household_size=inf) → List[june.groups.household.Household]¶ Creates and fills households with old people.
- area:
The area in which to create and fill the households.
- n_households:
Number of households.
- extra_people_lists:
Tuple of lists where the created households will be added to be used later to allocate unallocated people.
- max_household_size:
The maximum size of the created households.
-
fill_random_people_to_existing_households
(men_by_age, women_by_age, households_with_extra_kids: list, households_with_kids: list, households_with_extra_youngadults: list, households_with_extra_adults: list, households_with_extra_oldpeople: list, all_households: list) → None¶ The people that have not been associated a household yet are distributed in the following way. Given the lists in the arguments, we assign each age group according to this preferences: Kids -> households_with_extra_kids, households_with_kids, any Young adults -> households_with_extra_youngadults, households_with_adults, any Adults -> households_with_extra_adults, any Old people -> households_with_extra_oldpeople, any.
When we allocate someone to any house, we prioritize the houses that have a small number of people (less than the max_household_size parameter defined in the __init__)
- men_by_age
dictionary with men left to allocate by age key.
- women_by_age
dictionary with women left to allocate by age key.
- number_to_fill
number of remaining people to distribute into spare households.
- households_with_extra_kids
list of households that take extra kids.
- households_with_kids
list of households that already have kids.
- households_with_extra_youngadults
list of households that take extra young adults.
- households_with_extra_oldpeople
list of households that take extra old people
- area
area where households are.
-
fill_youngadult_households
(men_by_age: dict, women_by_age: dict, youngadults_per_household: int, n_households: int, area: june.geography.geography.Area, extra_people_lists=()) → List[june.groups.household.Household]¶ Fils households with young adults (18 to 35) years old.
- youngadults_per_household:
number of adults to fill in the household. Can be any positive number.
- n_households:
number of households with this configuration
- area:
the area in which to put the household
- extra_people_lists:
whether to include the created households in a list for extra people to be put in.
-
fill_youngadult_with_parents_households
(men_by_age: dict, women_by_age: dict, adults_per_household: int, n_households: int, area: june.geography.geography.Area, extra_people_lists=()) → List[june.groups.household.Household]¶ Fils households with one young adult (18 to 35) and one or two adults.
- youngadults_per_household:
number of adults to fill in the household. Can be one or two.
- n_households:
number of households with this configuration
- area:
the area in which to put the household
- extra_people_lists:
whether to include the created households in a list for extra people to be put in.
-
classmethod
from_df
(husband_wife_df: pandas.core.frame.DataFrame, parent_child_df: pandas.core.frame.DataFrame, **kwargs) → june.distributors.household_distributor.HouseholdDistributor¶ Initializes a household distributor from dataframes. If they are not specified they are assumed to be in the default location.
- husband_wife_filename:
Dataframe containing as index the age differences between wife and husband (relative to the wife) and one column with the probability of that age difference.
- parent_child_filename:
Dataframe containing as index the age differences between a mother and her kids. The first and second columns must contain the probabilities for the first and second kid respectively.
- Keyword Arguments:
Any extra argument that is taken by the __init__ of HouseholdDistributor.
-
classmethod
from_file
(husband_wife_filename: str = PosixPath('/home/sadie/JUNE/data/input/households/couples_age_difference.csv'), parent_child_filename: str = PosixPath('/home/sadie/JUNE/data/input/households/parent_kid_age_difference.csv'), config_filename: str = PosixPath('/home/sadie/JUNE/configs/defaults/distributors/household_distributor.yaml'), number_of_random_numbers=1000) → june.distributors.household_distributor.HouseholdDistributor¶ Initializes a household distributor from file. If they are not specified they are assumed to be in the default location.
- husband_wife_filename:
Path of the CSV file containing in one column the age differences between wife and husband (relative to the wife) and in the second columns the probability of that age difference.
- parent_child_filename:
Path of the CSV file containing in one column the age differences between a mother and her kids. The second and third columns must contain the probabilities for the first and second kid respectively.
- config_filename:
Path of the config file defining the different age groups.
- number_of_random_numbers:
Number of random numbers to initialize. This should be equal to the number of people in the area we want to put households in.
-
june.distributors.household_distributor.
count_items_in_dict
(dictionary)¶
-
june.distributors.household_distributor.
count_remaining_people
(dict1, dict2)¶
-
june.distributors.household_distributor.
get_closest_element_in_array
(array, value)¶
-
june.distributors.household_distributor.
default_logging_config_filename
= PosixPath('/home/sadie/JUNE/configs/config_world_creation_logger.yaml')¶ This file contains routines to distribute people to households according to census data.