Generates a rate list to be supplied to the stem_dynamics
funciton.
rate(rate, from, to, strata = NULL, incidence = FALSE, lumped = FALSE)string for computing the rate (unlumped by default unless
lumped=TRUE)
compartment from which an individual exits, a string
compartment into which an individual enters, a string
character vector of strata to which the rate applies, may be supplied as "ALL"
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.
is the rate string provided on the lumped state space of compartment counts.
rate list
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 \(\beta * I\) and \(\mu\), whereas the lumped rates which will be generated automatically are \(\beta * I * S\) and \(\mu * 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:
rate("beta * I_SELF", "S", "I", "ALL"): each susceptible contacts the infecteds within her own stratum at rate \(\beta * I\), but does not contract an infection from outside her stratum. This rate applies to subjects in all strata.
rate("beta
* I_SELF^alpha", "S", "I", "ALL"): each susceptible contacts the infecteds
within her own stratum at rate \(\beta * I^\alpha\), 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.
rate("beta * comp_fcn(I_ALL, sum)", "S", "I", "ALL"): each susceptible contacts all infecteds in the population at rate \(\beta * \sum_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.
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.
rate("beta1 * I_SELF + beta2 * comp_fcn(I_ADJ, sum)", "S", "I", "ALL"): each susceptible contacts infecteds in her own stratum at rate \(\beta1 * I_SELF\), and contacts infecteds in adjacent strata (specified in the adjacency matrix) at rate \(\beta * \sum_{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.
rate("beta * I_SELF", "S", "I_west", "ALL"): all susceptibles contact infecteds in their own region at rate \(\beta * 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.
rate("beta*I", "S", "I", "ALL", lumped = FALSE)
#> $rate
#> [1] "beta*I"
#>
#> $from
#> [1] "S"
#>
#> $to
#> [1] "I"
#>
#> $strata
#> [1] "ALL"
#>
#> $incidence
#> [1] FALSE
#>
#> $lumped
#> [1] FALSE
#>