covasim.sim module

Defines the Sim class, Covasim’s core class.

class covasim.sim.Sim(pars=None, datafile=None, datacols=None, label=None, simfile=None, popfile=None, load_pop=False, save_pop=False, **kwargs)

Bases: covasim.base.BaseSim

The Sim class handles the running of the simulation: the creation of the population and the dynamcis of the epidemic.

Parameters

  • pars (dict) – parameters to modify from their default values

  • datafile (str/df) – filename of (Excel, CSV) data file to load, or a pandas dataframe of the data

  • datacols (list) – list of column names of the data to load

  • label (str) – the name of the simulation (useful to distinguish in batch runs)

  • simfile (str) – the filename for this simulation, if it’s saved (default: creation date)

  • popfile (str) – the filename to load/save the population for this simulation

  • load_pop (bool) – whether to load the population from the named file

  • save_pop (bool) – whether to save the population to the named file

  • kwargs (dict) – passed to make_pars()

Examples:

sim = cv.Sim()
sim = cv.Sim(pop_size=10e3, datafile='my_data.xlsx')
update_pars(pars=None, create=False, **kwargs)

Ensure that metaparameters get used properly before being updated

set_metadata(simfile, label)

Set the metadata for the simulation – creation time and filename

load_data(datafile=None, datacols=None, verbose=None, **kwargs)

Load the data to calibrate against, if provided

initialize(reset=False, **kwargs)

Perform all initializations, including validating the parameters, setting the random number seed, creating the results structure, initializing the people, validating the layer parameters (which requires the people), and initializing the interventions.

Parameters

  • reset (bool) – whether or not to reset people even if they already exist

  • kwargs (dict) – passed to init_people

layer_keys()

Attempt to retrieve the current layer keys, in the following order: from the people object (for an initialized sim), from the popdict (for one in the process of being initialized), from the beta_layer parameter (for an uninitialized sim), or by assuming a default (if none of the above are available).

reset_layer_pars(layer_keys=None, force=False)

Reset the parameters to match the population.

Parameters

  • layer_keys (list) – override the default layer keys (use stored keys by default)

  • force (bool) – reset the parameters even if they already exist

validate_layer_pars()

Handle layer parameters, since they need to be validated after the population creation, rather than before.

validate_pars(validate_layers=True)

Some parameters can take multiple types; this makes them consistent.

Parameters

validate_layers (bool) – whether to validate layer parameters as well via validate_layer_pars() – usually yes, except during initialization

init_results()

Create the main results structure. We differentiate between flows, stocks, and cumulative results The prefix “new” is used for flow variables, i.e. counting new events (infections/deaths/recoveries) on each timestep The prefix “n” is used for stock variables, i.e. counting the total number in any given state (sus/inf/rec/etc) on any particular timestep The prefix “cum” is used for cumulative variables, i.e. counting the total number that have ever been in a given state at some point in the sim Note that, by definition, n_dead is the same as cum_deaths and n_recovered is the same as cum_recoveries, so we only define the cumulative versions

load_population(popfile=None, **kwargs)

Load the population dictionary from file – typically done automatically as part of sim.initialize(). Supports loading either saved population dictionaries (popdicts, file ending .pop by convention), or ready-to-go People objects (file ending .ppl by convention). Either object an also be supplied directly. Once a population file is loaded, it is removed from the Sim object.

Parameters

  • popfile (str or obj) – if a string, name of the file; otherwise, the popdict or People object to load

  • kwargs (dict) – passed to sc.makefilepath()

init_people(save_pop=False, load_pop=False, popfile=None, reset=False, verbose=None, **kwargs)

Create the people.

Parameters

  • save_pop (bool) – if true, save the population dictionary to popfile

  • load_pop (bool) – if true, load the population dictionary from popfile

  • popfile (str) – filename to load/save the population

  • reset (bool) – whether to regenerate the people even if they already exist

  • verbose (int) – detail to print

  • kwargs (dict) – passed to cv.make_people()

init_interventions()

Initialize the interventions

init_analyzers()

Initialize the analyzers

rescale()

Dynamically rescale the population – used during step()

step()

Step the simulation forward in time. Usually, the user would use sim.run() rather than calling sim.step() directly.

run(do_plot=False, until=None, restore_pars=True, reset_seed=True, verbose=None, **kwargs)

Run the simulation.

Parameters

  • do_plot (bool) – whether to plot

  • until (int/str) – day or date to run until

  • restore_pars (bool) – whether to make a copy of the parameters before the run and restore it after, so runs are repeatable

  • reset_seed (bool) – whether to reset the random number stream immediately before run

  • verbose (float) – level of detail to print, e.g. 0 = no output, 0.2 = print every 5th day, 1 = print every day

  • kwargs (dict) – passed to sim.plot()

Returns

the results object (also modifies in-place)

Return type

results (dict)

finalize(verbose=None, restore_pars=True)

Compute final results

compute_results(verbose=None)

Perform final calculations on the results

compute_prev_inci()

Compute prevalence and incidence. Prevalence is the current number of infected people divided by the number of people who are alive. Incidence is the number of new infections per day divided by the susceptible population.

compute_yield()

Compute test yield – number of positive tests divided by the total number of tests

compute_doubling(window=3, max_doubling_time=30)

Calculate doubling time using exponential approximation – a more detailed approach is in utils.py. Compares infections at time t to infections at time t-window, and uses that to compute the doubling time. For example, if there are 100 cumulative infections on day 12 and 200 infections on day 19, doubling time is 7 days.

Parameters

  • window (float) – the size of the window used (larger values are more accurate but less precise)

  • max_doubling_time (float) – doubling time could be infinite, so this places a bound on it

Returns

the doubling time results array

Return type

doubling_time (array)

compute_r_eff(method='daily', smoothing=2, window=7)

Effective reproduction number based on number of people each person infected.

Parameters

  • method (str) – ‘instant’ uses daily infections, ‘infectious’ counts from the date infectious, ‘outcome’ counts from the date recovered/dead

  • smoothing (int) – the number of steps to smooth over for the ‘daily’ method

  • window (int) – the size of the window used for ‘infectious’ and ‘outcome’ calculations (larger values are more accurate but less precise)

Returns

the r_eff results array

Return type

r_eff (array)

compute_gen_time()

Calculate the generation time (or serial interval). There are two ways to do this calculation. The ‘true’ interval (exposure time to exposure time) or ‘clinical’ (symptom onset to symptom onset).

Returns

the generation time results

Return type

gen_time (dict)

summarize(full=False, t=None, verbose=None, output=False, update=True)

Print a summary of the simulation, drawing from the last time point in the simulation.

Parameters

  • full (bool) – whether or not to print all results (by default, only cumulative)

  • t (int/str) – day or date to compute summary for (by default, the last point)

  • verbose (bool) – whether to print to screen (default: same as sim)

  • output (bool) – whether to return the summary

  • update (bool) – whether to update the summary stored in the sim (sim.summary)

brief(output=False)

Return a one-line description of a sim

compute_fit(output=True, *args, **kwargs)

Compute the fit between the model and the data. See cv.Fit() for more information.

Parameters

  • output (bool) – whether or not to return the TransTree; if not, store in sim.results

  • args (list) – passed to cv.Fit()

  • kwargs (dict) – passed to cv.Fit()

Example:

sim = cv.Sim(datafile=data.csv)
sim.run()
fit = sim.compute_fit()
fit.plot()
make_age_histogram(output=True, *args, **kwargs)

Calculate the age histograms of infections, deaths, diagnoses, etc. See cv.age_histogram() for more information. This can be used alternatively to supplying the age histogram as an analyzer to the sim. If used this way, it can only record the final time point since the states of each person are not saved during the sim.

Parameters

  • output (bool) – whether or not to return the age histogram; if not, store in sim.results

  • args (list) – passed to cv.age_histogram()

  • kwargs (dict) – passed to cv.age_histogram()

Example:

sim = cv.Sim()
sim.run()
agehist = sim.make_age_histogram()
agehist.plot()
make_transtree(output=True, *args, **kwargs)

Create a TransTree (transmission tree) object, for analyzing the pattern of transmissions in the simulation. See cv.TransTree() for more information.

Parameters

  • output (bool) – whether or not to return the TransTree; if not, store in sim.results

  • args (list) – passed to cv.TransTree()

  • kwargs (dict) – passed to cv.TransTree()

Example:

sim = cv.Sim()
sim.run()
tt = sim.make_transtree()
plot(*args, **kwargs)

Plot the results of a single simulation.

Parameters

  • to_plot (dict) – Dict of results to plot; see get_sim_plots() for structure

  • do_save (bool) – Whether or not to save the figure

  • fig_path (str) – Path to save the figure

  • fig_args (dict) – Dictionary of kwargs to be passed to pl.figure()

  • plot_args (dict) – Dictionary of kwargs to be passed to pl.plot()

  • scatter_args (dict) – Dictionary of kwargs to be passed to pl.scatter()

  • axis_args (dict) – Dictionary of kwargs to be passed to pl.subplots_adjust()

  • legend_args (dict) – Dictionary of kwargs to be passed to pl.legend(); if show_legend=False, do not show

  • show_args (dict) – Control which “extras” get shown: uncertainty bounds, data, interventions, ticks, and the legend

  • as_dates (bool) – Whether to plot the x-axis as dates or time points

  • dateformat (str) – Date string format, e.g. ‘%B %d’

  • interval (int) – Interval between tick marks

  • n_cols (int) – Number of columns of subpanels to use for subplot

  • font_size (int) – Size of the font

  • font_family (str) – Font face

  • grid (bool) – Whether or not to plot gridlines

  • commaticks (bool) – Plot y-axis with commas rather than scientific notation

  • setylim (bool) – Reset the y limit to start at 0

  • log_scale (bool) – Whether or not to plot the y-axis with a log scale; if a list, panels to show as log

  • do_show (bool) – Whether or not to show the figure

  • colors (dict) – Custom color for each result, must be a dictionary with one entry per result key in to_plot

  • sep_figs (bool) – Whether to show separate figures for different results instead of subplots

  • fig (fig) – Handle of existing figure to plot into

Returns

Figure handle

Return type

fig

Example:

sim = cv.Sim()
sim.run()
sim.plot()
plot_result(key, *args, **kwargs)

Simple method to plot a single result. Useful for results that aren’t standard outputs. See sim.plot() for explanation of other arguments.

Parameters

key (str) – the key of the result to plot

Examples:

sim.plot_result('r_eff')
exception covasim.sim.AlreadyRunError

Bases: RuntimeError

This error is raised if a simulation is run in such a way that no timesteps will be taken. This error is a distinct type so that it can be safely caught and ignored if required, but it is anticipated that most of the time, calling sim.run() and not taking any timesteps, would be an inadvertent error.