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)[source]

Bases: BaseSim

load_data(datafile=None, **kwargs)[source]

Load the data to calibrate against, if provided

load_hiv_data(location=None, hiv_datafile=None, art_datafile=None, **kwargs)[source]

Load any data files that are used to create additional parameters, if provided

initialize(reset=False, init_states=True, **kwargs)[source]

Perform all initializations on the sim.


Attempt to retrieve the current layer keys.

reset_layer_pars(layer_keys=None, force=False)[source]

Reset the parameters to match the population.

  • layer_keys (list) – override the default layer keys (use stored keys by default)

  • force (bool) – reset the parameters even if they already exist


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


Some parameters can take multiple types; this makes them consistent.


validate_layers (bool) – whether to validate layer parameters as well via validate_layer_pars() – usually yes, except during initialization


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.


Initialize the genotype parameters


Initialize immunity matrices

init_results(frequency='annual', add_data=True)[source]

Create the main results structure. The prefix “new” is used for flow variables, i.e. counting new events (infections/deaths) on each timestep 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 The prefix “cum” is used for cumulative variables, i.e. counting the total number that have ever been in a given state at some point in the sim

  • 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_people(popdict=None, init_states=False, reset=False, verbose=None, **kwargs)[source]

Create the people and the network.

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

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


Initialize and validate the interventions


Initialize the analyzers

init_states(age_brackets=None, init_hpv_prev=None, init_cin_prev=None, init_cancer_prev=None)[source]

Initialize prior immunity and seed infections


Step through time and update values

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

Run the model once

finalize(verbose=None, restore_pars=True)[source]

Compute final results


Perform final calculations on the results


Compute prevalence, incidence, and other states.

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

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

  • 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)[source]

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

  • 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


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)[source]

Plot the outputs of the model


Compute fit between model and data.

exception AlreadyRunError[source]

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)[source]

Compute the difference of the summaries of two simulations, and print any values which differ.

  • 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


s1 = hpv.Sim(rand_seed=1).run()
s2 = hpv.Sim(rand_seed=2).run()
hpv.diff_sims(s1, s2)