Generate the objects governing the dynamics of a stochastic epidemic model.

stem_dynamics(
  rates,
  parameters,
  state_initializer,
  compartments,
  tmax,
  tparam = NULL,
  tcovar = NULL,
  forcings = NULL,
  strata = NULL,
  constants = NULL,
  timestep = NULL,
  adjacency = NULL,
  messages = FALSE,
  compile_rates = TRUE,
  compile_lna = TRUE,
  compile_ode = TRUE,
  step_size = 1e-06,
  stepper = "rk54_a",
  rtol = 1e-06,
  atol = 1e-06,
  ...
)

Arguments

rates

list of rate lists, each generated by a call to the rate function.

parameters

numeric vector with named elements, the model parameters. Note that this includes ALL model parameters, including those referred to in the measurement process. Importantly, if there is a time-varying parameter in the model it should not be included in the parameters argument, but rather specified separately in the tparam argument. However, if the time-varying parameter depends on hyperparameters that are updated via MCMC, the hyperparameters should be included in the vector of parameters.

state_initializer

list of initializer lists, each generated by a call to stem_initializer. Used to initialize the system at the first observation time.

compartments

character vector of compartment names if there is a single stratum, or if there are multiple strata a list of character vectors where the name of each character vector is the compartment name and the character vector lists the strata to in which the compartment exists. The reserved word "ALL" can be used instead of listing all strata.

tmax

the time at which simulation of the system is terminated. Defaults to the last observation time if not supplied.

tparam

list of time-varying parameter lists, each generated by a call to the tparam function. Time-varying parameters are defined by mapping vectors of N(0,1) draws to parameter values and are updated jointly via elliptical slice sampling.

tcovar

Matrix of time varying covariates, the first column of which contains the times at which covariates change. Note that if a covariate modifies the model compartment counts (e.g., vaccination), the flow between model compartments must also be declared using a list of forcing functions, supplied in the forcings argument (see the documentation for the forcing function).

forcings

list of forcings, which declare that certain time varying covariates modify compartment counts, each generated by a call to the forcing function.

strata

vector of stratum names, required if the "ALL" reserved word is used

(e.g. compartments = list(S = "ALL", I = "ALL", R = "ALL", D = "old"); strata = c("infants", "young", "old");

constants

optional. numeric vector with named elements that are constants referenced in the rate functions.

adjacency

optional matrix specifying the adjacency structure of strata, with 0 entries indicating non-adjacency and 1 for adjacency. Rows and columns must be labeled.

Important note: care should be taken to make sure that there are no partial string matches between the building blocks of a model. For example, if the population size is given by the string constant "N", then "N" should not appear in any of parameter names, compartment names, etc. In particular, suppose there is a parameter named "BETA_N". When the rate functions are parsed internally, the rate strings will be parsed incorrectly due to the partial match.

messages

should a message be printed when parsing the rates?

compile_rates

should the rate functions for exact simulation and inference be compiled?

compile_lna

should the LNA functions be compiled?

compile_ode

should the ODE functions for the deterministic mean process be compiled?

step_size

initial step size for ODE stepper. Adapted internally, but too large of an initial size can lead to failures in stiff systems.

stepper

string specifying the stepper type (see odeintr package documentation)

rtol, atol

stepper error tolerance (see odeintr package documentation)

Value

list with evaluated rate functions and objects for managing the bookkeeping for epidemic paths. The objects in the list are as follows:

rates: list of parsed rate functions
rate_ptrs: vector of external function pointers to compiled rate functions.
parameters: named numeric vector of model parameters
tcovar: matrix of time-varying covariates, with column names
constants: named numeric vector of constants, with stratum sizes and population size included
state_initializer: list of model initializer lists
initdist_params: named numeric vector of parameters governing the initial distribution of compartment counts
fixed_inits: logical indicating whether the initial distribution parameters are fixed compartment counts (TRUE) or parameters of a dirichlet distribution (FALSE)
flow_matrix: matrix of flow between model compartments associated with each transition event
lna_rates: list with lna pointers and lna code
strata_sizes: named numeric vector of strata sizes
popsize: population size
comp_codes: named vector of (C++) compartment codes
param_codes: named vector of (C++) parameter codes
tcovar_codes: named vector of (C++) time-varying covariate codes
const_codes: named vector of (C++) constant codes
strata_codes: named vector of (C++) strata codes
incidence_codes: named vector of (C++) incidence compartment codes (colum location in the path matrix)
incidence_sources: named vector of (C++) codes for compartments corresponding to each incidence compartment
lna_param_codes: named vector of (C++) codes for the concatenated LNA parameters
progressive: logical indicating whether the model is progressive
absorbing_states: logical vector indicating which model compartments are absorbing states
rate_adjmat: adjacency matrix indicating which rates need to be updated when a transition event occurs
timevarying: logical indicating whether there are any time-varying covariates or parameters
timecode: index of column in the time-varying covariate matrix for time (as a variable, not an index)
tcovar_adjmat: adjacency matrix indicating which rates need to be updated when a time-varying covariate value changes
tcovar_changemat: indicator matrix indicating which time-varying covariates change at which time in the tcovar matrix
t0: initialization time for the system
tmax: time until which the system evolves
n_strata: number of strata
n_compartments: number of compartments
n_params: number of model parameters
n_tcovar: number of time-varying covariates, including time
n_consts: number of constants in the model
dynamics_args: original arguments supplied to stem_dynamics