synthpops.school_modules module

This module generates school contacts by class and grade in flexible ways. Contacts can be clustered into classes and also mixed across the grade and across the school.

H. Guclu et. al (2016) shows that mixing across grades is low for public schools in elementary and middle schools. Mixing across grades is however higher in high schools.

Functions in this module are flexible to allow users to specify the inter-grade mixing, and to choose whether contacts are clustered within a grade. Clustering contacts across different grades is not supported because there is no data to suggest that this happens commonly.

synthpops.school_modules.add_contacts_from_edgelist(popdict, edgelist, setting)

Add contacts to popdict from edges in an edgelist. Note that this simply adds to the contacts already in the layer and does not overwrite the contacts.

Parameters

  • popdict (dict) – dict of people

  • edgelist (list) – list of edges

  • setting (str) – social setting layer

Returns

Updated popdict.

synthpops.school_modules.add_contacts_from_group(popdict, group, setting)

Add contacts to popdict from fully connected group. Note that this simply adds to the contacts already in the layer and does not overwrite the contacts.

Parameters

  • popdict (dict) – dict of people

  • group (list) – list of people in group

  • setting (str) – social setting layer

Returns

Updated popdict.

synthpops.school_modules.add_contacts_from_groups(popdict, groups, setting)

Add contacts to popdict from fully connected groups.

Parameters

  • popdict (dict) – dict of people

  • groups (list) – list of lists of people in groups

  • setting (str) – social setting layer

Returns

Updated popdict.

synthpops.school_modules.add_random_contacts_from_graph(G, expected_average_degree)

Add additional edges at random to achieve the expected or desired average degree.

Parameters

  • G (networkx Graph) – networkx Graph object

  • expected_average_degree (int) – expected or desired average degree

Returns

Updated networkx Graph object with additional edges added at random.

synthpops.school_modules.generate_random_contacts_for_additional_school_members(school_uids, additional_school_member_uids, average_additional_school_members_degree=20)

Generate random contacts for additional school members. This might be people like non teaching staff such as principals, cleaning staff, or school nurses.

Parameters

  • school_uids (list) – list of uids of individuals already in the school

  • additional_school_member_uids (list) – list of uids of the additional school member who do not have contacts yet or for whom more contacts are needed

  • average_additional_school_members_degree (float) – average degree for the additional school members

Returns

List of edges for the additional school members in school.

synthpops.school_modules.generate_random_contacts_across_school(all_school_uids, average_class_size)

Generate edges for contacts in a school where everyone mixes randomly. Assuming class and thus class size determines effective contacts.

Parameters

  • all_school_uids (list) – list of uids of individuals in the school

  • average_class_size (int) – average class size or number of contacts in school

  • verbose (bool) – If True, print some edges

Returns

List of edges between individuals in school.

synthpops.school_modules.generate_random_classes_by_grade_in_school(syn_school_uids, syn_school_ages, age_by_uid_dic, grade_age_mapping, age_grade_mapping, average_class_size=20, inter_grade_mixing=0.1, verbose=False)

Generate edges for contacts mostly within the same age/grade. Edges are randomly distributed so that clustering is roughly average_class_size/size of the grade. Inter grade mixing is done by rewiring edges, specifically swapping endpoints of pairs of randomly sampled edges.

Parameters

  • syn_school_uids (list) – list of uids of students in the school

  • syn_school_ages (list) – list of the ages of the students in the school

  • age_by_uid_dic (dict) – dict mapping uid to age

  • grade_age_mapping (dict) – dict mapping grade to an age

  • age_grade_mapping (dict) – dict mapping age to a grade

  • average_class_size (int) – average class size

  • inter_grade_mixing (float) – percent of within grade edges that rewired to create edges across grades

  • verbose (bool) – print statements throughout

Returns

List of edges between students in school.

synthpops.school_modules.generate_clustered_classes_by_grade_in_school(syn_school_uids, syn_school_ages, age_by_uid_dic, grade_age_mapping, age_grade_mapping, average_class_size=20, inter_grade_mixing=0.1, return_edges=False, verbose=False)

Generate edges for contacts mostly within the same age/grade. Edges are randomly distributed so that clustering is roughly average_class_size/size of the grade. Inter grade mixing is done by rewiring edges, specifically swapping endpoints of pairs of randomly sampled edges.

Parameters

  • syn_school_uids (list) – list of uids of students in the school

  • syn_school_ages (list) – list of the ages of the students in the school

  • age_by_uid_dic (dict) – dict mapping uid to age

  • grade_age_mapping (dict) – dict mapping grade to an age

  • age_grade_mapping (dict) – dict mapping age to a grade

  • average_class_size (int) – average class size

  • inter_grade_mixing (float) – percent of within grade edges that rewired to create edges across grades

  • return_edges (bool) – If True, return edges, else return two groups of contacts - students and teachers for each class

  • verbose (bool) – print statements throughout

Returns

List of edges between students in school or groups of contacts.

synthpops.school_modules.generate_edges_between_teachers(teachers, average_teacher_teacher_degree)

Generate edges between teachers.

Parameters

  • teachers (list) – a list of teachers

  • average_teacher_teacher_degree (int) – average number of contacts with other teachers

Returns

List of edges between teachers.

synthpops.school_modules.generate_edges_for_teachers_in_random_classes(syn_school_uids, syn_school_ages, teachers, age_by_uid_dic, average_student_teacher_ratio=20, average_teacher_teacher_degree=4, verbose=False)

Generate edges for teachers, including to both students and other teachers at the same school. Well mixed contacts within the same age/grade, some cross grade mixing. Teachers are clustered by grade mostly.

Parameters

  • syn_school_uids (list) – list of uids of students in the school

  • syn_school_ages (list) – list of the ages of the students in the school

  • teachers (list) – list of teachers in the school

  • age_by_uid_dic (dict) – dict mapping uid to age

  • grade_age_mapping (dict) – dict mapping grade to an age

  • age_grade_mapping (dict) – dict mapping age to a grade

  • average_student_teacher_ratio (int) – average number of students per teacher

  • average_teacher_teacher_degree (int) – average number of contacts with other teachers

  • verbose (bool) – print statements throughout

Returns

List of edges connected to teachers.

synthpops.school_modules.generate_edges_for_teachers_in_clustered_classes(groups, teachers, average_student_teacher_ratio=20, average_teacher_teacher_degree=4, return_edges=False, verbose=False)

Generate edges for teachers, including to both students and other teachers at the same school. Students and teachers are clustered into disjoint classes.

Parameters

  • groups (list) – list of lists of students, clustered into groups mostly by grade

  • teachers (list) – list of teachers in the school

  • average_student_teacher_ratio (int) – average number of students per teacher

  • average_teacher_teacher_degree (int) – average number of contacts with other teachers

  • return_edges (bool) – If True, return edges, else return two groups of contacts - students and teachers for each class

  • verbose (bool) – print statements throughout

Returns

List of edges connected to teachers.

synthpops.school_modules.add_school_edges(popdict, syn_school_uids, syn_school_ages, teachers, non_teaching_staff, age_by_uid_dic, grade_age_mapping, age_grade_mapping, average_class_size=20, inter_grade_mixing=0.1, average_student_teacher_ratio=20, average_teacher_teacher_degree=4, average_additional_staff_degree=20, school_mixing_type='random', verbose=False)

Generate edges for teachers, including to both students and other teachers at the same school.

Parameters

  • popdict (dict) – dictionary of people

  • syn_school_uids (list) – list of uids of students in the school

  • syn_school_ages (list) – list of the ages of the students in the school

  • teachers (list) – list of teachers in the school

  • age_by_uid_dic (dict) – dict mapping uid to age

  • grade_age_mapping (dict) – dict mapping grade to an age

  • age_grade_mapping (dict) – dict mapping age to a grade

  • average_class_size (int) – average class size

  • average_student_teacher_ratio (int) – average number of students per teacher

  • average_teacher_teacher_degree (int) – average number of contacts with other teachers

  • school_mixing_type (str) – ‘random’ for well mixed schools, ‘clustered’ for disjoint classes in a school

  • verbose (bool) – print statements throughout

Returns

Updated popdict.

synthpops.school_modules.get_default_school_type_age_ranges()

Define and return default school types and the age range for each.

Returns

A dictionary of default school types and the age range for each.

synthpops.school_modules.get_default_school_types_by_age()

Define and return default probabilities of school type for each age.

Returns

A dictionary of default probabilities for the school type likely for each age.

synthpops.school_modules.get_default_school_types_by_age_single()

Define and return default school type by age by assigning the school type with the highest probability.

Returns

A dictionary of default school type by age.

synthpops.school_modules.get_default_school_size_distr_brackets()

Define and return default school size distribution brackets.

Returns

A dictionary of school size brackets.

synthpops.school_modules.get_default_school_size_distr_by_type()

Define and return default school size distribution for each school type. The school size distributions are binned to size groups or brackets.

Returns

A dictionary of school size distributions binned by size groups or brackets for each type of default school.