rsvsim.sim module¶
Defines the Sim class, rsvsim’s core class.
-
class
rsvsim.sim.
Sim
(pars=None, datafile=None, datacols=None, label=None, simfile=None, popfile=None, load_pop=False, save_pop=False, **kwargs)[source]¶ Bases:
rsvsim.base.BaseSim
The Sim class handles the running of the simulation: the creation of the population and the dynamics of the epidemic. This class handles the mechanics of the actual simulation, while BaseSim takes care of housekeeping (saving, loading, exporting, etc.). Please see the BaseSim class for additional methods.
- 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
version (str) – if supplied, use default parameters from this version of RSVsim instead of the latest
kwargs (dict) – passed to make_pars()
Examples:
sim = cv.Sim() sim = cv.Sim(pop_size=10e3, datafile='my_data.xlsx')
-
load_data
(datafile=None, datacols=None, verbose=None, **kwargs)[source]¶ Load the data to calibrate against, if provided
-
initialize
(reset=False, **kwargs)[source]¶ 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
()[source]¶ 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)[source]¶ 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
()[source]¶ Handle layer parameters, since they need to be validated after the population creation, rather than before.
-
validate_pars
(validate_layers=True)[source]¶ 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
()[source]¶ 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)[source]¶ 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)[source]¶ 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_immunity
(create=False)[source]¶ Initialize immunity matrices and precompute immune waning for each genotype
-
step
()[source]¶ 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)[source]¶ 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. -1 = one-line output, 0 = no output, 0.1 = print every 10th day, 1 = print every day
- Returns
A pointer to the sim object (with results modified in-place)
-
compute_states
()[source]¶ Compute prevalence, incidence, and other states. 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. Also calculates the number of people alive, the number preinfectious, the number removed, and recalculates susceptibles to handle scaling.
-
compute_yield
()[source]¶ Compute test yield – number of positive tests divided by the total number of tests, also called test positivity rate. Relative yield is with respect to prevalence: i.e., how the yield compares to what the yield would be from choosing a person at random from the population.
-
compute_doubling
(window=3, max_doubling_time=30)[source]¶ 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)[source]¶ Effective reproduction number based on number of people each person infected.
- Parameters
method (str) – ‘daily’ 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
()[source]¶ 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)
-
compute_summary
(full=None, t=None, update=True, output=False, require_run=False)[source]¶ Compute the summary dict and string for the sim. Used internally; see sim.summarize() for the user version.
- 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)
update (bool) – whether to update the stored sim.summary
output (bool) – whether to return the summary
require_run (bool) – whether to raise an exception if simulations have not been run yet
-
summarize
(full=False, t=None, output=False)[source]¶ Print a medium-length summary of the simulation, drawing from the last time point in the simulation by default. Called by default at the end of a sim run. See also sim.disp() (detailed output) and sim.brief() (short output).
- 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)
output (bool) – whether to return the summary instead of printing it
Examples:
sim = cv.Sim(label='Example sim', verbose=0) # Set to run silently sim.run() # Run the sim sim.summarize() # Print medium-length summary of the sim sim.summarize(t=24, full=True) # Print a "slice" of all sim results on day 24
-
disp
(output=False)[source]¶ Display a verbose description of a sim. See also sim.summarize() (medium length output) and sim.brief() (short output).
- Parameters
output (bool) – if true, return a string instead of printing output
Example:
sim = cv.Sim(label='Example sim', verbose=0) # Set to run silently sim.run() # Run the sim sim.disp() # Displays detailed output
-
brief
(output=False)[source]¶ Print a one-line description of a sim. See also sim.disp() (detailed output) and sim.summarize() (medium length output). The symbol “⚙” is used to show infections, and “☠” is used to show deaths.
- Parameters
output (bool) – if true, return a string instead of printing output
Example:
sim = cv.Sim(label='Example sim', verbose=0) # Set to run silently sim.run() # Run the sim sim.brief() # Prints one-line output
-
compute_fit
(*args, **kwargs)[source]¶ Compute the fit between the model and the data. See cv.Fit() for more information.
- Parameters
args (list) – passed to cv.Fit()
kwargs (dict) – passed to cv.Fit()
- Returns
A Fit object
Example:
sim = cv.Sim(datafile='data.csv') sim.run() fit = sim.compute_fit() fit.plot()
-
calibrate
(calib_pars, **kwargs)[source]¶ Automatically calibrate the simulation, returning a Calibration object (a type of analyzer). See the documentation on that class for more information.
- Parameters
calib_pars (dict) – a dictionary of the parameters to calibrate of the format dict(key1=[best, low, high])
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 = sim.calibrate(calib_pars, n_trials=50) calib.plot()
-
make_age_histogram
(*args, output=True, **kwargs)[source]¶ 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
(*args, output=True, **kwargs)[source]¶ 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)[source]¶ Plot the results of a single simulation.
- Parameters
to_plot (dict) – Dict of results to plot; see get_default_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
date_args (dict) – Control how the x-axis (dates) are shown (see below for explanation)
show_args (dict) – Control which “extras” get shown: uncertainty bounds, data, interventions, ticks, and the legend
mpl_args (dict) – Dictionary of kwargs to be passed to Matplotlib; options are dpi, fontsize, and fontfamily
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
ax (axes) – Axes instance to plot into
kwargs (dict) – Parsed among figure, plot, scatter, date, and other settings (will raise an error if not recognized)
The optional dictionary “date_args” allows several settings for controlling how the x-axis of plots are shown, if this axis is dates. These options are:
as_dates
: whether to format them as dates (else, format them as days since the start)dateformat
: string format for the date (default %b-%d, e.g. Apr-04)interval
: the number of days between tick marksrotation
: whether to rotate labelsstart_day
: the first day to plotend_day
: the last day to plot
- Returns
Figure handle
- Return type
fig
Example:
sim = cv.Sim() sim.run() sim.plot()
New in version 2.1.0: argument passing, date_args, and mpl_args
-
plot_result
(key, *args, **kwargs)[source]¶ 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
- Returns
Figure handle
- Return type
fig
Example:
sim = cv.Sim().run() sim.plot_result('r_eff')
-
rsvsim.sim.
diff_sims
(sim1, sim2, skip_key_diffs=False, output=False, die=False)[source]¶ Compute the difference of the summaries of two simulations, and print any values which differ.
- Parameters
sim1 (sim/dict) – either a simulation object or the sim.summary dictionary
sim2 (sim/dict) – ditto
skip_key_diffs (bool) – whether to skip keys that don’t match between sims
output (bool) – whether to return the output as a string (otherwise print)
die (bool) – whether to raise an exception if the sims don’t match
require_run (bool) – require that the simulations have been run
Example:
s1 = cv.Sim(beta=0.01) s2 = cv.Sim(beta=0.02) s1.run() s2.run() cv.diff_sims(s1, s2)
-
exception
rsvsim.sim.
AlreadyRunError
[source]¶ 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.