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

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.

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

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.

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)
#> # A tibble: 6 x 4
#>     sim agent_id     S     I
#>   <dbl>    <dbl> <dbl> <dbl>
#> 1     1        1     1    NA
#> 2     1        2     1    NA
#> 3     1        3     1    NA
#> 4     1        4     1    NA
#> 5     1        5     1    NA
#> 6     1        6     1    NA
table(abm$I)
#> 
#>  1 13 56 79 82 83 98 
#>  5  1  1  1  1  1  1 
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()