simulate_agents: Simulate an agent-based model for given state-to-state...

In skgallagher/timeternR: A Pipeline to Analyze and Compare Infectious Disease Epidemics

Description

Simulate an agent-based model for given state-to-state transfers

Usage

simulate_agents(
  trans_mat,
  init_vals,
  par_vals,
  max_T,
  n_sims,
  birth_dates = NULL,
  birth_states = NULL,
  verbose = TRUE,
  out_format = "wide"
)

Arguments

trans_mat	TBD matrix of size KxK where K is the total number of states (including death and excluding birth)
init_vals	vector of length K corresponding to the initial values in each state. This will be over-ridden by birth_dates and birth_states if those are not NULL.
par_vals	vector of named parameters and their values
max_T	total number of discrete time steps
n_sims	number of simulations to run
birth_dates	vector of size N, the maximum number of agents where each entry is the 'birth' of the agent into the system
birth_states	which state an agent begins when born into the system
verbose	logical to print progress
out_format	Format of the output data frame. Wide corresponds to one row to each agent and "long" corresponds to one row being a state change. Generally, 'wide' is more readable and slightly easier to use with other EpiCompare functions. However, With the 'wide' format, there is a problem when agents can enter a state more than once. This will trigger an error.

Details

A (fairly) generic, simple agent-based model based on multinomial/categorical draws to transfer from state to state. Although the function can support a non-constant population, it does not support random births, they must be pre-specified. Random deaths may be supported by adding a compartment for them. Please see the 'basic-abm' vignette for more details on usage.

Value

a data frame with the following columns

agent_id

unique ID of agent that can be linked through simulations

time

time between 0 and max_T

state

integer of the state the agent goes to at that time

state_name

name of state corresponding to the integer

sim

simulation number

Examples

## SI example
## In this example, agents start out susceptible and then become infected

trans_mat <- matrix(c("X0 * (1 - X1 * par1/N)", "X0 * X1 * par1 / N",
"0", "X1"), byrow = TRUE, nrow = 2)
rownames(trans_mat) <- c("S", "I")
init_vals <- c(999, 1)
par_vals <- c(par1 = .01)
max_T <- 100
n_sims <- 5

abm <- simulate_agents(trans_mat,
init_vals,
par_vals,
max_T,n_sims,
verbose = FALSE)

head(abm)
table(abm$I)
library(ggplot2)
library(dplyr)
abm %>% dplyr::group_by(sim) %>%
agents_to_aggregate(states = I) %>%
ggplot(aes( x= t, y = X1, group = sim, col = factor(sim))) +
geom_line()

skgallagher/timeternR documentation built on Sept. 16, 2021, 7:21 p.m.