#' Generates a rate list to be supplied to the \code{\link{stem_dynamics}}
#' funciton.
#'
#' @param rate string for computing the rate (unlumped by default unless
#' \code{lumped=TRUE})
#' @param from compartment from which an individual exits, a string
#' @param to compartment into which an individual enters, a string
#' @param strata character vector of strata to which the rate applies, may be
#' supplied as "ALL"
#' @param 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.
#' @param lumped is the rate string provided on the lumped state space of
#' compartment counts.
#' @section 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 \code{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.
#'
#' \emph{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 \eqn{\beta * I} and \eqn{\mu}, whereas the lumped
#' rates which will be generated automatically are \eqn{\beta * I * S} and
#' \eqn{\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
#' \code{\link{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: \enumerate{ \item rate("beta * I_SELF", "S",
#' "I", "ALL"): each susceptible contacts the infecteds within her own stratum
#' at rate \eqn{\beta * I}, but does not contract an infection from outside
#' her stratum. This rate applies to subjects in all strata. \item rate("beta
#' * I_SELF^alpha", "S", "I", "ALL"): each susceptible contacts the infecteds
#' within her own stratum at rate \eqn{\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
#' \code{pow()} function. \item rate("beta * comp_fcn(I_ALL, sum)", "S", "I",
#' "ALL"): each susceptible contacts all infecteds in the population at rate
#' \eqn{\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. \item 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 \code{comp_fcn} call, the relevant strata will be pulled from the
#' strata supplied in the rate. \item rate("beta1 * I_SELF + beta2 *
#' comp_fcn(I_ADJ, sum)", "S", "I", "ALL"): each susceptible contacts
#' infecteds in her own stratum at rate \eqn{\beta1 * I_SELF}, and contacts
#' infecteds in adjacent strata (specified in the adjacency matrix) at rate
#' \eqn{\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 \code{from} and \code{to} arguments will automatically be updated when
#' the rate is parsed within the \code{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
#' \code{from} and \code{to} arguments. \enumerate{\item rate("beta * I",
#' "S_east","I_west", "east"): each susceptible in the east contacts infected
#' individuals in the east at rate \eqn{\beta * I_east}, and then transitions
#' to the infected compartment in the west stratum. \item rate("beta *
#' I_SELF", "S", "I_west", "ALL"): all susceptibles contact infecteds in their
#' own region at rate \eqn{\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.
#'
#' @return rate list
#' @export
#'
#' @examples rate("beta*I", "S", "I", "ALL", lumped = FALSE)
rate <- function(rate, from, to, strata = NULL, incidence = FALSE, lumped = FALSE) {
# generate the formula
list(rate = rate, from = from, to = to, strata = strata, incidence = incidence, lumped = lumped)
}
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.