Signature
P_inf = 1 - (1 - p)^k; X_next = (U < P_inf)
| Inputs | Definition | Unit |
|---|---|---|
p | Probability that one contact with an infectious agent transmits infection during the step, at least 0 and at most 1 | probability per contact |
k | Number of contacts with infectious agents during the step, a whole number of zero or more | contacts per step |
U | Pseudo-random number drawn for this agent and step from a uniform distribution on the unit interval, taken from the agent's own stream | dimensionless |
P_inf | Probability that the susceptible agent is infected during the step, from the contact rule of HE-FM-ABM-001 | probability per step |
|---|---|---|
X_next | State of the agent at step t+1, 1 if infected during the step and 0 if still susceptible | indicator |
Function
Agent state update function of an agent-based model
Maps the state of agent i at step t, the set of agents in contact with it, the state of the environment, the intervention in force and a random input to the state of that agent at step t+1, the rule X_i(t+1) = F(X_i(t), N_i(t), E(t), A(t), U_i(t)) of the article. In an infection model the rule for a susceptible agent reduces to a per-step infection probability from its k infectious contacts, the complement of the binomial probability of no events (HE-FM-BINOM-002), followed by a comparison of the agent's own uniform random number with that probability. A per-contact probability built from a transmission rate uses the constant-rate conversion HE-FM-TP-001, and a probability observed over another interval is rescaled with HE-FM-TP-003; neither is restated here. Population outputs are averaged over independent runs, and the Monte Carlo standard error of such a mean is the standard deviation across runs divided by the square root of the number of runs, the form of HE-FM-ANTV-002 with one observation per run and the divisor of HE-FM-BSE-001. This package adds the number of runs needed for a target standard error of a mean and of a share of runs. Attack rates and the final size relation are in HE-FN-ATR-001 and HE-CF-ATR-001, the cohort simulation without interaction is HE-FN-CSIM-001, and expected onward infections and the reproduction number belong to the Basic Reproduction Number page. Notation follows the Agent-Based Model article.
Try this function
Implementations
Excel
Agent infection update from a frozen uniform draw in Excel
With the agent's draw in a cell named AgentUniform, generated by RAND and then pasted as a value so that it does not change on recalculation, and the inputs named as in HE-IM-ABM-001, the formula returns 1 if the agent is infected in the step and 0 otherwise. Using the same AgentUniform column in each strategy's sheet gives common random numbers.
=IF(AgentUniform<1-(1-ContactTransProb)^InfectiousContacts,1,0)
Assumptions
Strict inequality in the agent uniform draw comparison
The agent is infected when U is strictly below P_inf. A tie has probability zero for a continuous uniform draw, and because Excel RAND returns values of at least 0 and below 1, the strict form never infects an agent whose P_inf is zero and always infects one whose P_inf is 1.
Synchronous update of all agents from start-of-step states
Every agent's P_inf is computed from the states at the start of the step, and all agents then change state together. Chhatwal and He state that agents update their characteristics in a certain order within each cycle and that the sequence of events within a cycle is important, so a model that updates agents one at a time states that order, because it changes who is infectious later in the same step.
Agent's own random stream kept across strategies
Each agent draws its random numbers from its own stream, set by a seed per agent, so the agent's draws do not change between strategies unless its own exposure changes. Chhatwal and He describe this per-agent seed for common random numbers, and Krijkamp and colleagues describe setting a seed number per individual in a microsimulation so that individuals are as similar as possible across intervention scenarios.
Worked examples
Agent with a draw of 0.25 infected with three contacts
For an illustrative agent whose uniform draw in the step is 0.25, three contacts at 0.10 give P_inf of 0.271, so the draw is below P_inf and the agent is infected.
p = 0.10; k = 3; U = 0.25; P_inf = 0.271; X_next = 1
Same agent and draw escaping infection with two contacts
With the same illustrative draw of 0.25 kept by the agent's own stream, the programme's two contacts give P_inf of 0.19, which is below the draw, so the agent stays susceptible. Under common random numbers the programme averts this agent's infection, and every agent whose draw is at least 0.19 and below 0.271 is averted in the same way, a share of 0.081.
p = 0.10; k = 2; U = 0.25; P_inf = 0.19; X_next = 0
Agent with no infectious contacts never infected in the step
With k equal to zero P_inf is zero, so no draw, even an illustrative 0.001, can infect the agent, a limiting case of the rule.
p = 0.10; k = 0; U = 0.001; P_inf = 0; X_next = 0
Common errors
Fresh random numbers for each strategy in the agent update
If each strategy draws new uniform numbers, the per-agent difference in infection between three and two contacts has a variance of 0.271 × 0.729 + 0.19 × 0.81, about 0.351, against 0.081 × 0.919, about 0.074, when each agent keeps its draw. About 4.7 times as many runs are then needed for the same standard error of the infections averted.
Updating agents in sequence within a step without stating the order
If agent B, a contact of an infectious agent A, is updated before agent C, whose only contact is B, then C can be infected in the same step with probability 0.10 × 0.10, or 0.01, for a per-contact probability of 0.10, while with start-of-step states that probability is zero. The order changes the speed of spread and is part of the model specification.
Sources
Chhatwal and He on update order and a random seed per agent
Chhatwal J, He T. Economic evaluations with agent-based modelling, an introduction. PharmacoEconomics. 2015;33(5):423-433. Section 2.6, which states that specific events such as transmission of disease can occur within each discrete time step, that the sequence of events within each cycle is important and that all agents are asked to update their characteristics in a certain order, and section 3.1, which implements common random numbers in agent-based models by assigning a unique random seed to each agent so that each agent's natural history or behaviour does not vary across strategies unless that agent accepts or rejects the intervention.
Krijkamp and colleagues on uniform draws and a seed per individual
Krijkamp EM, Alarid-Escudero F, Enns EA, Jalal HJ, Hunink MGM, Pechlivanoglou P. Microsimulation modeling for health decision sciences using R, a tutorial. Medical Decision Making. 2018;38(3):400-422. Section on stochastic variation and random sampling in microsimulation models, which explains that simulated individuals should be as similar as possible across comparators and that this can be achieved by explicitly setting a seed number per individual, and the section on the vectorised implementation, in which the samplev function draws each individual's state at t + 1 from vectors of random numbers generated from a U(0,1) distribution and the individual's transition probabilities.
Canonical Identity
Stable URI · Machine-readable · Resolvable · CC BY 4.0