synthpops.plotting module¶

This module provides plotting methods including methods to plot the age-specific contact matrix in different contact layers.

class plotting_kwargs(*args, **kwargs)[source]¶

Bases: sciris.sc_odict.objdict

A class to set and operate on plotting kwargs throughout synthpops.

Parameters:	kwargs (dict) – dictionary of plotting parameters to be used.

Class constructor for plotting_kwargs.

initialize()[source]¶: Initialize plot settings.

set_font(*args, **font)[source]¶: Set font styles.

default_plotting_kwargs()[source]¶: Define default plotting kwargs to be used in plotting methods.

set_figure_display_size(*args, **kwargs)[source]¶

Update plotting kwargs with new calculated display sizes.

Parameters:	kwargs (sc.objdict) – new values to update with
Returns:	Updated kwargs and recalculating the display sizes.

set_default_pop_pars()[source]¶: Check if method has some key pop parameters to call on data. If not, use defaults and warn user of their use and value.

make_title(suffix=None, override=False)[source]¶

Create the title for the figure depending on the location information and if there already exists a preset title_prefix.

Parameters:	suffix (str) – title suffix override (bool) – If True, override the title_prefix already stored in self and create a new one.
Returns:	None.

restore_defaults()[source]¶: Reset matplotlib defaults.

update_defaults(method_defaults, kwargs)[source]¶: Update defaults with method defaults and kwargs.

axis¶: Dictionary of axis settings.

calculate_contact_matrix(population, density_or_frequency='density', layer='H')[source]¶

Calculate the symmetric age-specific contact matrix from the connections for all people in the population. density_or_frequency sets the type of contact matrix calculated.

When density_or_frequency is set to ‘frequency’ each person is assumed to have a fixed amount of contact with others they are connected to in a setting so each person will split their contact amount equally among their connections. This means that if a person has links to 4 other individuals then 1/4 will be added to the matrix element matrix[age_i][age_j] for each link, where age_i is the age of the individual and age_j is the age of the contact. This follows the mass action principle such that increased density or number of people a person is in contact with leads to decreased per-link or connection contact rate.

When density_or_frequency is set to ‘density’ the amount of contact each person has with others scales with the number of people they are connected to. This means that a person with connections to 4 individuals has a higher total contact rate than a person with connection to 3 individuals. For this definition if a person has links to 4 other individuals then 1 will be added to the matrix element matrix[age_i][age_j] for each contact. This follows the ‘pseudo’mass action principle such that the per-link or connection contact rate is constant.

Parameters:	population (dict) – A dictionary of a population with attributes. density_or_frequency (str) – option for the type of contact matrix calculated. layer (str) – name of the physial contact setting, see notes.
Returns:	Symmetric age specific contact matrix.
Return type:	np.ndarray

Note

H for households, S for schools, W for workplaces, C for community or other, and ‘LTCF’ for long term care facilities.

plot_contacts(pop, **kwargs)[source]¶

Plot the age mixing matrix for a specific contact layer.

Parameters:

pop (pop object) – population, either synthpops.pop.Pop or dict
**layer (str) – name of the physial contact layer: H for households, S for schools, W for workplaces, C for community or other
**aggregate_flag (bool) – If True, plot the contact matrix for aggregate age brackets, else single year age contact matrix.
**logcolors_flag (bool) – If True, plot heatmap in logscale
**density_or_frequency (str) – If ‘density’, then each contact counts for 1/(group size -1) of a person’s contact in a group, elif ‘frequency’ then count each contact. This means that more people in a group leads to higher rates of contact/exposure.
**state_location (string) – name of the state the location is in
**country_location (string) – name of the country the location is in
**cmap (str or Matplotlib cmap) – colormap
**fontsize (int) – base font size
**rotation (int) – rotation for x axis labels
**title_prefix (str) – optional title prefix for the figure
**fig (matplotlib.figure) – If supplied, use this figure instead of generating one
**ax (matplotlib.axes) – If supplied, use these axes instead of generating one
**do_show (bool) – If True, show the plot
**do_save (bool) – If True, save the plot to disk

Returns:

Matplotlib figure.

plot_array(expected, fig=None, ax=None, **kwargs)[source]¶

Plot histogram on a sorted array based by names. If names not provided the order will be used. If generate data is not provided, plot only the expected values. Note this can only be used with the limitation that data that has already been binned. Figure will be saved in figdir if given or else working directory.

Parameters:

expected (array) – Array of expected values
fig (matplotlib.figure) – Matplotlib.figure object
ax (matplotlib.axis) – Matplotlib.axes object
**xvalue (array) – Array of values used in X-axis, must be the same length as expected
**generated (array) – Array of values generated using a model
**names (list or dict) – names to display on x-axis, default is set to the indexes of data
**figname (str) – name to save figure to disk
**figdir (str) – directory to save the plot if provided
**prefix (str) – used to prefix the title of the plot
**fontsize (float) – default fontsize
**color_1 (str) – color for expected data
**color_2 (str) – color for generated data
**expect_label (str) – Label to show in the plot, default to “expected”
**value_text (bool) – If True, display the values on top of the bar if specified
**rotation (float) – rotation angle for xticklabels
**binned (bool) – If True, data are binned. Else, if False, plot a simple histogram for expected data.
**do_show (bool) – If True, show the plot
**do_save (bool) – If True, save the plot to disk

Returns:

Matplotlib figure and axes.

plot_ages(pop, **kwargs)[source]¶

Plot a comparison of the expected and generated age distribution.

Parameters:

pop (pop object) – population, either synthpops.pop.Pop, sp.people.People, or dict
**left (float) – Matplotlib.figure.subplot.left
**right (float) – Matplotlib.figure.subplot.right
**top (float) – Matplotlib.figure.subplot.top
**bottom (float) – Matplotlib.figure.subplot.bottom
**color_1 (str) – color for expected data
**color_2 (str) – color for data from generated population
**fontsize (float) – Matplotlib.figure.fontsize
**figname (str) – name to save figure to disk
**comparison (bool) – If True, plot comparison to the generated population
**do_show (bool) – If True, show the plot
**do_save (bool) – If True, save the plot to disk

Returns:

Matplotlib figure and axes.

Note

If using pop with type sp.people.Pop or dict, args must be supplied for the location parameters to get the expected distribution.

Example:

pars = {'n': 10e3, 'location':'seattle_metro', 'state_location':'Washington', 'country_location':'usa'}
pop = sp.Pop(**pars)
fig, ax = pop.plot_age_distribution_comparison()

popdict = pop.to_dict()
kwargs = pars.copy()
kwargs['datadir'] = sp.datadir
fig, ax = sp.plot_age_distribution_comparison(popdict, **kwargs)

plot_household_sizes(pop, **kwargs)[source]¶

Plot a comparison of the expected and generated household size distribution.

Parameters:

pop (pop object) – population, either synthpops.pop.Pop or dict
**left (float) – Matplotlib.figure.subplot.left
**right (float) – Matplotlib.figure.subplot.right
**top (float) – Matplotlib.figure.subplot.top
**bottom (float) – Matplotlib.figure.subplot.bottom
**color_1 (str) – color for expected data
**color_2 (str) – color for data from generated population
**fontsize (float) – Matplotlib.figure.fontsize
**figname (str) – name to save figure to disk
**comparison (bool) – If True, plot comparison to the generated population
**do_show (bool) – If True, show the plot
**do_save (bool) – If True, save the plot to disk

Returns:

Matplotlib figure and axes.

Note

If using pop with type dict, args must be supplied for the location parameter to get the expected rates. sp.people.People pop type not yet supported.

Example:

pars = {'n': 10e3, 'location':'seattle_metro', 'state_location':'Washington', 'country_location':'usa'}
pop = sp.Pop(**pars)
fig, ax = pop.plot_household_sizes()

popdict = pop.to_dict()
kwargs = pars.copy()
kwargs['datadir'] = sp.datadir
fig, ax = sp.plot_household_sizes(popdict, **kwargs)

plot_ltcf_resident_sizes(pop, **kwargs)[source]¶

Plot a comparison of the expected and generated ltcf resident sizes.

Parameters:

pop (pop object) – population, either synthpops.pop.Pop or dict
**left (float) – Matplotlib.figure.subplot.left
**right (float) – Matplotlib.figure.subplot.right
**top (float) – Matplotlib.figure.subplot.top
**bottom (float) – Matplotlib.figure.subplot.bottom
**color_1 (str) – color for expected data
**color_2 (str) – color for data from generated population
**fontsize (float) – Matplotlib.figure.fontsize
**figname (str) – name to save figure to disk
**comparison (bool) – If True, plot comparison to the generated population
**do_show (bool) – If True, show the plot
**do_save (bool) – If True, save the plot to disk

Returns:

Matplotlib figure and axes.

Note

If using pop with type dict, args must be supplied for the location parameter to get the expected rates. sp.people.People pop type not yet supported.

Example:

pars = {'n': 10e3, 'location':'seattle_metro', 'state_location':'Washington', 'country_location':'usa'}
pop = sp.Pop(**pars)
fig, ax = pop.plot_ltcf_resident_sizes()

popdict = pop.to_dict()
kwargs = pars.copy()
kwargs['datadir'] = sp.datadir
fig, ax = sp.plot_ltcf_resident_sizes(popdict, **kwargs)

plot_enrollment_rates_by_age(pop, **kwargs)[source]¶

Plot a comparison of the expected and generated school enrollment rates by age.

Parameters:

pop (pop object) – population, either synthpops.pop.Pop or dict
**left (float) – Matplotlib.figure.subplot.left
**right (float) – Matplotlib.figure.subplot.right
**top (float) – Matplotlib.figure.subplot.top
**bottom (float) – Matplotlib.figure.subplot.bottom
**color_1 (str) – color for expected data
**color_2 (str) – color for data from generated population
**fontsize (float) – Matplotlib.figure.fontsize
**figname (str) – name to save figure to disk
**comparison (bool) – If True, plot comparison to the generated population
**do_show (bool) – If True, show the plot
**do_save (bool) – If True, save the plot to disk

Returns:

Matplotlib figure and axes.

Note

If using pop with type dict, args must be supplied for the location parameter to get the expected rates. sp.people.People pop type not yet supported.

Example:

pars = {'n': 10e3, 'location':'seattle_metro', 'state_location':'Washington', 'country_location':'usa'}
pop = sp.Pop(**pars)
fig, ax = pop.plot_enrollment_rates_by_age()

popdict = pop.to_dict()
kwargs = pars.copy()
kwargs['datadir'] = sp.datadir
fig, ax = sp.plot_enrollment_rates_by_age(popdict, **kwargs)

plot_employment_rates_by_age(pop, **kwargs)[source]¶

Plot a comparison of the expected and generated employment rates by age.

Parameters:

pop (pop object) – population, either synthpops.pop.Pop or dict
**left (float) – Matplotlib.figure.subplot.left
**right (float) – Matplotlib.figure.subplot.right
**top (float) – Matplotlib.figure.subplot.top
**bottom (float) – Matplotlib.figure.subplot.bottom
**color_1 (str) – color for expected data
**color_2 (str) – color for data from generated population
**fontsize (float) – Matplotlib.figure.fontsize
**figname (str) – name to save figure to disk
**comparison (bool) – If True, plot comparison to the generated population
**do_show (bool) – If True, show the plot
**do_save (bool) – If True, save the plot to disk

Returns:

Matplotlib figure and axes.

Note

If using pop with type dict, args must be supplied for the location parameter to get the expected rates. sp.people.People pop type not yet supported.

Example:

pars = {'n': 10e3, 'location':'seattle_metro', 'state_location':'Washington', 'country_location':'usa'}
pop = sp.Pop(**pars)
fig, ax = pop.plot_employment_rates_by_age()

popdict = pop.to_dict()
kwargs = pars.copy()
kwargs['datadir'] = sp.datadir
fig, ax = sp.plot_employment_rates_by_age(popdict, **kwargs)

plot_school_sizes(pop, **kwargs)[source]¶

Plot a comparison of the expected and generated school size distribution for each type of school expected.

Parameters:

pop (pop object) – population, either synthpops.pop.Pop, or dict
**with_school_types (type) – If True, plot school size distributions by type, else plot overall school size distributions
**keys_to_exclude (str or list) – school types to exclude
**left (float) – Matplotlib.figure.subplot.left
**right (float) – Matplotlib.figure.subplot.right
**top (float) – Matplotlib.figure.subplot.top
**bottom (float) – Matplotlib.figure.subplot.bottom
**hspace (float) – Matplotlib.figure.subplot.hspace
**subplot_height (float) – height of subplot in inches
**subplot_width (float) – width of subplot in inches
**screen_height_factor (float) – fraction of the screen height to use for display
**location_text_y (float) – height to add location text to figure
**fontsize (float) – Matplotlib.figure.fontsize
**rotation (float) – rotation angle for xticklabels
**cmap (str or Matplotlib cmap) – colormap
**figname (str) – name to save figure to disk
**comparison (bool) – If True, plot comparison to the generated population
**do_show (bool) – If True, show the plot
**do_save (bool) – If True, save the plot to disk

Returns:

Matplotlib figure and axes.

Note

If using pop with type sp.people.Pop or dict, args must be supplied for the location parameters to get the expected distribution.

Example:

pars = {'n': 10e3, 'location'='seattle_metro', 'state_location'='Washington', 'country_location'='usa'}
pop = sp.Pop(**pars)
fig, ax = pop.plot_school_sizes_by_type()

popdict = pop.to_dict()
kwargs = pars.copy()
kwargs['datadir'] = sp.datadir
fig, ax = sp.plot_school_sizes(popdict, **kwargs)

plot_workplace_sizes(pop, **kwargs)[source]¶

Plot a comparison of the expected and generated workplace sizes for workplaces outside of schools or long term care facilities.

Parameters:

pop (pop object) – population, either synthpops.pop.Pop or dict
**left (float) – Matplotlib.figure.subplot.left
**right (float) – Matplotlib.figure.subplot.right
**top (float) – Matplotlib.figure.subplot.top
**bottom (float) – Matplotlib.figure.subplot.bottom
**color_1 (str) – color for expected data
**color_2 (str) – color for data from generated population
**fontsize (float) – Matplotlib.figure.fontsize
**figname (str) – name to save figure to disk
**comparison (bool) – If True, plot comparison to the generated population
**do_show (bool) – If True, show the plot
**do_save (bool) – If True, save the plot to disk

Returns:

Matplotlib figure and axes.

Note

If using pop with type dict, args must be supplied for the location parameter to get the expected rates. sp.people.People pop type not yet supported.

Example:

pars = {'n': 10e3, 'location':'seattle_metro', 'state_location':'Washington', 'country_location':'usa'}
pop = sp.Pop(**pars)
fig, ax = pop.plot_workplace_sizes()

popdict = pop.to_dict()
kwargs = pars.copy()
kwargs['datadir'] = sp.datadir
fig, ax = sp.plot_workplace_sizes(popdict, **kwargs)

plot_household_head_ages_by_size(pop, **kwargs)[source]¶

Plot a comparison of the expected and generated age distribution of the household heads by the household size, presented as matrices. The age distribution of household heads is binned to match the expected data.

Parameters:

pop (sp.Pop) – population
**figname (str) – name to save figure to disk
**figdir (str) – directory to save the plot if provided
**title_prefix (str) – used to prefix the title of the plot
**fontsize (float) – Matplotlib.figure.fontsize
**cmap (str or Matplotlib cmap) – colormap
**do_show (bool) – If True, show the plot
**do_save (bool) – If True, save the plot to disk

Returns:

Matplotlib figure and axes.

Example:

pars = {'n': 10e3, 'location': 'seattle_metro', 'state_location': 'Washington', 'country_location': 'usa'}
pop = sp.Pop(**pars)
fig, ax = plot_household_head_ages_by_size(pop)

kwargs = pars.copy()
kwargs['cmap'] = 'rocket'
fig, ax = plot_household_head_ages_by_size(pop, **kwargs)

plot_contact_counts(contact_counter, **kwargs)[source]¶

Plot the number of contacts by contact types as a histogram. The contact_counter is a dictionary with keys = people_types (default to school layer [‘sc_student’, ‘sc_teacher’, ‘sc_staff’]) and each value is a dictionary which stores the list of counts for each type of contact, for example [‘sc_teacher’, ‘sc_student’, ‘sc_staff’, ‘all_staff’, ‘all’].

Parameters:	contact_counter (dict) – A dictionary with people_types as keys and value as list of counts for each type of contacts *title_prefix (str) – optional title prefix for the figure figname (str) – name to save figure to disk fontsize (float*) – Matplotlib.figure.fontsize
Returns:	Matplotlib figure and axes of the histograms of contact distributions for the corresponding contact_counter.