hpvsim.sim module

Define core Sim classes

class Sim(pars=None, datafile=None, label=None, popfile=None, people=None, version=None, hiv_datafile=None, art_datafile=None, **kwargs)

Bases: BaseSim

load_data(datafile=None, **kwargs)

Load the data to calibrate against, if provided

initialize(reset=False, init_states=True, init_analyzers=True, **kwargs)

Perform all initializations on the sim.

layer_keys()

Attempt to retrieve the current layer keys.

reset_layer_pars(layer_keys=None, force=False)

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()

Handle layer parameters, since they need to be validated after the population creation, rather than before.

validate_pars(validate_layers=True)

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

validate_init_conditions(init_hpv_prev)

Initial prevalence values can be supplied with different amounts of detail. Here we flesh out any missing details so that the initial prev values are by age and genotype. We also check the prevalence values are ok.

init_genotypes(upper_dysp_lim=200)

Initialize the genotype parameters

init_results(frequency='annual', add_data=True)

Create the main results structure. The prefix “n” is used for stock variables, i.e. counting the total number in any given state (sus/inf/etc) on any particular timestep

Parameters:

• sim (hpv.Sim) – a sim

• frequency (str or float) – the frequency with which to save results: accepts ‘annual’, ‘dt’, or a float which is interpreted as a fraction of a year, e.g. 0.2 will save results every 0.2 years

• add_data (bool) – whether or not to add data to the result structures

init_interventions()

Initialize and validate the interventions

init_people(popdict=None, init_states=False, reset=False, verbose=None, **kwargs)

Create the people and the network.

Use init_states=False for creating a fresh People object for use in future simulations

Parameters:

• popdict (any) – pre-generated people of various formats.

• init_states (bool) – whether to initialize states (default false when called directly)

• reset (bool) – whether to regenerate the people even if they already exist

• verbose (int) – detail to print

• kwargs (dict) – passed to hpv.make_people()

init_analyzers()

Initialize the analyzers

init_immunity(create=True)

Initialize immunity matrices and cumulative dysplasia

init_hiv()

Initialize states, attributes, and parameters relating to HIV

finalize_analyzers()

init_states(age_brackets=None, init_hpv_prev=None, init_cin_prev=None, init_cancer_prev=None)

Initialize prior immunity and seed infections

step()

Step through time and update values

run(do_plot=False, until=None, restore_pars=True, reset_seed=True, verbose=None)

Run the model once

finalize(verbose=None, restore_pars=True)

Compute final results

compute_results(verbose=None)

Perform final calculations on the results

compute_states()

Compute prevalence, incidence, and other states.

compute_summary(t=None, update=True, output=False, require_run=False)

Compute the summary dict and string for the sim. Used internally; see sim.summarize() for the user version.

Parameters:

• 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, sep=None, output=False)

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. 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)

• sep (str) – thousands separator (default ‘,’)

• output (bool) – whether to return the summary instead of printing it

Examples:

sim = hpv.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

plot(*args, **kwargs)

Plot the outputs of the model

compute_fit()

Compute fit between model and data.

exception AlreadyRunError

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.

diff_sims(sim1, sim2, skip_key_diffs=False, skip=None, output=False, die=False)

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

• skip (list) – a list of values to skip

• 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 = hpv.Sim(rand_seed=1).run()
s2 = hpv.Sim(rand_seed=2).run()
hpv.diff_sims(s1, s2)