poliosim.model module

Defines the full Poliosim model, which consists of the states and functions for updating states of each person (People class), and the dynamics of the simulation (Sim class).

class States[source]

Bases: sciris.sc_utils.prettyobj

For storing all the keys relating to a person and people

person = ['uid', 'age', 'sex', 'symp_prob', 'viral_shed', 'household_id', 'strain_type', 't_infection', 'current_immunity', 'prechallenge_immunity', 'postchallenge_peak_immunity', 'shed_duration', 'log10_peak_cid50', 'exposure_count', 'sus_para_exp_count', 'ri_dose_count', 'ri_take_count', 'sia_dose_count', 'sia_take_count', 'rel_trans']
states = ['naive', 'exposed', 'symptomatic', 'susceptible_to_paralysis', 'IPV_naive', 'is_shed', 'tested', 'diagnosed', 'recovered', 'known_contact', 'quarantined']
dates = ['date_naive', 'date_exposed', 'date_symptomatic', 'date_susceptible_to_paralysis', 'date_IPV_naive', 'date_is_shed', 'date_tested', 'date_diagnosed', 'date_recovered', 'date_known_contact', 'date_quarantined', 'date_pos_test', 'date_end_quarantine', 'date_first_exposed', 'date_end_isolation']
durs = ['dur_exp2inf', 'dur_inf2sym', 'dur_disease']
all_states = ['uid', 'age', 'sex', 'symp_prob', 'viral_shed', 'household_id', 'strain_type', 't_infection', 'current_immunity', 'prechallenge_immunity', 'postchallenge_peak_immunity', 'shed_duration', 'log10_peak_cid50', 'exposure_count', 'sus_para_exp_count', 'ri_dose_count', 'ri_take_count', 'sia_dose_count', 'sia_take_count', 'rel_trans', 'naive', 'exposed', 'symptomatic', 'susceptible_to_paralysis', 'IPV_naive', 'is_shed', 'tested', 'diagnosed', 'recovered', 'known_contact', 'quarantined', 'date_naive', 'date_exposed', 'date_symptomatic', 'date_susceptible_to_paralysis', 'date_IPV_naive', 'date_is_shed', 'date_tested', 'date_diagnosed', 'date_recovered', 'date_known_contact', 'date_quarantined', 'date_pos_test', 'date_end_quarantine', 'date_first_exposed', 'date_end_isolation', 'dur_exp2inf', 'dur_inf2sym', 'dur_disease']
class People(pars=None, strict=True, **kwargs)[source]

Bases: poliosim.base.BasePeople

A class to perform all the operations on the people. This class is usually not invoked directly, but instead is created automatically by the sim. Most initialization happens in BasePeople.

  • pars (dict) – the sim parameters, e.g. sim.pars – must have pop_size and n_days keys

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

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


Perform initializations


Create the seed infections


Set the prognoses for each person based on age during initialization. Need to reset the seed because viral loads are drawn stochastically.


Perform all state updates at the current timestep


Perform post-timestep updates

attempt_canonical_infection(attempt_date, dose=1000000, beta=1.0)[source]

Determine whether candidate targets will be infected based on their current immunity state, and if so, infect them. Uses unmodified betas and infection probabilities from the reference model.


This isn’t used internally, but is used by user scripts

update_polio(t_days=None, inds=None)[source]

Update each polio agent


Check for new progressions to symptomatic


Check for and/or do recovery = not infectious any more


Check for new diagnoses. Since most data are reported with diagnoses on the date of the test, this function reports counts not for the number of people who received a positive test result on a day, but rather, the number of people who were tested on that day who are schedule to be diagnosed in the future.

get_quarantine_subtargets(quarantine_subtarget, quarantine_candidate_inds)[source]

A small helper function.

  • quarantine_subtarget – a function. This function should take (people, quarantine_candidate_inds),

  • 'quarantine_candidate_inds'. (and should return a dictionary with keys 'inds' and 'vals'. The key 'inds' should be a copy of) –

  • candidates. (The 'vals' should be the associated probability of quarantining each of the quarantine) –

  • quarantine_candidate_inds – array of the indices of the candidates to potentially be quarantined.


Check for who gets put into quarantine


Make person naive. This is used during dynamic resampling


State changes associated with polio infection. Indices rather than filtering are used here for speed.

infect(inds, source=None, layer=None)[source]

Infect people and determine their eventual outcomes. Polio-specific state changes are in polio_infect(). Indices rather than filtering are used here for speed.

  • inds (array) – array of people to infect

  • source (array) – source indices of the people who transmitted this infection (None if an importation or seed infection)

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


number of people infected

Return type

count (int)

calculate_peak_immunity(inds, a=4.82, b=- 0.3, c=3.31, d=- 0.32)[source]

immunity immediately post infection

calculate_current_immunity(inds, rate=0.87)[source]

immunity after t months have passed since exposure

calculate_shed_duration(inds, u=30.3, delta=1.16, sigma=1.86)[source]

probability of shedding given Nab at time t (days post infection); assumes that individual was infected at t = 0; time is measured in days Equation S1 in Famulare 2018 PLOS Bio paper delta_t = time (days) since last infection – survival curve follows lognormal distribution

calculate_viral_shed(eta=1.65, v=0.17, epsilon=0.32)[source]

virus shed per gram, time is in months!

calculate_log10_peak_cid50(k=0.056, Smax=6.7, Smin=4.3, tau=12)[source]

returns the peak log10(cid50/g) given prior immunity, age is in months!

test(inds, test_sensitivity=1.0, loss_prob=0.0, test_delay=0)[source]

Method to test people

  • inds – indices of who to test

  • test_sensitivity (float) – probability of a true positive

  • loss_prob (float) – probability of loss to follow-up

  • test_delay (int) – number of days before test results are ready


Whether or not this person tested positive


Quarantine selected people starting on the current day. If a person is already quarantined, this will extend their quarantine. :param inds: indices of who to quarantine, specified by check_quar() :type inds: array

trace(inds, trace_probs, trace_time)[source]

Trace the contacts of the people provided :param inds: indices of whose contacts to trace :type inds: array :param trace_probs: probability of being able to trace people at each contact layer - should have the same keys as contacts :type trace_probs: dict :param trace_time: days it’ll take to trace people at each contact layer - should have the same keys as contacts :type trace_time: dict

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

class Sim(pars=None, datafile=None, datacols=None, label=None, simfile=None, popfile=None, load_pop=False, save_pop=False, **kwargs)[source]

Bases: poliosim.base.BaseSim

The Sim class handles the running of the simulation: the number of children, number of time points, and the parameters of the simulation.

  • pars (dict) – parameters to modify from their default values

  • datafile (str/df) – filename of (Excel, CSV) data file to load, or a pandas dataframe of the data

  • datacols (list) – list of column names of the data to load

  • label (str) – the name of the simulation (useful to distinguish in batch runs)

  • simfile (str) – the filename for this simulation, if it’s saved (default: creation date)

  • popfile (str) – the filename to load/save the population for this simulation

  • load_pop (bool) – whether to load the population from the named file

  • save_pop (bool) – whether to save the population to the named file

  • kwargs (dict) – passed to make_pars()


sim = ps.Sim()
sim = ps.Sim(pop_size=10e3, datafile='my_data.xlsx')

Perform all initializations, including validating the parameters, setting the random number seed, creating the results structure, initializing the people, validating the layer parameters (which requires the people), and initializing the interventions.


kwargs (dict) – passed to init_people


Create the main results structure. We differentiate between flows, stocks, and cumulative results The prefix “new” is used for flow variables, i.e. counting new events (infections/recoveries) on each timestep The prefix “n” is used for stock variables, i.e. counting the total number in any given state (sus/inf/rec/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


Dynamically rescale the population – used during step()


Step the simulation forward in time. Usually, the user would use sim.run() rather than calling sim.step() directly.

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

Run the simulation.

  • do_plot (bool) – whether to plot

  • until (int/str) – day or date to run until

  • restore_pars (bool) – whether to make a copy of the parameters before the run and restore it after, so runs are repeatable

  • reset_seed (bool) – whether to reset the random number stream immediately before run

  • verbose (float) – level of detail to print, e.g. 0 = no output, 0.2 = print every 5th day, 1 = print every day


A pointer to the sim object (with results modified in-place)

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

Compute final results


Perform final calculations on the results


Compute prevalence and incidence. Prevalence is the current number of infected people divided by the number of people who are alive. Incidence is the number of new infections per day divided by the susceptible population.

initialize_immunity(people, sia_coverage, ri_coverage, ri_ages_years)[source]
prob_infection(beta, current_immunities, doses=1000000, alpha=0.44, gamma=0.46)[source]