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¶
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)¶
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
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)¶
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)¶
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)¶
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)¶
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
- calculate_peak_immunity(inds, a=4.82, b=- 0.3, c=3.31, d=- 0.32)¶
immunity immediately post infection
- calculate_current_immunity(inds, rate=0.87)¶
immunity after t months have passed since exposure
- calculate_shed_duration(inds, u=30.3, delta=1.16, sigma=1.86)¶
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
virus shed per gram, time is in months!
- calculate_log10_peak_cid50(k=0.056, Smax=6.7, Smin=4.3, tau=12)¶
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)¶
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)¶
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)¶
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)¶
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)¶
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)¶
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)¶
- prob_infection(beta, current_immunities, doses=1000000, alpha=0.44, gamma=0.46)¶