Utilities

Overview

This module contains various utility functions that are used throughout the py0 module. These are imported automatically when py0 is imported.

Details

class utils.TransitionMatrix(compartment_names, infectious_compartments)

Defines the transition between different compartments in the disease model, given different epidemiology parameters.

add_transition(name1, name2, time, time_var)

Parameters

name1 (string) – source compartment
name2 (string) – destination compartment
time (float) – time it takes to move from source compartment to destination compartment. This is typically the reciprocal of rates.
time_var (float) – variance of the time it takes to move from source compartment to destination compartment. Use zero unless you are creating an esemble of trajectories to do inference using MaxEnt.

property value: Returns matrix value.

utils.compartment_restrainer(restrained_patches, restrained_compartments, ref_traj, prior, npoints=5, noise=0, start_time=0, end_time=None, time_average=7, marker_size=10, marker_color='r')

Adds restraints to reference traj based on selected compartments of selected patches.

Parameters

restrained_patches (list) – index of the patches (nodes) restrained
restrained_compartments (list) – index values for the restrained compartments
ref_traj (a [1, T, M, C] tensor with dtype tf.float32, where T is the number of timesteps, M is the number of patches (nodes) and C is the number of compartments.) – reference traj
prior (maxent.prior) – Prior distribution for expected deviation from target for restraint. Can be either ‘EmptyPrior’ for exact agreement or set to ‘Laplace’ for more allowable disagreement.
npoints (int) – number of data points in each restrained compartment
noise (float) – multiplicative noise to be added to observations to allow higher uncertainty
start_time (int) – index for the lower time limit of restraints
end_time (int) – index for the higher time limit of restraints. If not provided, maximum timestep will be assumed.
time_average (int) – number of timesteps to for time averaging of restraints
marker_size (int) – marker size for restraints
marker_color (string) – marker color for restraints

Returns

restraints, plot_fxns_list

utils.draw_graph(graph, weights=None, heatmap=False, title=None, dpi=150, true_origin=None, color_bar=True)

Plots networkx graph.

Parameters

graph – networkx graph
weights – probabiity of being exposed in every patch at time zero across all the sample trajs. If not provided uniform probability will be assumed over all nodes.
heatmap (bool) – change node color based on weights
title (string) – plot title
dpi (int) – dpi value of plot
true_origin (int) – index for the true origin node
color_bar (bool) – enables color bar in plot

utils.draw_graph_on_map(mobility_matrix, geojson, title=None, node_size=300, node_color='#eb4034', edge_color='#555555', map_face_colors=None, fontsize=12, figsize=(10, 10), ax=None, alpha_edge=0.3, alpha_node=0.8, true_origin=None, restrained_patches=None, obs_color='C0', org_color='C8', show_map_only=False, show_legend=False)

Plots networkx graph on a map given mobility flows and geographic features. The edges are weighted by the mobility flows between the nodes. This function also alows for visualization of true orgin node and observed ones.

Parameters

mobility_matrix (numpy array of [M, M], where M is the number of nodes in the metapopulation) – mobility flows between the nodes
geojson (string) – path to GeoJSON file describing the geographic features of the metapopulation
title (string) – figure title
node_size (int) – size for the networkx nodes
node_color (string or a list of strings with length M) – color for the networkx nodes
edge_color (string) – color for the networkx edges
map_face_colors (string or a list of strings with length M) – color for the faces of patches on the map
fontsize (float) – font size
figsize (tupple) – figure size
ax – matplotlib.axes.AxesSubplot. Defaults to a new axis.
show_legend (bool) – show legend for true origin or obsevations.
alpha_edge (float) – alpha value for edges that allows transparency
alpha_nodes (float) – alpha value for nodes that allows transparency
true_origin (int) – index for the true origin node
restrained_patches (list) – index of the patches (nodes) restrained
obs_color (string) – marker color for the observation nodes
org_color (tensor with dtype tf.float32) – marker size for the true origin node
show_map_only (bool) – Showing the map only without the networkx graph. Default is False.

utils.exposed_finder(trajs)

Finds the initial exposed patch (t=0) for trajs

Parameters: trajs (tensor with dtype tf.float32 of shape [N, T, M, C] where N is the number of samples, T is the number of timesteps, M is the number of patches (nodes) and C is the number of compartments.) – ensemble of trajectories after sampling
Returns: A numpy array containing the index of the initial exposed node for the ensemble of trajectories

utils.gen_graph(M)

Generates a fully connected dense networkx graph of size M, edge list and node list.

Parameters: M (int) – number of nodes in the metapopulation
Returns: graph, edge list, node list

utils.gen_graph_from_R(mobility_matrix)

Generates a networkx graph of size mobility_matrix.shape[0], edge list and node list.

Parameters: mobility_matrix (numpy array of [M, M], where M is the number of nodes in the metapopulation) – mobility flows between the nodes
Returns: graph, edge list, node list

utils.gen_random_graph(M, p=1.0, seed=None)

Returns a random networkx graph of size M with connection probability p

Parameters

M (int) – number of nodes in the metapopulation
p (float) – node connection probability
seed – allows random seeding for graph generations

Returns

graph

utils.get_dist(prior_params, compartments=['E', 'A', 'I', 'R'])

Gets distributions for the model parameters in the ensemble trectory sampling.

Parameters

prior_params (list) – model parameters during sampling over different batches.
compartments (list) – list of compartments except for ‘S’ (susceptible) as strings.

return: list of model parameter’s distributions.

utils.graph_degree(graph)

Returns graph degree of a network graph based on networkx graph input.

Parameters: graph – networkx graph
Returns: graph degree

utils.p0_loss(trajs, weights, true_origin)

Returns cross-entropy loss for p0 based on sampled trajs and maxent weights, size of meta-population and ground-truth p0 node inputs.

Parameters

trajs (a [N, T, M, C] tensor with dtype tf.float32, where N is the number of samples, T is the number of timesteps, M is the number of patches (nodes) and C is the number of compartments) – sampled ensemble of trajectories
weights (tensor with dtype tf.float32) – weights of the trajectories in the ensemble. If not provided, will be assumed as 1/N.
true_origin (int) – index for the true origin node

Returns

cross-entropy loss

utils.p0_map(prior_exposed_patch, meta_pop_size, weights=None, patch_names=None, title=None, choropleth=False, geojson=None, fontsize=12, figsize=(15, 8), vmin=None, vmax=None, restrained_patches=None, true_origin=None, obs_size=5, obs_color='C0', org_color='C8', colormap='Reds', ax=None, projection=None, show_legend=True, show_cbar=True)

Plots the weighted probabiity of being exposed in every patch at time zero on a grid or on a choropleth map (this requires geopandas and geoplot packages). If choropleth plotting is enabled, make sure your geojson has ‘county’ as header for the counties name column and your patches names are alphabetically sorted.

Parameters

prior_exposed_patch (an array of size N (sample size)) – output of exposed_finder function.
meta_pop_size (int) – size of the metapopulation
weights (tensor with dtype tf.float32) – weights of the trajectories in the ensemble. If not provided, will be assumed as 1/N.
patch_names (list) – name of the patches. Note that the namings should be similar to names from GeoJSON if using choropleth.
title (string) – figure title
choropleth (bool) – turn on if plotting choropleth plots
geojson (string) – path to GeoJSON file describing the geographic features of the metapopulation
fontsize (float) – font size
figsize (tupple) – figure size
vmin (float) – minimum value of the color bar
vmax (float) – maximum value of the color bar
restrained_patches (list) – index of the patches (nodes) restrained
true_origin (int) – index for the true origin node
obs_size (float) – marker size for the observation nodes
obs_color (string) – marker color for the observation nodes
org_color (tensor with dtype tf.float32) – marker size for the true origin node
colormap (string) – Matplotlib colormaps
ax – matplotlib.axes.AxesSubplot. Defaults to a new axis.
projection – the projection to use. For reference see Working with Projections.
show_legend (bool) – show legend for true origin or obsevations.
show_cbar (bool) – show heatmap color bar

utils.patch_quantile(trajs, *args, ref_traj=None, weights=None, lower_q_bound=0.3333333333333333, upper_q_bound=0.6666666666666666, restrained_patches=None, plot_fxns_list=None, figsize=(18, 18), patch_names=None, fancy_shading=False, n_shading_gradients=30, alpha=0.6, obs_color='C0', yscale_log=False, **kw_args)

Does traj_quantile for trajectories of shape [N, T, M, C] where N is the number of samples, T is the number of timesteps,: M is the number of patches (nodes) and C is the number of compartments.

Parameters

trajs (tensor with dtype tf.float32 of shape [N, T, M, C] where N is the number of samples, T is the number of timesteps, M is the number of patches (nodes) and C is the number of compartments.) – ensemble of trajectories after sampling
ref_traj (tensor with dtype tf.float32 of shape [1, T, M, C] where T is the number of timesteps, M is the number of patches (nodes) and C is the number of compartments.) – reference trajectory
weights (tensor with dtype tf.float32) – weights for the each trajectory in the ensemble. If not defined uniform weights will be assumed.
lower_q_bound (float) – lower quantile bound
upper_q_bound (float) – upper quantile bound
restrained_patches (list) – index of the patches (nodes) restrained
plot_fxns_list (list) – output of compartment_restrainer
figsize (tupple) – figure size
patch_names (list) – name of the patches (nodes). If not provided patches name will be defined by their index.
fancy_shading (bool) – allows for gradient shading of the confidence interval
n_shading_gradients (int) – number of intervals for shading gradients
alpha (float) – alpha value for edges that allows transparency
obs_color (string) – marker color for the observation nodes
yscale_log (bool) – change y axis scale to log for better visualization of the observations.

utils.plot_dist(R_dist, E_A, A_I, I_R, start_exposed_dist, beta_dist, name='prior')

plots a seaborn.distplot for the model’s prior parameter distribution.

Parameters

R_dist – sampled mobility flows as tensor with dtype tf.float32
E_A – time for going from E->A as tensor with dtype tf.float32
A_I – time for going from A->I as tensor with dtype tf.float32
I_R – time for going from I->R as tensor with dtype tf.float32
start_exposed_dist – starting exposed fraction as tensor with dtype tf.float32
beta_dist – beta value(s) as tensor with dtype tf.float32
name (string) – name for the distributions that shows up in the figure title

utils.sparse_graph_mobility(sparse_graph, fully_connected_mobility_matrix)

Generates a sprase mobility matrix based on sparse graph and a fully connected mobility matrix inputs. For a fully connected graph, the output mobility matrix remains the same.

Parameters

graph – networkx sparse graph
fully_connected_mobility_matrix (numpy array) – [M, M] array with values defining mobility flows between nodes

Returns

sparsed mobility matrix

utils.traj_loss(ref_traj, trajs, weights)

Returns Kullback–Leibler (KL) divergence loss for predicted traj based on a reference traj and MaxEnt reweighted trajs.

Parameters

ref_traj (a [1, T, M, C] tensor with dtype tf.float32, where T is the number of timesteps, M is the number of patches (nodes) and C is the number of compartments.) – reference traj
trajs (a [N, T, M, C] tensor with dtype tf.float32, where N is the number of samples, T is the number of timesteps, M is the number of patches (nodes) and C is the number of compartments) – sampled ensemble of trajectories

Returns

KL divergence as a scalar value

utils.traj_quantile(trajs, weights=None, lower_q_bound=0.3333333333333333, upper_q_bound=0.6666666666666666, figsize=(9, 9), names=None, plot_means=True, ax=None, add_legend=True, alpha=0.6, fancy_shading=False, n_shading_gradients=30)

Make a plot of all the trajectories and the average trajectory based on trajectory weights and lower and upper quantile values.

Parameters

trajs (tensor with dtype tf.float32 of shape [N, T, M, C] where N is the number of samples, T is the number of timesteps, M is the number of patches (nodes) and C is the number of compartments.) – ensemble of trajectories after sampling
weights (tensor with dtype tf.float32) – weights for the each trajectory in the ensemble. If not defined uniform weights will be assumed.
lower_q_bound (float) – lower quantile bound
upper_q_bound (float) – upper quantile bound
figsize (tupple) – figure size
names (list) – name of compartments as strings
plot_means (bool) – if True approximates quantiles as distance from median applied to mean.
ax – matplotlib.axes.AxesSubplot. Defaults to a new axis.
add_legend (bool) – show legend
alpha (float) – alpha value for edges that allows transparency
fancy_shading (bool) – allows for gradient shading of the confidence interval
n_shading_gradients (int) – number of intervals for shading gradients

utils.traj_to_restraints(ref_traj, inner_slice, npoints, prior, noise=0.1, time_average=7, start_time=0, end_time=None, marker_size=10, marker_color='r')

Creates npoints restraints based on given trajectory with multiplicative noise and time averaging. For example, it could be weekly averages with some noise.

Parameters

ref_traj (a [1, T, M, C] tensor with dtype tf.float32, where T is the number of timesteps, M is the number of patches (nodes) and C is the number of compartments.) – reference traj
inner_slice (list) – list of length 2. First index determines the patch and second index determines what compartment on that patch is restrained.
npoints (int) – number of data points in each restrained compartment
prior (maxent.prior) – Prior distribution for expected deviation from target for restraint. Can be either ‘EmptyPrior’ for exact agreement or set to ‘Laplace’ for more allowable disagreement.
noise (float) – multiplicative noise to be added to observations to allow higher uncertainty
time_average (int) – number of timesteps to for time averaging of restraints
start_time (int) – index for the lower time limit of restraints
end_time (int) – index for the higher time limit of restraints. If not provided, maximum timestep will be assumed.
marker_size (int) – marker size for restraints
marker_color (string) – marker color for restraints

Returns

list of restraints, list of functions which take a matplotlib axis and lambda value and plot the restraint on it.

utils.weighted_exposed_prob_finder(prior_exposed_patch, meta_pop_size, weights=None)

Finds the weighted probability of being exposed in every patch at time zero across all the sample trajs.

Parameters

prior_exposed_patch (an array of size N (sample size)) – output of exposed_finder function.
meta_pop_size (int) – size of the metapopulation
weights (tensor with dtype tf.float32) – weights of the trajectories in the ensemble. If not provided, will be assumed as 1/N.

Returns

weighted probability of being exposed across all patches

utils.weighted_quantile(values, quantiles, sample_weight=None, values_sorted=False, old_style=False)

Very close to numpy.percentile, but supports weights.: Note: quantiles should be in [0, 1]!

Parameters

values – numpy.array with data
quantiles – array-like with many quantiles needed
sample_weight – array-like of the same length as array
values_sorted – bool, if True, then will avoid sorting of initial array
old_style – if True, will correct output to be consistent with numpy.percentile.

Returns

numpy.array with computed quantiles.