rate: Generates a rate list to be supplied to the 'stem_dynamics'...

In fintzij/stemr: Stochastic Epidemic Model Simulation and Estimation

Generates a rate list to be supplied to the stem_dynamics funciton.

Description

Generates a rate list to be supplied to the stem_dynamics funciton.

Usage

rate(rate, from, to, strata = NULL, incidence = FALSE, lumped = FALSE)

Arguments

rate	string for computing the rate (unlumped by default unless lumped=TRUE)
from	compartment from which an individual exits, a string
to	compartment into which an individual enters, a string
strata	character vector of strata to which the rate applies, may be supplied as "ALL"
incidence	should an artificial compartment be created for th purpose of simulating or making inference based on incidence data for this transition or set of transitions? Defaults to FALSE.
lumped	is the rate string provided on the lumped state space of compartment counts.

Value

rate list

Specifying the rate functions

Each rate list specifies, at a minimum, the rate function, the compartment from which an individual exits, the compartment that she enters. Optionally, the strata to which the rate function applies can be supplied. The optional strata argument can either be a character vector of strata for which the rate applies, or may be specified as "ALL" if the rate function applies to common compartments in all strata. If there are multiple strata, the strata argument for each rate is required. If a rate is time dependent, the reserved word "TIME" should be used for the time variable. For example, "beta * I + eta *TIME" would indicate a linear trend in the infectivity rate.

VERY IMPORTANT: The rate functions are assumed to be specified at the subject level and they are parsed internally and converted to lumped rates. For example, in a standard SIR model, the subject-level infectivity and recovery rates are β * I and μ, whereas the lumped rates which will be generated automatically are β * I * S and μ * I. When a lumped string is provided, no internal conversion will occur.

The rate functions should be provided as string snippets of valid C++ code (though if the snippet is a single line, no semicolon needs to be added). Each function is parsed internally for references to parameters, compartments, strata, constants, and the time variable. There are a few case-sensitive reserved words that are provided to facilitate the specification of rate functions when there are multiple strata that factor into a rate: "ALL", "REL", "ADJ", "SELF". "ALL", "REL", and "ADJ" will be parsed as a vector of compartments, and therefore must be wrapped using the comp_fcn function, which specifies how the compartments in that vector should be aggregated.

In an SIR model with multiple strata, for example, we could specify infectivity rates as follows:

1. rate("beta * I_SELF", "S", "I", "ALL"): each susceptible contacts the infecteds within her own stratum at rate β * I, but does not contract an infection from outside her stratum. This rate applies to subjects in all strata.

2. rate("beta * I_SELF^alpha", "S", "I", "ALL"): each susceptible contacts the infecteds within her own stratum at rate β * I^α, but does not contract an infection from outside her stratum. Note that the rate will be parsed to produce valid C++, so exponentiation is done using the pow() function.

3. rate("beta * comp_fcn(I_ALL, sum)", "S", "I", "ALL"): each susceptible contacts all infecteds in the population at rate β * ∑_s I_s, regardless of stratum. Note that 'I_ALL' will be replaced by a vector of I_strata, therefore using 'I_all' outside of a function, e.g. beta * I_ALL, will result in an error. However, beta * comp_fcn(I_ALL, sum) is well defined.

4. rate("beta * comp_fcn(I_REL), sum,", "S", "I", c("young", "old")): each suscpetible contacts infecteds in the young and old strata with rate beta. N.B. when the "REL" keyword is used in a comp_fcn call, the relevant strata will be pulled from the strata supplied in the rate.

5. rate("beta1 * I_SELF + beta2 * comp_fcn(I_ADJ, sum)", "S", "I", "ALL"): each susceptible contacts infecteds in her own stratum at rate β1 * I_SELF, and contacts infecteds in adjacent strata (specified in the adjacency matrix) at rate β * ∑_{s: stratum 's' is adjacent} I_s. Note that in this case, the diagonal entries in the adjacency matrix should be set to zero.

The from and to arguments will automatically be updated when the rate is parsed within the stem_dynamics function to reflect the strata if there are multiple strata in the event that no strata are specified in those arguments. Suppose, for example, that we define strata to be two adjacent regions, east and west. The first rate given above will be understood as governing transitions from S_east to I_east, and from S_west to I_west. If we we want to define rates for transitions where a subject crosses strata, we can do so by including the strata in the from and to arguments.

1. rate("beta * I", "S_east","I_west", "east"): each susceptible in the east contacts infected individuals in the east at rate β * I_east, and then transitions to the infected compartment in the west stratum.

2. rate("beta * I_SELF", "S", "I_west", "ALL"): all susceptibles contact infecteds in their own region at rate β * I, but upon becoming infected end up in the infected compartment in the west stratum.

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. Thus, it is highly recommended that the names of all model compartment, parameters, time-varying covariates, and constants be at least four characters long.

Examples

rate("beta*I", "S", "I", "ALL", lumped = FALSE)

fintzij/stemr documentation built on March 25, 2022, 12:25 p.m.