stem_dynamics: Generate the objects governing the dynamics of a stochastic...
In fintzij/stemr: Stochastic Epidemic Model Simulation and Estimation

stem_dynamics

R Documentation

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

Description

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

Usage

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