Scenarios

class Scenarios(sim=None, metapars=None, scenarios=None, basepars=None, scenfile=None, label=None)

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

Methods

result_keys(which='all')

Attempt to retrieve the results keys from the base sim

run(n_runs=None, debug=False, keep_people=False, verbose=None, **kwargs)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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

Returns:

a new Scenario object

Return type:

scen (Scenarios)