covasim.analysis module

Additional analysis functions that are not part of the core Covasim workflow, but which are useful for particular investigations.

class Analyzer(label=None)

Bases: sciris.sc_utils.prettyobj

Base class for analyzers. Based on the Intervention class. Analyzers are used to provide more detailed information about a simulation than is available by default – for example, pulling states out of sim.people on a particular timestep before it gets updated in the next timestep.

To retrieve a particular analyzer from a sim, use sim.get_analyzer().

Parameters:label (str) – a label for the Analyzer (used for ease of identification)

initialize(sim=None)

Initialize the analyzer, e.g. convert date strings to integers.

finalize(sim=None)

Finalize analyzer

This method is run once as part of sim.finalize() enabling the analyzer to perform any final operations after the simulation is complete (e.g. rescaling)

apply(sim)

Apply analyzer at each time point. The analyzer has full access to the sim object, and typically stores data/results in itself. This is the core method which each analyzer object needs to implement.

Parameters:sim – the Sim instance

shrink(in_place=False)

Remove any excess stored data from the intervention; for use with sim.shrink().

Parameters:in_place (bool) – whether to shrink the intervention (else shrink a copy)

to_json()

Return JSON-compatible representation

Custom classes can’t be directly represented in JSON. This method is a one-way export to produce a JSON-compatible representation of the intervention. This method will attempt to JSONify each attribute of the intervention, skipping any that fail.

Returns:JSON-serializable representation

class snapshot(days, *args, die=True, **kwargs)

Bases: covasim.analysis.Analyzer

Analyzer that takes a “snapshot” of the sim.people array at specified points in time, and saves them to itself. To retrieve them, you can either access the dictionary directly, or use the get() method.

Parameters:

• days (list) – list of ints/strings/date objects, the days on which to take the snapshot
• args (list) – additional day(s)
• die (bool) – whether or not to raise an exception if a date is not found (default true)
• kwargs (dict) – passed to Analyzer()

Example:

sim = cv.Sim(analyzers=cv.snapshot('2020-04-04', '2020-04-14'))
sim.run()
snapshot = sim['analyzers'][0]
people = snapshot.snapshots[0]            # Option 1
people = snapshot.snapshots['2020-04-04'] # Option 2
people = snapshot.get('2020-04-14')       # Option 3
people = snapshot.get(34)                 # Option 4
people = snapshot.get()                   # Option 5

initialize(sim)

apply(sim)

finalize(sim)

get(key=None)

Retrieve a snapshot from the given key (int, str, or date)

class age_histogram(days=None, states=None, edges=None, datafile=None, sim=None, die=True, **kwargs)

Bases: covasim.analysis.Analyzer

Calculate statistics across age bins, including histogram plotting functionality.

Parameters:

• days (list) – list of ints/strings/date objects, the days on which to calculate the histograms (default: last day)
• states (list) – which states of people to record (default: exposed, tested, diagnosed, dead)
• edges (list) – edges of age bins to use (default: 10 year bins from 0 to 100)
• datafile (str) – the name of the data file to load in for comparison, or a dataframe of data (optional)
• sim (Sim) – only used if the analyzer is being used after a sim has already been run
• die (bool) – whether to raise an exception if dates are not found (default true)
• kwargs (dict) – passed to Analyzer()

Examples:

sim = cv.Sim(analyzers=cv.age_histogram())
sim.run()

agehist = sim.get_analyzer()
agehist = cv.age_histogram(sim=sim) # Alternate method
agehist.plot()

from_sim(sim)

Create an age histogram from an already run sim

initialize(sim)

apply(sim)

finalize(sim)

get(key=None)

Retrieve a specific histogram from the given key (int, str, or date)

compute_windows()

Convert cumulative histograms to windows

plot(windows=False, width=0.8, color='#F8A493', fig_args=None, axis_args=None, data_args=None, **kwargs)

Simple method for plotting the histograms.

Parameters:

• windows (bool) – whether to plot windows instead of cumulative counts
• width (float) – width of bars
• color (hex or rgb) – the color of the bars
• fig_args (dict) – passed to pl.figure()
• axis_args (dict) – passed to pl.subplots_adjust()
• data_args (dict) – ‘width’, ‘color’, and ‘offset’ arguments for the data
• kwargs (dict) – passed to cv.options.with_style(); see that function for choices

class daily_age_stats(states=None, edges=None, **kwargs)

Bases: covasim.analysis.Analyzer

Calculate daily counts by age, saving for each day of the simulation. Can plot either time series by age or a histogram over all time.

Parameters:

• states (list) – which states of people to record (default: [‘diagnoses’, ‘deaths’, ‘tests’, ‘severe’])
• edges (list) – edges of age bins to use (default: 10 year bins from 0 to 100)
• kwargs (dict) – passed to Analyzer()

Examples:

sim = cv.Sim(analyzers=cv.daily_age_stats())
sim = cv.Sim(pars, analyzers=daily_age)
sim.run()
daily_age = sim.get_analyzer()
daily_age.plot()
daily_age.plot(total=True)

initialize(sim)

apply(sim)

to_df()

Create dataframe totals for each day

to_total_df()

Create dataframe totals across days

plot(total=False, do_show=None, fig_args=None, axis_args=None, plot_args=None, dateformat=None, width=0.8, color='#F8A493', **kwargs)

Plot the results.

Parameters:

• total (bool) – whether to plot the total histograms rather than time series
• do_show (bool) – whether to show the plot
• fig_args (dict) – passed to pl.figure()
• axis_args (dict) – passed to pl.subplots_adjust()
• plot_args (dict) – passed to pl.plot()
• dateformat (str) – the format to use for the x-axes (only used for time series)
• width (float) – width of bars (only used for histograms)
• color (hex/rgb) – the color of the bars (only used for histograms)
• kwargs (dict) – passed to cv.options.with_style()

class daily_stats(days=None, verbose=True, reporter=None, save_inds=False, **kwargs)

Bases: covasim.analysis.Analyzer

Print out daily statistics about the simulation. Note that this analyzer takes a considerable amount of time, so should be used primarily for debugging, not in production code. To keep the intervention but toggle it off, pass an empty list of days.

To show the stats for a day after a run has finished, use e.g. daily_stats.report('2020-04-04').

Parameters:

• days (list) – days on which to print out statistics (if None, assume all)
• verbose (bool) – whether to print on each timestep
• reporter (func) – if supplied, a custom parser of the stats object into a report (see make_report() function for syntax)
• save_inds (bool) – whether to save the indices of every infection at every timestep (also recoverable from the infection log)

Example:

sim = cv.Sim(analyzers=cv.daily_stats())
sim.run()
sim['analyzers'][0].plot()

initialize(sim)

intersect(*args)

Compute the intersection between arrays of indices, handling either keys to precomputed indices or lists of indices. With two array inputs, simply performs np.intersect1d(arr1, arr2).

apply(sim)

report(day=None)

Print out one or all reports – take a date string or an int

make_report(sim, stats, show_empty='count')

Turn the statistics into a report

transpose(keys=None)

Transpose the data from a list-of-dicts-of-dicts to a dict-of-dicts-of-lists

plot(fig_args=None, axis_args=None, plot_args=None, do_show=None, **kwargs)

Plot the daily statistics recorded. Some overlap with e.g. sim.plot(to_plot='overview').

Parameters:

• fig_args (dict) – passed to pl.figure()
• axis_args (dict) – passed to pl.subplots_adjust()
• plot_args (dict) – passed to pl.plot()
• do_show (bool) – whether to show the plot
• kwargs (dict) – passed to cv.options.with_style()

class nab_histogram(days=None, edges=None, **kwargs)

Bases: covasim.analysis.Analyzer

Store histogram of log_{10}(NAb) distribution

Parameters:

• days (list) – days on which calculate the NAb histogram (if None, assume last day)
• edges (list) – log10 bin edges for histogram

Example:

sim = cv.Sim(analyzers=cv.nab_histogram())
sim.run()
sim.get_analyzer().plot()

New in version 3.1.0.

initialize(sim)

apply(sim)

plot(fig_args=None, axis_args=None, plot_args=None, do_show=None, **kwargs)

Plot the results

Parameters:

• fig_args (dict) – passed to pl.figure()
• axis_args (dict) – passed to pl.subplots_adjust()
• plot_args (dict) – passed to pl.plot()
• do_show (bool) – whether to show the plot
• kwargs (dict) – passed to cv.options.with_style()

class Fit(sim, weights=None, keys=None, custom=None, compute=True, verbose=False, die=True, label=None, **kwargs)

Bases: covasim.analysis.Analyzer

A class for calculating the fit between the model and the data. Note the following terminology is used here:

• fit: nonspecific term for how well the model matches the data
• difference: the absolute numerical differences between the model and the data (one time series per result)
• goodness-of-fit: the result of passing the difference through a statistical function, such as mean squared error
• loss: the goodness-of-fit for each result multiplied by user-specified weights (one time series per result)
• mismatches: the sum of all the losses (a single scalar value per time series)
• mismatch: the sum of the mismatches – this is the value to be minimized during calibration

Parameters:

• sim (Sim) – the sim object
• weights (dict) – the relative weight to place on each result (by default: 10 for deaths, 5 for diagnoses, 1 for everything else)
• keys (list) – the keys to use in the calculation
• custom (dict) – a custom dictionary of additional data to fit; format is e.g. {‘my_output’:{‘data’:[1,2,3], ‘sim’:[1,2,4], ‘weights’:2.0}}
• compute (bool) – whether to compute the mismatch immediately
• verbose (bool) – detail to print
• die (bool) – whether to raise an exception if no data are supplied
• label (str) – the label for the analyzer
• kwargs (dict) – passed to cv.compute_gof() – see this function for more detail on goodness-of-fit calculation options

Example:

sim = cv.Sim(datafile='my-data-file.csv')
sim.run()
fit = sim.compute_fit()
fit.plot()

compute()

Perform all required computations

reconcile_inputs()

Find matching keys and indices between the model and the data

compute_diffs(absolute=False)

Find the differences between the sim and the data

compute_gofs(**kwargs)

Compute the goodness-of-fit

compute_losses()

Compute the weighted goodness-of-fit

compute_mismatch(use_median=False)

Compute the final mismatch

summarize()

Print out results from the fit

plot(keys=None, width=0.8, fig_args=None, axis_args=None, plot_args=None, date_args=None, do_show=None, fig=None, **kwargs)

Plot the fit of the model to the data. For each result, plot the data and the model; the difference; and the loss (weighted difference). Also plots the loss as a function of time.

Parameters:

• keys (list) – which keys to plot (default, all)
• width (float) – bar width
• fig_args (dict) – passed to pl.figure()
• axis_args (dict) – passed to pl.subplots_adjust()
• plot_args (dict) – passed to pl.plot()
• date_args (dict) – passed to cv.plotting.reset_ticks() (handle date format, rotation, etc.)
• do_show (bool) – whether to show the plot
• fig (fig) – if supplied, use this figure to plot in
• kwargs (dict) – passed to cv.options.with_style()

Returns:

Figure object

class Calibration(sim, calib_pars=None, fit_args=None, custom_fn=None, par_samplers=None, n_trials=None, n_workers=None, total_trials=None, name=None, db_name=None, keep_db=None, storage=None, label=None, die=False, verbose=True)

Bases: covasim.analysis.Analyzer

A class to handle calibration of Covasim simulations. Uses the Optuna hyperparameter optimization library (optuna.org), which must be installed separately (via pip install optuna).

Note: running a calibration does not guarantee a good fit! You must ensure that you run for a sufficient number of iterations, have enough free parameters, and that the parameters have wide enough bounds. Please see the tutorial on calibration for more information.

Parameters:

• sim (Sim) – the simulation to calibrate
• calib_pars (dict) – a dictionary of the parameters to calibrate of the format dict(key1=[best, low, high])
• fit_args (dict) – a dictionary of options that are passed to sim.compute_fit() to calculate the goodness-of-fit
• par_samplers (dict) – an optional mapping from parameters to the Optuna sampler to use for choosing new points for each; by default, suggest_float
• custom_fn (func) – a custom function for modifying the simulation; receives the sim and calib_pars as inputs, should return the modified sim
• n_trials (int) – the number of trials per worker
• n_workers (int) – the number of parallel workers (default: maximum
• total_trials (int) – if n_trials is not supplied, calculate by dividing this number by n_workers)
• name (str) – the name of the database (default: ‘covasim_calibration’)
• db_name (str) – the name of the database file (default: ‘covasim_calibration.db’)
• keep_db (bool) – whether to keep the database after calibration (default: false)
• storage (str) – the location of the database (default: sqlite)
• label (str) – a label for this calibration object
• die (bool) – whether to stop if an exception is encountered (default: false)
• verbose (bool) – whether to print details of the calibration
• kwargs (dict) – passed to cv.Calibration()

Returns:

A Calibration object

Example:

sim = cv.Sim(datafile='data.csv')
calib_pars = dict(beta=[0.015, 0.010, 0.020])
calib = cv.Calibration(sim, calib_pars, total_trials=100)
calib.calibrate()
calib.plot()

New in version 3.0.3.

run_sim(calib_pars, label=None, return_sim=False)

Create and run a simulation

run_trial(trial)

Define the objective for Optuna

worker()

Run a single worker

run_workers()

Run multiple workers in parallel

remove_db()

Remove the database file if keep_db is false and the path exists.

New in version 3.1.0.

make_study()

Make a study, deleting one if it already exists

calibrate(calib_pars=None, verbose=True, **kwargs)

Actually perform calibration.

Parameters:

• calib_pars (dict) – if supplied, overwrite stored calib_pars
• verbose (bool) – whether to print output from each trial
• kwargs (dict) – if supplied, overwrite stored run_args (n_trials, n_workers, etc.)

summarize()

Print out results from the calibration

parse_study()

Parse the study into a data frame – called automatically

to_json(filename=None)

Convert the data to JSON.

New in version 3.1.1.

plot_sims(**kwargs)

Plot sims, before and after calibration.

New in version 3.1.1: renamed from plot() to plot_sims().

plot_trend(best_thresh=2)

Plot the trend in best mismatch over time.

New in version 3.1.1.

plot_all()

Plot every point in the calibration. Warning, very slow for more than a few hundred trials.

New in version 3.1.1.

plot_best(best_thresh=2)

Plot only the points with lowest mismatch. New in version 3.1.1.

plot_stride(npts=200)

Plot a fixed number of points in order across the results.

New in version 3.1.1.

class TransTree(sim, to_networkx=False, **kwargs)

Bases: covasim.analysis.Analyzer

A class for holding a transmission tree. There are several different representations of the transmission tree: “infection_log” is copied from the people object and is the simplest representation. “detailed h” includes additional attributes about the source and target. If NetworkX is installed (required for most methods), “graph” includes an NX representation of the transmission tree.

Parameters:

• sim (Sim) – the sim object
• to_networkx (bool) – whether to convert the graph to a NetworkX object

Example:

sim = cv.Sim().run()
sim.run()
tt = sim.make_transtree()
tt.plot()
tt.plot_histograms()

New in version 2.1.0: tt.detailed is a dataframe rather than a list of dictionaries; for the latter, use tt.detailed.to_dict('records').

day(day=None, which=None)

Convenience function for converting an input to an integer day

count_targets(start_day=None, end_day=None)

Count the number of targets each infected person has. If start and/or end days are given, it will only count the targets of people who got infected between those dates (it does not, however, filter on the date the target got infected).

Parameters:

• start_day (int/str) – the day on which to start counting people who got infected
• end_day (int/str) – the day on which to stop counting people who got infected

count_transmissions()

Iterable over edges corresponding to transmission events

This excludes edges corresponding to seeded infections without a source

make_detailed(people, reset=False)

Construct a detailed transmission tree, with additional information for each person

r0(recovered_only=False)

Return average number of transmissions per person

This doesn’t include seed transmissions. By default, it also doesn’t adjust for length of infection (e.g. people infected towards the end of the simulation will have fewer transmissions because their infection may extend past the end of the simulation, these people are not included). If ‘recovered_only=True’ then the downstream transmissions will only be included for people that recover before the end of the simulation, thus ensuring they all had the same amount of time to transmit.

plot(fig_args=None, plot_args=None, do_show=None, fig=None)

Plot the transmission tree.

Parameters:

• fig_args (dict) – passed to pl.figure()
• plot_args (dict) – passed to pl.plot()
• do_show (bool) – whether to show the plot
• fig (fig) – if supplied, use this figure

animate(*args, **kwargs)

Animate the transmission tree.

Parameters:

• animate (bool) – whether to animate the plot (otherwise, show when finished)
• verbose (bool) – print out progress of each frame
• markersize (int) – size of the markers
• sus_color (list) – color for susceptibles
• fig_args (dict) – arguments passed to pl.figure()
• axis_args (dict) – arguments passed to pl.subplots_adjust()
• plot_args (dict) – arguments passed to pl.plot()
• delay (float) – delay between frames in seconds
• colors (list) – color of each person
• cmap (str) – colormap for each person (if colors is not supplied)
• fig (fig) – if supplied, use this figure

Returns:

the figure object

Return type:

fig

plot_histograms(start_day=None, end_day=None, bins=None, width=0.8, fig_args=None, fig=None)

Plots a histogram of the number of transmissions.

Parameters:

• start_day (int/str) – the day on which to start counting people who got infected
• end_day (int/str) – the day on which to stop counting people who got infected
• bins (list) – bin edges to use for the histogram
• width (float) – width of bars
• fig_args (dict) – passed to pl.figure()
• fig (fig) – if supplied, use this figure