hpvsim.people module

Defines the People class and functions associated with making people and handling the transitions between states (e.g., from susceptible to infected).

class People(pars, strict=True, pop_trend=None, **kwargs)[source]

Bases: BasePeople

A class to perform all the operations on the people – usually not invoked directly.

This class is usually created automatically by the sim. The only required input argument is the population size, but typically the full parameters dictionary will get passed instead since it will be needed before the People object is initialized. However, ages, contacts, etc. will need to be created separately – see hpv.make_people() instead.

Note that this class handles the mechanics of updating the actual people, while hpv.BasePeople takes care of housekeeping (saving, loading, exporting, etc.). Please see the BasePeople class for additional methods.

  • pars (dict) – the sim parameters, e.g. sim.pars – alternatively, if a number, interpreted as n_agents

  • strict (bool) – whether or not to only create keys that are already in self.meta.person; otherwise, let any key be set

  • pop_trend (dataframe) – a dataframe of years and population sizes, if available

  • kwargs (dict) – the actual data, e.g. from a popdict, being specified


ppl1 = hpv.People(2000)

sim = hpv.Sim()
ppl2 = hpv.People(sim.pars)

Initialize flows to be zero


Return the scaled versions of the flows – replacement for len(inds) followed by scale factor multiplication


Let people age by one timestep

initialize(sim_pars=None, hiv_pars=None)[source]

Perform initializations

update_states_pre(t, year=None)[source]

Perform all state updates at the current timestep

set_prognoses(inds, g, dt, hiv_pars=None)[source]

Set prognoses for people following infection. Wrapper method that calls the 4 separate methods for setting and updating prognoses.

set_dysp_status(inds, g, dt)[source]

Use durations and dysplasia rates to determine whether HPV clears or progresses to dysplasia

set_severity(inds, g, gpars, hiv_prog_rate=None)[source]

Set dysplasia severity and duration for women who develop dysplasia

set_dysp_rates(inds, g, gpars, hiv_dysp_rate=None)[source]

Set dysplasia rates

set_cin_grades(inds, g, dt, dysp_arrs)[source]

Set CIN clinical grades and dates of progression

set_hiv_prognoses(inds, year=None)[source]

Set HIV outcomes (for now only ART)


Dissolve partnerships

create_partnerships(tind, mixing, layer_probs, cross_layer, dur_pship, acts, age_act_pars, pref_weight=100)[source]

Create partnerships. All the hard work of creating the contacts is done by hppop.make_contacts, which in turn relies on hpu.create_edgelist for creating the edgelist. This method is just a light wrapper that passes in the arguments in the right format and the updates relationship info stored in the People class.

check_inds(current, date, filter_inds=None)[source]

Return indices for which the current state is false and which meet the date criterion

check_inds_true(current, date, filter_inds=None)[source]

Return indices for which the current state is true and which meet the date criterion


Check for new progressions to CIN1


Check for new progressions to CIN2


Check for new progressions to CIN3


Check for new progressions to cancer


Check for new deaths from cancer


Check for HPV clearance.


Apply HIV infection rates to population


Apply death rates to remove people from the population NB people are not actually removed to avoid issues with indices

add_births(year=None, new_births=None)[source]

Add more people to the population

Specify either the year from which to retrieve the birth rate, or the absolute number of new people to add. Must specify one or the other. People are added in-place to the current People instance


Check if people need to immigrate/emigrate in order to make the population size correct.


Make a set of people naive. This is used during dynamic resampling.


inds (array) – list of people to make naive

infect(inds, g=None, offset=None, dur=None, layer=None)[source]

Infect people and determine their eventual outcomes. Method also deduplicates input arrays in case one agent is infected many times and stores who infected whom in infection_log list.

  • inds (array) – array of people to infect

  • g (int) – int of genotype to infect people with

  • offset (array) – if provided, the infections will occur at the timepoint self.t+offset

  • dur (array) – if provided, the duration of the infections

  • layer (str) – contact layer this infection was transmitted on


number of people infected

Return type

count (int)

remove_people(inds, cause=None)[source]

Remove people - used for death and migration

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

Plot statistics of the population – age distribution, numbers of contacts, and overall weight of contacts (number of contacts multiplied by beta per layer).

  • bins (arr) – age bins to use (default, 0-100 in one-year bins)

  • width (float) – bar width

  • font_size (float) – size of font

  • alpha (float) – transparency of the plots

  • fig_args (dict) – passed to pl.figure()

  • axis_args (dict) – passed to pl.subplots_adjust()

  • plot_args (dict) – passed to pl.plot()

  • do_show (bool) – whether to show the plot

  • fig (fig) – handle of existing figure to plot into

story(uid, *args)[source]

Print out a short history of events in the life of the specified individual.

  • uid (int/list) – the person or people whose story is being regaled

  • args (list) – these people will tell their stories too


sim = hpv.Sim(pop_type='hybrid', verbose=0)