synthpops.base module

The module contains frequently-used functions that do not neatly fit into other areas of the code base.

class LayerGroup(**kwargs)

Bases: dict

A generic class for individual setting group and some methods to operate on each.

Parameters:kwargs (dict) – data dictionary for the setting group

Notes

Settings currently supported include : households (H), schools (S), workplaces (W), and long term care facilities (LTCF).

Class constructor for an base empty setting group.

Parameters:**member_uids (np.array) – ids of group members

set_layer_group(**kwargs)

Set layer group values.

validate(layer_str='')

Check that information supplied to make a household is valid and update to the correct type if necessary.

member_ages(age_by_uid, subgroup_member_uids=None)

Return the ages of members in the layer group given the pop object.

Parameters:

• age_by_uid (np.ndarray) – mapping of age to uid
• subgroup_member_uids (np.ndarray, list) – subgroup of uids to return ages for

Returns:

ages of members in group or subgroup

Return type:

nd.ndarray

norm_dic(dic)

Normalize the dictionary dic.

Parameters:dic (dict) – A dictionary with numerical values. Returns:A normalized dictionary.

norm_age_group(age_dic, age_min, age_max)

Create a normalized dictionary for the range age_min to age_max, inclusive.

Parameters:

• age_dic (dict) – A dictionary with numerical values.
• age_min (int) – The minimum value of the range for the dictionary.
• age_max (int) – The maximum value of the range for the dictionary.

Returns:

A normalized dictionary for keys in the range age_min to age_max, inclusive.

get_index_by_brackets(brackets)

Create a dictionary mapping each item in the value arrays to the key. For example, if brackets are age brackets, then this function will map each age to the age bracket or bin that it belongs to, so that the resulting dictionary will give index_by_brackets[age_index] = age bracket of age_index.

Parameters:brackets (dict) – A dictionary mapping bracket or bin keys to the array of values that belong to each bracket. Returns:A dictionary mapping indices to the brackets or bins each index belongs to. Return type:dict

get_age_by_brackets(age_brackets)

Create a dictionary mapping age to the age bracket it falls in.

Parameters:age_brackets (dict) – A dictionary mapping age bracket keys to age bracket range. Returns:A dictionary of age bracket by age.

Example

age_brackets = sp.get_census_age_brackets(sp.datadir,state_location='Washington',country_location='usa')
age_by_brackets = sp.get_age_by_brackets(age_brackets)

get_ids_by_age(age_by_id)

Get lists of IDs that map to each age.

Parameters:age_by_id (dict) – A dictionary with the age of each individual by their ID. Returns:A dictionary listing IDs for each age from a dictionary that maps ID to age.

count_ages(popdict)

Create an age count from a population dictionary.

Parameters:popdict (dict) – dictionary defining population Returns:Dictionary of the age count of the population. Return type:dict

get_aggregate_ages(ages, age_by_brackets)

Create a dictionary of the count of ages by age brackets.

Parameters:

• ages (dict) – A dictionary of age count by single year.
• age_by_brackets (dict) – A dictionary mapping age to the age bracket range it falls within.

Returns:

A dictionary of aggregated age count for specified age brackets.

Example

aggregate_age_count = sp.get_aggregate_ages(age_count, age_by_brackets)
aggregate_matrix = symmetric_matrix.copy()
aggregate_matrix = sp.get_aggregate_matrix(aggregate_matrix, age_by_brackets)

get_aggregate_matrix(matrix, age_by_brackets)

Aggregate a symmetric matrix to fewer age brackets. Do not use for homogeneous mixing matrix.

Parameters:

• matrix (np.ndarray) – A symmetric age contact matrix.
• age_by_brackets (dict) – A dictionary mapping age to the age bracket range it falls within.

Returns:

A symmetric contact matrix (np.ndarray) aggregated to age brackets.

Example

age_brackets = sp.get_census_age_brackets(sp.settings_config.datadir,state_location='Washington',country_location='usa')
age_by_brackets = sp.get_age_by_brackets(age_brackets)

aggregate_age_count = sp.get_aggregate_ages(age_count, age_by_brackets)
aggregate_matrix = symmetric_matrix.copy()
aggregate_matrix = sp.get_aggregate_matrix(aggregate_matrix, age_by_brackets_dic)

asymmetric_matrix = sp.get_asymmetric_matrix(aggregate_matrix, aggregate_age_count)

get_asymmetric_matrix(symmetric_matrix, aggregate_ages)

Get the contact matrix for the average individual in each age bracket.

Parameters:

• symmetric_matrix (np.ndarray) – A symmetric age contact matrix.
• aggregate_ages (dict) – A dictionary mapping single year ages to age brackets.

Returns:

A contact matrix (np.ndarray) whose elements M_ij describe the contact frequency for the average individual in age bracket i with all possible contacts in age bracket j.

Example

age_brackets = sp.get_census_age_brackets(sp.datadir,state_location='Washington',country_location='usa')
age_by_brackets = sp.get_age_by_brackets(age_brackets)

aggregate_age_count = sp.get_aggregate_ages(age_count, age_by_brackets)
aggregate_matrix = symmetric_matrix.copy()
aggregate_matrix = sp.get_aggregate_matrix(aggregate_matrix, age_by_brackets)

asymmetric_matrix = sp.get_asymmetric_matrix(aggregate_matrix, aggregate_age_count)

get_bin_edges(size_brackets)

Get the bin edges for size brackets.

Parameters:size_brackets (dict) – dictionary mapping bracket or bin number to an array of the range of sizes Returns:An array of the bin edges.

get_bin_labels(size_brackets)

Get the bin labels from the values contained within each bracket or bin.

Parameters:size_brackets (dict) – dictionary mapping bracket or bin number to an array of the range of sizes Returns:A list of bin labels.

count_values(dic)

Counter of values in the dictionary. Keys in the returned dictionary are values from the input dictionary.

Parameters:dic (dict) – dictionary with sortable values Returns:Dictionary of the count of values. Return type:dict

count_binned_values(dic, bins=None)

Binned counter of values in the dictionary. Indices are the bin indices from the input bins.

Parameters:

• dic (dict) – dictionary with sortable and binnable values
• bins (array) – array of bin edges

Returns:

Array of the count of values binned

Return type:

array

binned_values_dist(dic, bins=None)

Binned distribution of values in the dictionary. Indices are the bin indices from the input bins.

Parameters:

• dic (dict) – dictionary with sortable and binnable values
• bins (array) – array of bin edges

Returns:

Array of the binned distribution of values.

Return type:

array