hpvsim.run module¶

Functions and classes for running multiple HPVsim runs.

make_metapars()[source]¶: Create default metaparameters for a Scenarios run

class MultiSim(sims=None, base_sim=None, label=None, initialize=False, **kwargs)[source]¶

Bases: FlexPretty

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:

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
label (str) – the name of the multisim
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 = hpv.Sim() # Create the sim
msim = hpv.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 = hpv.Sim() # Create the sim
msim = hpv.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 = [hpv.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 = hpv.MultiSim(sims) # Convert to multisim
msim.plot() # Plot as single sim

result_keys()[source]¶: Attempt to retrieve the results keys from the base 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

reset()[source]¶: Undo a combine() or reduce() by resetting the base sim, which, and results

reduce(quantiles=None, use_mean=False, bounds=None, output=False)[source]¶

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.

Parameters:

quantiles (dict) – the quantiles to use, e.g. [0.1, 0.9] or {‘low : ‘0.1, ‘high’ : 0.9}
use_mean (bool) – whether to use the mean instead of the median
bounds (float) – if use_mean=True, the multiplier on the standard deviation for upper and lower bounds (default 2)
output (bool) – whether to return the “reduced” sim (in any case, modify the multisim in-place)

Example:

msim = hpv.MultiSim(hpv.Sim())
msim.run()
msim.reduce()
msim.summarize()

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 = hpv.MultiSim(hpv.Sim())
msim.run()
msim.combine()
msim.summarize()

compare(t=None, sim_inds=None, output=False, do_plot=False, show_match=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())
show_match (bool) – whether to include a column for whether all sims match
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 hpv.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 = hpv.Sim()
msim = hpv.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. For an explanation of other available arguments, see Sim.plot().

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:

Figure handle

Return type:

fig

save(filename=None, keep_people=False, **kwargs)[source]¶

Save to disk as a gzipped pickle. Load with hpv.load(filename) or hpv.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 sc.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 hpv.load()

Returns:

the loaded MultiSim object

Return type:

msim (MultiSim)

Example:

msim = hpv.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 = hpv.MultiSim.merge(msim1, msim2, base=True) mm2 = hpv.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 that many chunks; if a list return chunks of that many sims

Returns:

A list of MultiSim objects

Examples:

m1 = hpv.MultiSim(hpv.Sim(label='sim1'), initialize=True)
m2 = hpv.MultiSim(hpv.Sim(label='sim2'), initialize=True)
m3 = hpv.MultiSim.merge(m1, m2)
m3.run()
m1b, m2b = m3.split()

msim = hpv.MultiSim(hpv.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=2) # Equivalent to inds=[[0,1,2], [3,4,5]]

disp(output=False)[source]¶

Display a verbose description of a multisim. See also multisim.summarize() (medium length output) and multisim.brief() (short output).

Parameters:: output (bool) – if true, return a string instead of printing output

Example:

msim = hpv.MultiSim(hpv.Sim(verbose=0), label='Example multisim')
msim.run()
msim.disp() # Displays detailed output

summarize(output=False)[source]¶

Print a moderate length summary of the MultiSim. See also multisim.disp() (detailed output) and multisim.brief() (short output).

Parameters:: output (bool) – if true, return a string instead of printing output

Example:

msim = hpv.MultiSim(hpv.Sim(verbose=0), label='Example multisim')
msim.run()
msim.summarize() # Prints moderate length output

brief(output=False)[source]¶

Print a compact representation of the multisim. See also multisim.disp() (detailed output) and multisim.summarize() (medium length output).

Parameters:: output (bool) – if true, return a string instead of printing output

Example:

msim = hpv.MultiSim(hpv.Sim(verbose=0), label='Example multisim')
msim.run()
msim.brief() # Prints one-line output

to_json(*args, **kwargs)[source]¶: Shortcut for base_sim.to_json()

to_excel(*args, **kwargs)[source]¶: Shortcut for base_sim.to_excel()

class Scenarios(sim=None, metapars=None, scenarios=None, basepars=None, scenfile=None, label=None)[source]¶

Bases: ParsObj

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.

Parameters:

sim (Sim) – if supplied, use a pre-created simulation as the basis for the scenarios
metapars (dict) – meta-parameters for the run, e.g. number of runs; see make_metapars() for structure
scenarios (dict) – a dictionary defining the scenarios; see examples folder for examples; see below for baseline
basepars (dict) – a dictionary of sim parameters to be used for the basis of the scenarios (not required if sim is provided)
scenfile (str) – a filename for saving (defaults to the creation date)
label (str) – the name of the scenarios

Example:

scens = hpv.Scenarios()

Returns:: a Scenarios object
Return type:: scens

result_keys(which='all')[source]¶: Attempt to retrieve the results keys from the base sim

run(n_runs=None, debug=False, keep_people=False, verbose=None, **kwargs)[source]¶

Run the specified scenarios.

Parameters:

debug (bool) – if True, runs a single run instead of multiple, which makes debugging easier
verbose (int) – level of detail to print, passed to sim.run()
kwargs (dict) – passed to multi_run() and thence to sim.run()

Returns:

None (modifies Scenarios object in place)

compare(t=None, output=False)[source]¶

Print out a comparison of each scenario.

Parameters:

t (int/str) – the day (or date) to do the comparison; default, the end
output (bool) – if true, return the dataframe instead of printing output

Example:

scenarios = {'base': {'name':'Base','pars': {}}, 'beta': {'name':'Beta', 'pars': {'beta': 0.020}}}
scens = hpv.Scenarios(scenarios=scenarios, label='Example scenarios')
scens.run()
scens.compare(t=30) # Prints comparison for day 30

plot(*args, **kwargs)[source]¶

Plot the results of a scenario. For an explanation of available arguments, see Sim.plot().

Returns:: Figure handle
Return type:: fig

Example:

scens = hpv.Scenarios()
scens.run()
scens.plot()

plot_age_results(*args, **kwargs)[source]¶

Plot all age_results analyzers in a scenario together. :returns: Figure handle :rtype: fig

Example:

az = hpv.age_results(timepoints=['2015', '2020'], results=['hpv_incidence', 'total_cancers'])
base_sim = hpv.Sim(analyzers=az)
scens = hpv.Scenarios(sim=base_sim)
scens.run()
scens.plot_age_results()

to_json(filename=None, tostring=True, indent=2, verbose=False, *args, **kwargs)[source]¶

Export results as JSON.

Parameters:: filename (str) – if None, return string; else, write to file
Returns:: A unicode string containing a JSON representation of the results, or writes the JSON file to disk

to_excel(filename=None)[source]¶

Export results as XLSX

Parameters:: filename (str) – if None, return string; else, write to file
Returns:: An sc.Spreadsheet with an Excel file, or writes the file to disk

save(scenfile=None, keep_sims=True, keep_people=False, **kwargs)[source]¶

Save to disk as a gzipped pickle.

Parameters:

scenfile (str) – the name or path of the file to save to; if None, uses stored
keep_sims (bool) – whether or not to store the actual Sim objects in the Scenarios object
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:

scens.save() # Saves to a .scens file with the date and time of creation by default

static load(scenfile, *args, **kwargs)[source]¶

Load from disk from a gzipped pickle.

Parameters:

scenfile (str) – the name or path of the file to load from
kwargs – passed to hpv.load()

Returns:

the loaded scenarios object

Return type:

scens (Scenarios)

Example:

scens = hpv.Scenarios.load('my-scenarios.scens')

disp(output=False)[source]¶

Display a verbose description of the scenarios. See also scenarios.summarize() (medium length output) and scenarios.brief() (short output).

Parameters:: output (bool) – if true, return a string instead of printing output

Example:

scens = hpv.Scenarios(hpv.Sim(), label='Example scenarios')
scens.run(verbose=0) # Run silently
scens.disp() # Displays detailed output

summarize(output=False)[source]¶

Print a moderate length summary of the scenarios. See also scenarios.disp() (detailed output) and scenarios.brief() (short output).

Parameters:: output (bool) – if true, return a string instead of printing output

Example:

scens = hpv.Scenarios(hpv.Sim(), label='Example scenarios')
scens.run(verbose=0) # Run silently
scens.summarize() # Prints moderate length output

brief(output=False)[source]¶

Print a compact representation of the scenarios. See also scenarios.disp() (detailed output) and scenarios.summarize() (medium length output).

Parameters:: output (bool) – if true, return a string instead of printing output

Example:

scens = hpv.Scenarios(label='Example scenarios')
scens.run()
scens.brief() # Prints one-line output

static merge(*args)[source]¶

Merge two or more scenarios to create a single scenario object :param args: the Scenarios to merge (either a list, or separate) :type args: Scenarios

Returns:: a new Scenario object
Return type:: scen (Scenarios)

class Sweep(base_sim=None, sweep_pars=None, sweep_vars=None, n_draws=4, initialize=False, label=None, **kwargs)[source]¶

Bases: MultiSim

Class for running parameter sweeps.

Parameters:

base_sim (Sim) – the sim used for shared properties
label (str) – the name of the multisim
kwargs (dict) – stored in run_args and passed to run()

Returns:

a Sweep object

Return type:

sweep

Examples:: sim = hpv.Sim() # Create the sim sweep = hpv.Sweep(sim, sweep_pars={‘beta’:[0.4, 0.8]}, n_runs=5) # Create the sweep sweep.run() # Run the sims in parallel sweep.plot() # Plot results

create_sims(initialize=False)[source]¶

run(shrink=True, reduce=True, sum_totals=True, from_year=None, to_year=None, **kwargs)[source]¶

Run the sims :param shrink: whether or not to shrink after running :type shrink: bool :param kwargs: passed to multi_run(); use run_args to pass arguments to sim.run() :type kwargs: dict

Returns:: None (modifies MultiSim object in place)

Examples::: sweep.run()

reduce(sum_totals=True, from_year=None, to_year=None)[source]¶: Create a dataframe holding reduced results

combine(**kwargs)[source]¶

mean(**kwargs)[source]¶

median(**kwargs)[source]¶

compare(**kwargs)[source]¶

plot_heatmap(to_plot=None, xpar=None, ypar=None, zscales=1, npts=100, **kwargs)[source]¶

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 hpvsim as hp
sim = hpv.Sim() # Create a default simulation
sim = hpv.single_run(sim) # Run it, equivalent(ish) to sim.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, **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 (default: true for single, false for list of sims)
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 hpvsim as hpv
sim = hpv.Sim()
sims = hpv.multi_run(sim, n_runs=6, noise=0.2)

parallel(*args, **kwargs)[source]¶

A shortcut to hpv.MultiSim(), allowing the quick running of multiple simulations at once.

Parameters:

args (list) – The simulations to run
kwargs (dict) – passed to multi_run()

Returns:

A run MultiSim object.

Examples:

s1 = hpv.Sim(beta=0.01, label='Low')
s2 = hpv.Sim(beta=0.02, label='High')
hpv.parallel(s1, s2).plot()
msim = hpv.parallel([s1, s2], keep_people=True)