Functions & Formulae

Each applied formula has its own function page, with a signature, implementations, and tests.

Agent state update function of an agent-based model

F(X_i(t), N_i(t), E(t), A(t), U_i(t)) = X_i(t+1)

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.

  • Per-step infection probability of a susceptible agent from k infectious contacts

    P_inf = 1 - (1 - p)^k

    A susceptible agent with k contacts with infectious agents in one step, each transmitting independently with probability p, escapes infection only if every contact fails, which happens with probability (1 minus p) to the power k, the binomial probability of no events in HE-FM-BINOM-002 with k in place of n. The probability of at least one transmission, P_inf, is the complement; the article writes it P. It rises with k but less than in proportion, because a second transmission to an agent already infected adds nothing, so the sum k times p overstates it and can exceed 1. With one contact the formula returns p and with no contacts it returns zero.

  • One-step infection update of a susceptible agent from its own uniform random number

    P_inf = 1 - (1 - p)^k; X_next = (U < P_inf)

    Turns the per-step infection probability of HE-FM-ABM-001 into the agent's next state by comparing it with a uniform random number U drawn for that agent. The agent becomes infected, X_next equal to 1, when U is below P_inf, and otherwise stays susceptible with X_next equal to 0, so over many draws the share infected approaches P_inf. Drawing U from a stream reserved for the agent, the per-agent seed that Chhatwal and He describe for common random numbers, gives the same agent the same U under each strategy, so a strategy that lowers P_inf can avert that agent's infection and cannot cause it. A single draw against P_inf has the same distribution as one draw per contact against p, which the computational function under HE-FM-ABM-001 uses as an independent check.

  • Monte Carlo runs needed for a target standard error of a mean agent-based model outcome

    R_req = (s_run / e_target)^2

    Inverts the Monte Carlo standard error of a mean over independent runs, s_run divided by the square root of the number of runs (the form of HE-FM-ANTV-002 with one observation per run, with the standard deviation taken with divisor R minus 1 as in HE-FM-BSE-001), to give the number of runs R_req whose standard error equals a chosen target e_target. s_run is the standard deviation of the outcome across a pilot set of runs, for example of mean cost per person or, for an increment, of the paired difference between strategies run with common random numbers. The result is rounded up to a whole number of runs. Halving the target multiplies the runs by four.

  • Monte Carlo runs needed for a target standard error of a share of agent-based model runs

    R_prop = P_exp * (1 - P_exp) / e_share^2

    For an output that is a share of runs, such as the share in which an outbreak becomes a major one, each run gives a 0 or 1 result and the Monte Carlo standard error of the share is the binomial standard error, the square root of P_exp(1 minus P_exp) over the number of runs, the standard error of an estimated binomial probability in HE-FM-BINOM-004. Putting in the expected share and rearranging gives the number of runs R_prop for a target standard error e_share, equation 1 of Morris and colleagues. The product P_exp(1 minus P_exp) is largest at a share of 0.5, so 0.25 divided by the squared target is a worst-case count when the share is unknown.