poliosim.run module¶
Functions and classes for running multiple Poliosim runs.
- class MultiSim(sims=None, base_sim=None, quantiles=None, initialize=False, label=None, **kwargs)[source]¶
Bases:
sciris.sc_utils.prettyobj
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.
- Parameters
sims (Sim/list) – a single sim or a list of sims
base_sim (Sim) – the sim used for shared properties; if not supplied, the first of the sims provided
quantiles (dict) – the quantiles to use with reduce(), e.g. [0.1, 0.9] or {‘low : ‘0.1, ‘high’ : 0.9}
initialize (bool) – whether or not to initialize the sims (otherwise, initialize them during run)
kwargs (dict) – stored in run_args and passed to run()
- Returns
a MultiSim object
- Return type
msim
Examples:
sim = ps.Sim() # Create the sim msim = ps.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 = ps.Sim() # Create the sim msim = ps.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 = [ps.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 = ps.MultiSim(sims) # Convert to multisim msim.plot() # Plot as single sim
- init_sims(**kwargs)[source]¶
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.
- Parameters
kwargs (dict) – passed to multi_run()
- run(reduce=False, combine=False, **kwargs)[source]¶
Run the actual sims
- Parameters
reduce (bool) – whether or not to reduce after running (see reduce())
combine (bool) – whether or not to combine after running (see combine(), not compatible with reduce)
kwargs (dict) – passed to multi_run(); use run_args to pass arguments to sim.run()
- Returns
None (modifies MultiSim object in place)
Examples:
msim.run() msim.run(run_args=dict(until='2020-0601', restore_pars=False))
- shrink(**kwargs)[source]¶
Not to be confused with reduce(), this shrinks each sim in the msim; see sim.shrink() for more information.
- Parameters
kwargs (dict) – passed to sim.shrink() for each sim
- reduce(quantiles=None, output=False)[source]¶
Combine multiple sims into a single sim with scaled results
- mean(bounds=None, **kwargs)[source]¶
Alias for reduce(use_mean=True). See reduce() for full description.
- Parameters
bounds (float) – multiplier on the standard deviation for the upper and lower bounds (default, 2)
kwargs (dict) – passed to reduce()
- median(quantiles=None, **kwargs)[source]¶
Alias for reduce(use_mean=False). See reduce() for full description.
- Parameters
quantiles (list or dict) – upper and lower quantiles (default, 0.1 and 0.9)
kwargs (dict) – passed to reduce()
- combine(output=False)[source]¶
Combine multiple sims into a single sim with scaled results.
Example:
msim = cv.MultiSim(cv.Sim()) msim.run() msim.combine() msim.summarize()
- compare(t=None, sim_inds=None, output=False, do_plot=False, **kwargs)[source]¶
Create a dataframe compare sims at a single point in time.
- Parameters
t (int/str) – the day (or date) to do the comparison; default, the end
sim_inds (list) – list of integers of which sims to include (default: all)
output (bool) – whether or not to return the comparison as a dataframe
do_plot (bool) – whether or not to plot the comparison (see also plot_compare())
kwargs (dict) – passed to plot_compare()
- Returns
a dataframe comparison
- Return type
df (dataframe)
- 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)[source]¶
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
to_plot (list) – list or dict of which results to plot; see cv.get_default_plots() for structure
inds (list) – if not combined or reduced, the indices of the simulations to plot (if None, plot all)
plot_sims (bool) – whether to plot individual sims, even if combine() or reduce() has been used
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
max_sims (int) – maximum number of sims to use with color-by-sim; can be overridden by other options
colors (list) – if supplied, override default colors for color_by_sim
labels (list) – if supplied, override default labels for color_by_sim
alpha_range (list) – a 2-element list/tuple/array providing the range of alpha values to use to distinguish the lines
plot_args (dict) – passed to sim.plot()
show_args (dict) – passed to sim.plot()
kwargs (dict) – passed to sim.plot()
- Returns
Figure handle
- Return type
fig
Examples:
sim = ps.Sim() msim = ps.MultiSim(sim) msim.run() msim.plot() # Plots individual sims msim.reduce() msim.plot() # Plots the combined sim
- plot_result(key, colors=None, labels=None, *args, **kwargs)[source]¶
Convenience method for plotting – arguments passed to Sim.plot_result()
- plot_compare(t=- 1, sim_inds=None, log_scale=True, **kwargs)[source]¶
Plot a comparison between sims, using bars to show different values for each result.
- Parameters
t (int) – index of results, passed to compare()
sim_inds (list) – which sims to include, passed to compare()
log_scale (bool) – whether to plot with a logarithmic x-axis
kwargs (dict) – standard plotting arguments, see Sim.plot() for explanation
- Returns
the figure handle
- Return type
fig (figure)
- save(filename=None, keep_people=False, **kwargs)[source]¶
Save to disk as a gzipped pickle. Load with ps.load(filename) or ps.MultiSim.load(filename).
- Parameters
filename (str) – the name or path of the file to save to; if None, uses default
keep_people (bool) – whether or not to store the population in the Sim objects (NB, very large)
kwargs (dict) – passed to makefilepath()
- Returns
the validated absolute path to the saved file
- Return type
scenfile (str)
Example:
msim.save() # Saves to an .msim file
- static load(msimfile, *args, **kwargs)[source]¶
Load from disk from a gzipped pickle.
- Parameters
msimfile (str) – the name or path of the file to load from
kwargs – passed to ps.load()
- Returns
the loaded MultiSim object
- Return type
msim (MultiSim)
Example:
msim = ps.MultiSim.load('my-multisim.msim')
- static merge(*args, base=False)[source]¶
Convenience method for merging two MultiSim objects.
- Parameters
args (MultiSim) – the MultiSims to merge (either a list, or separate)
base (bool) – if True, make a new list of sims from the multisim’s two base sims; otherwise, merge the multisim’s lists of sims
- Returns
a new MultiSim object
- Return type
msim (MultiSim)
Examples:
mm1 = ps.MultiSim.merge(msim1, msim2, base=True) mm2 = ps.MultiSim.merge([m1, m2, m3, m4], base=False)
- split(inds=None, chunks=None)[source]¶
Convenience method for splitting one MultiSim into several. You can specify either individual indices of simulations to extract, via inds, or consecutive chunks of indices, via chunks. If this function is called on a merged MultiSim, the chunks can be retrieved automatically and no arguments are necessary.
- Parameters
inds (list) – a list of lists of indices, with each list turned into a MultiSim
chunks (int or list) – if an int, split the MultiSim into chunks of that length; if a list return chunks of that many sims
- Returns
A list of MultiSim objects
Examples:
m1 = ps.MultiSim(ps.Sim(label='sim1'), initialize=True) m2 = ps.MultiSim(ps.Sim(label='sim2'), initialize=True) m3 = ps.MultiSim.merge(m1, m2) m3.run() m1b, m2b = m3.split() msim = ps.MultiSim(ps.Sim(), n_runs=6) msim.run() m1, m2 = msim.split(inds=[[0,2,4], [1,3,5]]) mlist1 = msim.split(chunks=[2,4]) # Equivalent to inds=[[0,1], [2,3,4,5]] mlist2 = msim.split(chunks=3) # Equivalent to inds=[[0,1,2], [3,4,5]]
- 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)[source]¶
Convenience function to perform a single simulation run. Mostly used for parallelization, but can also be used directly.
- Parameters
sim (Sim) – the sim instance to be run
ind (int) – the index of this sim
reseed (bool) – whether or not to generate a fresh seed for each run
noise (float) – the amount of noise to add to each run
noisepar (str) – the name of the parameter to add noise to
keep_people (bool) – whether to keep the people after the sim run
run_args (dict) – arguments passed to sim.run()
sim_args (dict) – extra parameters to pass to the sim, e.g. ‘n_infected’
verbose (int) – detail to print
do_run (bool) – whether to actually run the sim (if not, just initialize it)
kwargs (dict) – also passed to the sim
- Returns
a single sim object with results
- Return type
sim (Sim)
Example:
import poliosim as ps sim = ps.Sim() # Create a default simulation sim = ps.single_run(sim) # Run it, equivalent(ish) to sim.run()
- multi_run(sim, n_runs=4, reseed=True, 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, **kwargs)[source]¶
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.
- Parameters
sim (Sim) – the sim instance to be run, or a list of sims.
n_runs (int) – the number of parallel runs
reseed (bool) – whether or not to generate a fresh seed for each run
noise (float) – the amount of noise to add to each run
noisepar (str) – the name of the parameter to add noise to
iterpars (dict) – any other parameters to iterate over the runs; see sc.parallelize() for syntax
combine (bool) – whether or not to combine all results into one sim, rather than return multiple sim objects
keep_people (bool) – whether to keep the people after the sim run (default false)
run_args (dict) – arguments passed to sim.run()
sim_args (dict) – extra parameters to pass to the sim
par_args (dict) – arguments passed to sc.parallelize()
do_run (bool) – whether to actually run the sim (if not, just initialize it)
parallel (bool) – whether to run in parallel using multiprocessing (else, just run in a loop)
n_cpus (int) – the number of CPUs to run on (if blank, set automatically; otherwise, passed to par_args)
verbose (int) – detail to print
kwargs (dict) – also passed to the sim
- Returns
If combine is True, a single sim object with the combined results from each sim. Otherwise, a list of sim objects (default).
Example:
import poliosim as ps sim = ps.Sim() sims = ps.multi_run(sim, n_runs=6, noise=0.2)