documentation edits for flows and specifications

Author: stevencarlislewalker

R/formula_list_generators.R

@@ -808,7 +808,7 @@ HazardUpdateMethod = function(change_model) {
 #' Specify different kinds of flows between compartments.
 #' 
 #' The examples below can be mixed and matched in `mp_tmb_model_spec()`
-#' to produce compartmental models. Note that the symbols used below must
+#' to produce compartmental models. The symbols used below must
 #' be used in an appropriate context (e.g., if `N` is used for total population
 #' size, then there must be an expression like `N ~ S + I + R` somewhere in
 #' the model or for models with constant population size there must be a 
@@ -818,20 +818,23 @@ HazardUpdateMethod = function(change_model) {
 #' originates.
 #' @param to String giving the name of the compartment to which the flow is
 #' going.
-#' @param rate String giving the expression for the per-capita or absolute
-#' flow rate. Alternatively for per-capita flows, and for back compatibility, 
+#' @param rate String giving the expression for the per-capita
+#' flow rate. Alternatively, and for back compatibility, 
 #' a two-sided formula with the left-hand-side giving the name of the absolute 
-#' flow rate per unit time-stepand the right-hand-side giving an expression for 
+#' flow rate per time-step and the right-hand-side giving an expression for 
 #' the per-capita rate of flow from `from` to `to`.
-#' @param abs_rate String giving the name for the absolute flow rate. 
-#' By default, during simulations, the absolute flow rate will be computed as
-#' `from * rate`. This default behaviour will simulate the compartmental model
-#' as discrete difference equations, but this default can be changed to use
-#' other approaches (see \code{\link{state_updates}}).
-#' If a formula is passed to `rate` (not recommended for better readability), 
-#' then this `abs_rate` argument will be ignored.
+#' @param abs_rate String giving the name for the absolute flow rate per
+#' time-step. By default, during simulations, the absolute flow rate will be 
+#' computed as `from * rate`. This default behaviour will simulate the 
+#' compartmental model as discrete difference equations, but this can 
+#' be changed to use other approaches such as ordinary differential equations
+#' or stochastic models (see \code{\link{state_updates}}). If a formula is 
+#' passed to `rate` (not recommended for better readability), then this 
+#' `abs_rate` argument will be ignored.
 #' @param rate_name String giving the name for the absolute flow rate.
 #' 
+#' @seealso [mp_absolute_flow()]
+#' 
 #' @examples
 #' 
 #' # infection by mass action
@@ -896,16 +899,31 @@ mp_per_capita_outflow = function(from, rate, abs_rate = NULL) {
   PerCapitaOutflow(from, rate, call_string)
 }
 
-#' @describeIn mp_per_capita_flow Experimental
+
+#' Specify Absolute Flow Between Compartments (Experimental)
+#' 
+#' An experimental alternative to \code{\link{mp_per_capita_flow}} that 
+#' allows users to specify flows using absolute rates instead of 
+#' per-capita rates.
+#' 
+#' @param from String giving the name of the compartment from which the flow
+#' originates.
+#' @param to String giving the name of the compartment to which the flow is
+#' going.
+#' @param rate String giving the expression for the absolute
+#' flow rate per time-step.
+#' @param rate_name String giving the name for the variable that 
+#' will store the `rate`.
+#' 
+#' @seealso [mp_per_capita_flow()]
+#' 
 #' @export
 mp_absolute_flow = function(from, to, rate, rate_name = NULL) {
   call_string = deparse(match.call())
   rate = handle_abs_rate_args(rate, rate_name)
   AbsoluteFlow(from, to, rate, call_string)
 }
 
-
-
 PerCapitaOutflow = function(from, rate, call_string) {
   self = PerCapitaFlow(from, NULL, rate, call_string)
   self$change_frame = function() {
@@ -1037,16 +1055,9 @@ to_change_component.ChangeComponent = function(x) x
 to_change_component.formula = function(x) Formula(x)
 
 
-#' Reduce Model
-#' 
-#' Reduce a model by removing any model structure 
-#' (e.g. \code{\link{mp_per_capita_flow}}), so that expression lists
-#' are plain R formulas.
-#' 
-#' @param model A model object.
-#'
-#' @describeIn mp_expand Synonym of `mp_expand` present only for 
-#' back-compatibility. Please use `mp_expand` in new projects.
+#' @describeIn mp_expand Confusingly, `mp_reduce` and `mp_expand` are synonyms.
+#' Please use `mp_expand` in new projects, as `mp_reduce` is available for 
+#' back-compatibility only.
 #' @export
 mp_reduce = function(model) UseMethod("mp_reduce")
 

R/mp_tmb_model_spec.R

@@ -254,50 +254,59 @@ must_save_time_args = function(formulas) {
 #' Specify a simulation model in the TMB engine. A detailed explanation of this
 #' function is covered in `vignette("quickstart")`.
 #' 
-#' @param before List of expressions to be evaluated (in the order provided)
-#' before the simulation loop begins. Expressions can either be standard
-#' R \code{\link{formula}} objects or calls to flow functions (e.g., 
-#' \code{\link{mp_per_capita_flow}}). Formulas must have a left hand
-#' side that gives the name of the matrix being updated, and a right hand side
-#' giving an expression containing only (1) the names of quantities in the 
-#' model, (2) functions defined in the TMB engine, and (3) numerical literals 
-#' (e.g., \code{3.14}). The available functions in the TMB engine  can be 
-#' described in \code{\link{engine_functions}}. Names can be provided for the 
-#' components of \code{before}, and these names do not have to be unique. These 
-#' names are used by the \code{sim_exprs} argument.
+#' @param before List of formulas to be evaluated (in the order provided)
+#' before the simulation loop begins. These formulas must be standard 
+#' two-sided R \code{\link{formula}} objects. See `details` below for the 
+#' rules for these formulas.
 #' @param during List of formulas or calls to flow functions (e.g., 
 #' \code{\link{mp_per_capita_flow}}) to be evaluated at every iteration of the
-#' simulation loop, with the same rules as \code{before}.
-#' @param after List of formulas or calls to flow functions (e.g., 
-#' \code{\link{mp_per_capita_flow}}) to be evaluated after the simulation loop,
-#' with the same rules as \code{before}.
+#' simulation loop.
+#' @param after List of formulas to be evaluated (in the order provided)
+#' before the simulation loop begins. These formulas must be standard 
+#' two-sided R \code{\link{formula}} objects. See `details` below for the 
+#' rules for these formulas.
 #' @param default Named list of objects, each of which can be coerced into 
 #' a \code{\link{numeric}} \code{\link{matrix}}. The names refer to 
 #' variables that appear in \code{before}, \code{during}, and \code{after}.
 #' @param integers Named list of vectors that can be coerced to integer
 #' vectors. These integer vectors can be used by name in model formulas to
 #' provide indexing of matrices and as grouping factors in 
 #' \code{\link{group_sums}}.
-#' @param must_save Character vector of the names of matrices that must have 
+#' @param must_save Character vector of the names of variables that must have 
 #' their values stored at every iteration of the simulation loop. For example,
-#' a matrix that the user does not want to be returned but that impacts dynamics
-#' with a time lag must be saved and therefore in this list.
-#' @param must_not_save Character vector of the names of matrices that must
+#' a variable that you do not want to be returned, but that impacts 
+#' dynamics with a time lag, must be saved and therefore must be in this list.
+#' @param must_not_save Character vector of the names of variables that must
 #' not have their values stored at every iteration of the simulation loop. For
 #' example, the user may ask to return a very large matrix that would create
 #' performance issues if stored at each iteration. The creator of the model
-#' can mark such matrices making it impossible for the user of the model to
+#' can mark such variables making it impossible for the user of the model to
 #' save their full simulation history.
 #' @param sim_exprs Character vector of the names of \code{before}, 
 #' \code{during}, and \code{after} expressions that must only be evaluated 
 #' when simulations are being produced and not when the objective function is
 #' being evaluated. For example, expressions that generate stochasticity should
 #' be listed in \code{sim_exprs} because TMB objective functions must be
 #' continuous.
-#' @param state_update (experimental) Optional character vector for how to 
-#' update the state variables when it is relevant. Options include `"euler"`, 
+#' @param state_update Optional character vector for how to update the state 
+#' variables when it is relevant. Options include `"euler"` (the default), 
 #' `"rk4"`, and `"euler_multinomial"`.
 #' 
+#' @details
+#' Expressions in the `before`, `during`, and `after` lists can be standard 
+#' R \code{\link{formula}} objects for defining variables in the model. These
+#' formulas must have a left hand side that gives the name of the (possibly 
+#' matrix-valued) variable being updated, and a right hand side giving an 
+#' expression containing only (1) the names of quantities in the model, (2) 
+#' numerical literals (e.g., \code{3.14}), or (3) functions defined in the TMB 
+#' engine (described in \code{\link{engine_functions}}). For example, the
+#' expression `N ~ S + I + R` updates the value of `N` to be the sum of the
+#' variables `S`, `I`, and `R`.
+#' 
+#' Names can be provided for the components of the `before`, `during`, and
+#' `after` lists, and these names do not have to be unique. These names are 
+#' used by the \code{sim_exprs} argument.
+#' 
 #' @examples
 #' ## A simple SI model.
 #' spec = mp_tmb_model_spec(
@@ -337,8 +346,6 @@ must_save_time_args = function(formulas) {
 #'   |> mp_trajectory()
 #' )
 #' 
-#' 
-#' 
 #' @concept create-model-spec
 #' @export
 mp_tmb_model_spec = TMBModelSpec