run
run
Functions and classes for running multiple Covasim runs.
cv.MultiSim is built on ss.MultiSim, and cv.Scenarios is built on cv.MultiSim. Both keep the v3 interface: e.g. after msim.reduce(), msim.results['cum_infections'] is a result with .values, .low, and .high; and after scens.run(), scens.results['cum_infections']['baseline']['best'] is the median of the baseline scenario.
Classes
| Name | Description |
|---|---|
| MultiSim | Class for running multiple copies of a simulation. The parameter n_runs |
| Scenarios | Class for running multiple sets of multiple simulations – e.g., scenarios. |
MultiSim
run.MultiSim(
sims=None,
base_sim=None,
label=None,
n_runs=4,
initialize=False,
inplace=False,
**kwargs,
)Class for running multiple copies of a simulation. The parameter n_runs controls how many copies of the simulation there will be, if a list of sims is not provided. This is the main class that’s used to run multiple versions of a simulation (e.g., with different random seeds).
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| sims (Sim/list) | a single sim or a list of sims | required | |
| base_sim (Sim) | the sim used for shared properties; if not supplied, the first of the sims provided | required | |
| label (str) | the name of the multisim | required | |
| n_runs (int) | if a single sim is provided, the number of replicates (default 4) | required | |
| initialize (bool) | whether or not to initialize the sims (otherwise, initialize them during run) | required | |
| inplace (bool) | whether to update the supplied sims with the results (default False, as in v3; Starsim’s default is True) | required | |
| kwargs (dict) | stored in run_args and passed to run(), e.g. noise=0.1 or keep_people=True | required |
Returns
| Name | Type | Description |
|---|---|---|
| msim | a MultiSim object |
MultiSims can be merged with cv.MultiSim.merge() and split with msim.split() (see ss.MultiSim).
Examples::
sim = cv.Sim() # Create the sim
msim = cv.MultiSim(sim, n_runs=5) # Create the multisim
msim.run() # Run them in parallel
msim.combine() # Combine into one sim
msim.plot() # Plot results
sim = cv.Sim() # Create the sim
msim = cv.MultiSim(sim, n_runs=11, noise=0.1, keep_people=True) # Set up a multisim with noise
msim.run() # Run
msim.reduce() # Compute statistics
msim.plot() # Plot
sims = [cv.Sim(beta=0.015*(1+0.02*i)) for i in range(5)] # Create sims
for sim in sims: sim.run() # Run sims in serial
msim = cv.MultiSim(sims) # Convert to multisim
msim.plot() # Plot as single simMethods
| Name | Description |
|---|---|
| combine | Combine multiple sims into a single sim with scaled results, e.g. to |
| compare | Create a dataframe compare sims at a single point in time. |
| init_sims | Initialize the sims, but don’t actually run them. Syntax is the same |
| load | Load from disk from a gzipped pickle. |
| plot | Plot all the sims – arguments passed to Sim.plot(). The |
| plot_compare | Plot a comparison between sims, using bars to show different values for |
| plot_result | Convenience method for plotting – arguments passed to sim.plot_result() |
| reduce | Combine multiple sims into a single sim statistically: by default, use |
| run | Run the actual sims. This mirrors ss.MultiSim.run(), but calls |
| save | Save to disk as a gzipped pickle. Load with cv.load(filename) or |
combine
run.MultiSim.combine(output=False)Combine multiple sims into a single sim with scaled results, e.g. to treat several smaller sims as one larger population. Count results are summed, and other results (e.g. prevalence) are averaged, weighted by each sim’s total population.
Note: unlike v3, the people are not combined; the combined sim has the people of the first sim.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| output | bool | whether to return the combined sim (otherwise, return the MultiSim) | False |
Example::
msim = cv.MultiSim(cv.Sim())
msim.run()
msim.combine()
msim.summarize()compare
run.MultiSim.compare(
t=None,
sim_inds=None,
output=False,
do_plot=False,
**kwargs,
)Create a dataframe compare sims at a single point in time.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| t (int/str) | the day (or date) to do the comparison; default, the end | required | |
| sim_inds (list) | list of integers of which sims to include (default: all) | required | |
| output (bool) | whether or not to return the comparison as a dataframe | required | |
| do_plot (bool) | whether or not to plot the comparison (see also plot_compare()) | required | |
| kwargs (dict) | passed to plot_compare() | required |
Returns
| Name | Type | Description |
|---|---|---|
| df | dataframe |
a dataframe comparison |
init_sims
run.MultiSim.init_sims(**kwargs)Initialize the sims, but don’t actually run them. Syntax is the same as MultiSim.run(). Note: in most cases you can just call run() directly, there is no need to call this separately.
This mirrors ss.MultiSim.init_sims(), but calls cv.multi_run(); keep the two in sync.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| kwargs | dict | passed to multi_run() | {} |
load
run.MultiSim.load(msimfile, *args, **kwargs)Load from disk from a gzipped pickle.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| msimfile | str | the name or path of the file to load from | required |
| kwargs | passed to cv.load() | {} |
Returns
| Name | Type | Description |
|---|---|---|
| msim | MultiSim | the loaded MultiSim object |
Example::
msim = cv.MultiSim.load('my-multisim.msim')plot
run.MultiSim.plot(
to_plot=None,
inds=None,
plot_sims=False,
color_by_sim=None,
max_sims=5,
colors=None,
labels=None,
alpha_range=None,
plot_args=None,
show_args=None,
**kwargs,
)Plot all the sims – arguments passed to Sim.plot(). The behavior depends on whether or not combine() or reduce() has been called. If so, this function by default plots only the combined/reduced sim (which you can override with plot_sims=True). Otherwise, it plots a separate line for each sim.
Note that this function is complex because it aims to capture the flexibility of both sim.plot() and scens.plot(). By default, if combine() or reduce() has been used, it will resemble sim.plot(); otherwise, it will resemble scens.plot(). This can be changed via color_by_sim, together with the other options.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| to_plot (list) | list or dict of which results to plot; see cv.get_default_plots() for structure | required | |
| inds (list) | if not combined or reduced, the indices of the simulations to plot (if None, plot all) | required | |
| plot_sims (bool) | whether to plot individual sims, even if combine() or reduce() has been used | required | |
| color_by_sim (bool) | if True, set colors based on the simulation type; otherwise, color by result type; True implies a scenario-style plotting, False implies sim-style plotting | required | |
| max_sims (int) | maximum number of sims to use with color-by-sim; can be overridden by other options | required | |
| colors (list) | if supplied, override default colors for color_by_sim | required | |
| labels (list) | if supplied, override default labels for color_by_sim | required | |
| alpha_range (list) | a 2-element list/tuple/array providing the range of alpha values to use to distinguish the lines | required | |
| plot_args (dict) | passed to sim.plot() | required | |
| show_args (dict) | passed to sim.plot() | required | |
| kwargs (dict) | passed to sim.plot() | required |
Returns
| Name | Type | Description |
|---|---|---|
| fig | Figure handle |
Examples::
sim = cv.Sim()
msim = cv.MultiSim(sim)
msim.run()
msim.plot() # Plots individual sims
msim.reduce()
msim.plot() # Plots the combined simplot_compare
run.MultiSim.plot_compare(t=-1, sim_inds=None, log_scale=True, **kwargs)Plot a comparison between sims, using bars to show different values for each result. For an explanation of other available arguments, see Sim.plot().
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| t (int) | index of results, passed to compare() | required | |
| sim_inds (list) | which sims to include, passed to compare() | required | |
| log_scale (bool) | whether to plot with a logarithmic x-axis | required | |
| kwargs (dict) | standard plotting arguments, see Sim.plot() for explanation | required |
Returns
| Name | Type | Description |
|---|---|---|
| fig | Figure handle |
plot_result
run.MultiSim.plot_result(key, colors=None, labels=None, *args, **kwargs)Convenience method for plotting – arguments passed to sim.plot_result()
reduce
run.MultiSim.reduce(*args, output=False, **kwargs)Combine multiple sims into a single sim statistically: by default, use the median value and the 10th and 90th percentiles for the lower and upper bounds. If use_mean=True, then use the mean and ±2 standard deviations for lower and upper bounds.
The reduced sim becomes the base sim, so e.g. msim.results['cum_infections'] (the same as msim.base_sim.results['cum_infections']) has .values, .low, and .high.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| quantiles | dict | the quantiles to use, e.g. [0.1, 0.9] or {‘low : ’0.1, ’high’ : 0.9} | required |
| use_mean | bool | whether to use the mean instead of the median | required |
| bounds | float | if use_mean=True, the multiplier on the standard deviation for upper and lower bounds (default 2) | required |
| output | bool | whether to return the “reduced” sim (otherwise, return the MultiSim) | False |
Example::
msim = cv.MultiSim(cv.Sim())
msim.run()
msim.reduce()
msim.summarize()run
run.MultiSim.run(reduce=False, combine=False, **kwargs)Run the actual sims. This mirrors ss.MultiSim.run(), but calls cv.multi_run() and has the v3 reduce and combine options; keep the two in sync.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| reduce | bool | whether or not to reduce after running (see reduce()) | False |
| combine | bool | whether or not to combine after running (see combine(), not compatible with reduce) | False |
| kwargs | dict | passed to multi_run(), e.g. n_runs, noise, keep_people, parallel; use run_args to pass arguments to sim.run() | {} |
Returns
| Name | Type | Description |
|---|---|---|
| msim | MultiSim | the MultiSim, modified in place |
Examples::
msim.run()
msim.run(run_args=dict(until='2020-06-01'))save
run.MultiSim.save(filename=None, keep_people=False, **kwargs)Save to disk as a gzipped pickle. Load with cv.load(filename) or cv.MultiSim.load(filename).
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| filename (str) | the name or path of the file to save to; if None, uses default | required | |
| keep_people (bool) | whether or not to store the population in the Sim objects (NB, very large) | required | |
| kwargs (dict) | passed to sc.makefilepath() |
required |
Returns
| Name | Type | Description |
|---|---|---|
| msimfile | str | the validated absolute path to the saved file |
Example::
msim.save() # Saves to an .msim fileScenarios
run.Scenarios(
sim=None,
metapars=None,
scenarios=None,
basepars=None,
scenfile=None,
label=None,
)Class for running multiple sets of multiple simulations – e.g., scenarios. Note that most users are recommended to use MultiSim rather than Scenarios, as it gives more control over run options. Scenarios should be used primarily for quick investigations. See the examples folder for example usage.
Each scenario is run as a cv.MultiSim, and the results are stored as scens.results[reskey][scenkey], with name, best (the median), low, and high entries. For the results by variant (e.g. cum_infections_by_variant), these have shape (time, variant), as in the sim, rather than (variant, time) as in v3.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| sim (Sim) | if supplied, use a pre-created simulation as the basis for the scenarios | required | |
| metapars (dict) | meta-parameters for the run, e.g. number of runs; see make_metapars() for structure | required | |
| scenarios (dict) | a dictionary defining the scenarios; see examples folder for examples; see below for baseline | required | |
| basepars (dict) | a dictionary of sim parameters to be used for the basis of the scenarios (not required if sim is provided) | required | |
| scenfile (str) | a filename for saving (defaults to the creation date) | required | |
| label (str) | the name of the scenarios | required |
Example::
scenarios = {'base': {'name':'Base','pars': {}}, 'beta': {'name':'Beta', 'pars': {'beta': 0.020}}}
scens = cv.Scenarios(scenarios=scenarios, basepars={'pop_size':5000})
scens.run()
scens.plot()Returns
| Name | Type | Description |
|---|---|---|
| scens | a Scenarios object |
Methods
| Name | Description |
|---|---|
| brief | Print a compact representation of the scenarios. See also scenarios.disp() |
| compare | Print out a comparison of each scenario. |
| disp | Display a verbose description of the scenarios. See also scenarios.summarize() |
| load | Load from disk from a gzipped pickle. |
| plot | Plot the results of a scenario. For an explanation of available arguments, |
| plot_result | Convenience method for plotting a single result; see Sim.plot() for other arguments |
| result_keys | The result keys of the scenarios; see sim.result_keys(). These are only |
| run | Run the specified scenarios. |
| save | Save to disk as a gzipped pickle. |
| summarize | Print a moderate length summary of the scenarios. See also scenarios.disp() |
| to_excel | Export results as XLSX |
| to_json | Export results as JSON. |
brief
run.Scenarios.brief(output=False)Print a compact representation of the scenarios. See also scenarios.disp() (detailed output) and scenarios.summarize() (medium length output).
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| output | bool | if true, return a string instead of printing output | False |
compare
run.Scenarios.compare(t=None, output=False)Print out a comparison of each scenario.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| t (int/str) | the day (or date) to do the comparison; default, the end | required | |
| output (bool) | if true, return the dataframe instead of printing output | required |
Example::
scenarios = {'base': {'name':'Base','pars': {}}, 'beta': {'name':'Beta', 'pars': {'beta': 0.020}}}
scens = cv.Scenarios(scenarios=scenarios, label='Example scenarios')
scens.run()
scens.compare(t=30) # Prints comparison for day 30disp
run.Scenarios.disp(output=False)Display a verbose description of the scenarios. See also scenarios.summarize() (medium length output) and scenarios.brief() (short output).
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| output | bool | if true, return a string instead of printing output | False |
load
run.Scenarios.load(scenfile, *args, **kwargs)Load from disk from a gzipped pickle.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| scenfile | str | the name or path of the file to load from | required |
| kwargs | passed to cv.load() | {} |
Returns
| Name | Type | Description |
|---|---|---|
| scens | Scenarios | the loaded scenarios object |
Example::
scens = cv.Scenarios.load('my-scenarios.scens')plot
run.Scenarios.plot(*args, **kwargs)Plot the results of a scenario. For an explanation of available arguments, see Sim.plot().
Returns
| Name | Type | Description |
|---|---|---|
| fig | Figure handle |
Example::
scens = cv.Scenarios()
scens.run()
scens.plot()plot_result
run.Scenarios.plot_result(key, *args, **kwargs)Convenience method for plotting a single result; see Sim.plot() for other arguments
result_keys
run.Scenarios.result_keys(which='all')The result keys of the scenarios; see sim.result_keys(). These are only available once the scenarios have been run.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| which | str | ‘main’, ‘variant’, or ‘all’ | 'all' |
run
run.Scenarios.run(debug=False, keep_people=False, verbose=None, **kwargs)Run the specified scenarios.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| debug (bool) | if True, runs a single run instead of multiple, which makes debugging easier | required | |
| keep_people (bool) | whether to keep the people in each sim after it has run | required | |
| verbose (int) | level of detail to print, passed to sim.run() | required | |
| kwargs (dict) | passed to MultiSim.run(), and thence to multi_run() | required |
Returns
| Name | Type | Description |
|---|---|---|
| scens | Scenarios | the Scenarios, modified in place |
save
run.Scenarios.save(scenfile=None, keep_sims=True, keep_people=False, **kwargs)Save to disk as a gzipped pickle.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| scenfile (str) | the name or path of the file to save to; if None, uses stored | required | |
| keep_sims (bool) | whether or not to store the actual Sim objects in the Scenarios object | required | |
| keep_people (bool) | whether or not to store the population in the Sim objects (NB, very large) | required | |
| kwargs (dict) | passed to makefilepath() | required |
Returns
| Name | Type | Description |
|---|---|---|
| scenfile | str | the validated absolute path to the saved file |
Example::
scens.save() # Saves to a .scens file with the date and time of creation by defaultsummarize
run.Scenarios.summarize(output=False)Print a moderate length summary of the scenarios. See also scenarios.disp() (detailed output) and scenarios.brief() (short output).
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| output | bool | if true, return a string instead of printing output | False |
to_excel
run.Scenarios.to_excel(filename=None)Export results as XLSX
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| filename | str | if None, return string; else, write to file | None |
Returns
| Name | Type | Description |
|---|---|---|
| An sc.Spreadsheet with an Excel file, or writes the file to disk |
to_json
run.Scenarios.to_json(
filename=None,
tostring=True,
indent=2,
verbose=False,
*args,
**kwargs,
)Export results as JSON.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| filename | str | if None, return string; else, write to file | None |
Returns
| Name | Type | Description |
|---|---|---|
| A unicode string containing a JSON representation of the results, | ||
| or writes the JSON file to disk |
Functions
| Name | Description |
|---|---|
| make_metapars | Create default metaparameters for a Scenarios run |
| multi_run | For running multiple runs in parallel. If the first argument is a list of sims, |
| parallel | A shortcut to cv.MultiSim(), allowing the quick running of multiple simulations |
| single_run | Convenience function to perform a single simulation run. Mostly used for |
make_metapars
run.make_metapars()Create default metaparameters for a Scenarios run
multi_run
run.multi_run(
sim,
n_runs=4,
reseed=None,
noise=0.0,
noisepar=None,
iterpars=None,
combine=False,
keep_people=None,
run_args=None,
sim_args=None,
par_args=None,
do_run=True,
parallel=True,
n_cpus=None,
verbose=None,
retry=None,
**kwargs,
)For running multiple runs in parallel. If the first argument is a list of sims, exactly these will be run and most other arguments will be ignored.
Note: this mirrors ss.multi_run(), but calls cv.single_run() (to handle noise and keep_people); keep the two in sync.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| sim (Sim) | the sim instance to be run, or a list of sims. | required | |
| n_runs (int) | the number of parallel runs | required | |
| reseed (bool) | whether or not to generate a fresh seed for each run (default: true for single, false for list of sims) | required | |
| noise (float) | the amount of noise to add to each run | required | |
| noisepar (str) | the name of the parameter to add noise to | required | |
| iterpars (dict) | any other parameters to iterate over the runs; see sc.parallelize() for syntax | required | |
| combine (bool) | whether or not to combine all results into one sim, rather than return multiple sim objects | required | |
| keep_people (bool) | whether to keep the people after the sim run (default false) | required | |
| run_args (dict) | arguments passed to sim.run() | required | |
| sim_args (dict) | extra parameters to pass to the sim | required | |
| par_args (dict) | arguments passed to sc.parallelize() | required | |
| do_run (bool) | whether to actually run the sim (if not, just initialize it) | required | |
| parallel (bool) | whether to run in parallel using multiprocessing (else, just run in a loop) | required | |
| n_cpus (int) | the number of CPUs to run on (if blank, set automatically; otherwise, passed to par_args) | required | |
| verbose (int) | detail to print | required | |
| retry (str) | not used (in v3, how to handle failed runs); accepted for compatibility | required | |
| kwargs (dict) | also passed to the sim | required |
Returns
| Name | Type | Description |
|---|---|---|
| If combine is True, a single sim object with the combined results from each sim. | ||
| Otherwise, a list of sim objects (default). |
Example::
import covasim as cv
sim = cv.Sim()
sims = cv.multi_run(sim, n_runs=6, noise=0.2)
sims = cv.multi_run(sim, iterpars={'beta':[0.01, 0.02, 0.03]}) # Run 3 sims with different betasparallel
run.parallel(*args, **kwargs)A shortcut to cv.MultiSim(), allowing the quick running of multiple simulations at once.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| args | list | The simulations to run | () |
| kwargs | dict | passed to multi_run() | {} |
Returns
| Name | Type | Description |
|---|---|---|
| A run MultiSim object. |
Examples::
s1 = cv.Sim(beta=0.01, label='Low')
s2 = cv.Sim(beta=0.02, label='High')
cv.parallel(s1, s2).plot()
msim = cv.parallel([s1, s2], keep_people=True)single_run
run.single_run(
sim,
ind=0,
reseed=True,
noise=0.0,
noisepar=None,
keep_people=False,
run_args=None,
sim_args=None,
verbose=None,
do_run=True,
**kwargs,
)Convenience function to perform a single simulation run. Mostly used for parallelization, but can also be used directly.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| sim (Sim) | the sim instance to be run | required | |
| ind (int) | the index of this sim | required | |
| reseed (bool) | whether or not to generate a fresh seed for each run | required | |
| noise (float) | the amount of noise to add to each run | required | |
| noisepar (str) | the name of the parameter to add noise to | required | |
| keep_people (bool) | whether to keep the people after the sim run | required | |
| run_args (dict) | arguments passed to sim.run() | required | |
| sim_args (dict) | extra parameters to pass to the sim, e.g. ‘beta’ | required | |
| verbose (int) | detail to print | required | |
| do_run (bool) | whether to actually run the sim (if not, just initialize it) | required | |
| kwargs (dict) | also passed to the sim | required |
Returns
| Name | Type | Description |
|---|---|---|
| sim | Sim | a single sim object with results |
Example::
import covasim as cv
sim = cv.Sim() # Create a default simulation
sim = cv.single_run(sim) # Run it, equivalent(ish) to sim.run()
sim = cv.single_run(cv.Sim(), beta=0.02) # Change a parameter, then run