synthpops.contact_networks module

This module generates the household, school, and workplace contact networks.

synthpops.contact_networks.make_contacts_from_microstructure_objects(age_by_uid_dic, homes_by_uids, schools_by_uids=None, teachers_by_uids=None, non_teaching_staff_uids=None, workplaces_by_uids=None, facilities_by_uids=None, facilities_staff_uids=None, use_two_group_reduction=False, average_LTCF_degree=20, with_school_types=False, school_mixing_type='random', average_class_size=20, inter_grade_mixing=0.1, average_student_teacher_ratio=20, average_teacher_teacher_degree=3, average_student_all_staff_ratio=15, average_additional_staff_degree=20, school_type_by_age=None, workplaces_by_industry_codes=None, verbose=False, max_contacts=None)

From microstructure objects (dictionary mapping ID to age, lists of lists in different settings, etc.), create a dictionary of individuals. Each key is the ID of an individual which maps to a dictionary for that individual with attributes such as their age, household ID (hhid), school ID (scid), workplace ID (wpid), workplace industry code (wpindcode) if available, and contacts in different layers.

Parameters

  • age_by_uid_dic (dict) – dictionary mapping id to age for all individuals in the population

  • homes_by_uids (list) – A list of lists where each sublist is a household and the IDs of the household members.

  • schools_by_uids (list) – A list of lists, where each sublist represents a school and the ids of the students and teachers within it

  • teachers_by_uids (list) – A list of lists, where each sublist represents a school and the ids of the teachers within it

  • workplaces_by_uids (list) – A list of lists, where each sublist represents a workplace and the ids of the workers within it

  • facilities_by_uids (list) – A list of lists, where each sublist represents a skilled nursing or long term care facility and the ids of the residents living within it

  • facilities_staff_uids (list) – A list of lists, where each sublist represents a skilled nursing or long term care facility and the ids of the staff working within it

  • non_teaching_staff_uids (list) – None or a list of lists, where each sublist represents a school and the ids of the non teaching staff within it

  • use_two_group_reduction (bool) – If True, create long term care facilities with reduced contacts across both groups

  • average_LTCF_degree (int) – default average degree in long term care facilities

  • with_school_types (bool) – If True, creates explicit school types.

  • school_mixing_type (str or dict) – The mixing type for schools, ‘random’, ‘age_clustered’, or ‘age_and_class_clustered’ if string, and a dictionary of these by school type otherwise. ‘random’ means random graphs for each school, ‘age_clustered’ means random graphs but with students mostly mixing within the age/grade (inter_grade_mixing controls mixing between grades), ‘age_and_grade_clustered’ means students cohorted into classes with their own teachers.

  • average_class_size (float) – The average classroom size.

  • inter_grade_mixing (float) – The average fraction of mixing between grades in the same school for clustered school mixing types.

  • average_student_teacher_ratio (float) – The average number of students per teacher.

  • average_teacher_teacher_degree (float) – The average number of contacts per teacher with other teachers.

  • average_student_all_staff_ratio (float) – The average number of students per staff members at school (including both teachers and non teachers).

  • average_additional_staff_degree (float) – The average number of contacts per additional non teaching staff in schools.

  • school_type_by_age (dict) – A dictionary of probabilities for the school type likely for each age.

  • workplaces_by_industry_codes (np.ndarray or None) – array with workplace industry code for each workplace

  • verbose (bool) – If True, print debugging statements.

  • trimmed_size_dic (dict) – If supplied, trim contacts on creation rather than post hoc.

Returns

A popdict of people with attributes. Dictionary keys are the IDs of individuals in the population and the values are a dictionary for each individual with their attributes, such as age, household ID (hhid), school ID (scid), workplace ID (wpid), workplace industry code (wpindcode) if available, and the IDs of their contacts in different layers. Different layers available are households (‘H’), schools (‘S’), and workplaces (‘W’), and long term care facilities (‘LTCF’). Contacts in these layers are clustered and thus form a network composed of groups of people interacting with each other. For example, all household members are contacts of each other, and everyone in the same school is considered a contact of each other. If use_two_group_reduction is True, then contracts within ‘LTCF’ are reduced from fully connected.

Notes

Methods to trim large groups of contacts down to better approximate a sense of close contacts (such as classroom sizes or smaller work groups are available via sp.trim_contacts() or sp.create_reduced_contacts_with_group_types(): see these methods for more details).

synthpops.contact_networks.create_reduced_contacts_with_group_types(popdict, group_1, group_2, setting, average_degree=20, p_matrix=None, force_cross_edges=True)

Create contacts between members of group 1 and group 2, fixing the average degree, and the probability of an edge between any two groups controlled by p_matrix if provided. Forces inter group edge for each individual in group 1 with force_cross_groups equal to True. This means not everyone in group 2 will have a contact with group 1.

Parameters

  • group_1 (list) – list of ids for group 1

  • group_2 (list) – list of ids for group 2

  • average_degree (int) – average degree across group 1 and 2

  • p_matrix (np.ndarray) – probability matrix for edges between any two groups

  • force_cross_groups (bool) – If True, force each individual to have at least one contact with a member from the other group

Returns

Popdict with edges added for nodes in the two groups.

Notes

This method uses the Stochastic Block Model algorithm to generate contacts both between nodes in different groups

and for nodes within the same group. In the current version, fixing the average degree and p_matrix, the matrix of probabilities for edges between any two groups is not supported. Future versions may add support for this.