Merge pull request #114 from dd-harp/dev

Documentation, etc

NAMESPACE

@@ -216,8 +216,6 @@ S3method(dts_update,human)
 S3method(dts_update,mosy)
 S3method(foi2eir,nb)
 S3method(foi2eir,pois)
-S3method(get_Linits,basicL)
-S3method(get_Linits,trace)
 S3method(get_MYZinits,RM)
 S3method(get_MYZinits,RM_dts)
 S3method(get_MYZinits,basicM)

R/aquatic-basicL-xde.R → R/aquatic-basicL.R

@@ -148,15 +148,6 @@ update_Linits.basicL <- function(pars, y0, s) {
   return(pars)
 }
 
-#' @title Return initial values as a vector
-#' @description Implements [get_Linits] for the GeRM model.
-#' @inheritParams get_Linits
-#' @return none
-#' @export
-get_Linits.basicL <- function(pars, s=1){
-  pars$Linits[[s]]
-}
-
 #' @title Make inits for basicL competition aquatic mosquito model
 #' @param nHabitats the number of habitats in the model
 #' @param Lopts a [list] that overwrites default values

R/aquatic-interface.R

@@ -1,67 +1,58 @@
 # generic methods for aquatic component
 
-
-#' @title Derivatives for aquatic stage mosquitoes
-#' @description This method dispatches on the type of `pars$Lpar`.
+#' @title Compute Derivatives for \eqn{\cal L}
+#' @description This method computes and returns the derivatives
+#' for the \eqn{\cal L} dynamical component -- a model family
+#' describing immature mosquitoes in aquatic habitats
+#' @note Dispatches on the class of `pars$Lpar[[s]]`
 #' @param t current simulation time
 #' @param y state vector
 #' @param pars an **`xds`** object
 #' @param s the species index
-#' @return a [numeric] vector of length `pars$L_ix`
+#' @return the derivatives, a [numeric] vector of length \eqn{n_q=}`nHabitats`
 #' @export
 dLdt <- function(t, y, pars, s) {
   UseMethod("dLdt", pars$Lpar[[s]])
 }
 
-#' @title Compute the steady states as a function of the daily EIR
-#' @description This method dispatches on the type of `Lpar`.
-#' @param eta the egg-laying rate
-#' @param Lpar a list that defines an xde model
-#' @return none
+#' @title Update States for \eqn{\cal L}
+#' @description This method updates the state variables
+#' for the \eqn{\cal L} component -- immature mosquitoes
+#' in aquatic habitats
+#' @note Dispatches on the class of `pars$Lpar[[s]]`
+#' @param t current simulation time
+#' @param y state vector
+#' @param pars an **`xds`** object
+#' @param s the species index
+#' @return the states, a [numeric] vector of length \eqn{n_q=}`nHabitats`
 #' @export
-xde_steady_state_L = function(eta, Lpar){
-  UseMethod("xde_steady_state_L", Lpar)
+Update_Lt <- function(t, y, pars, s) {
+  UseMethod("Update_Lt", pars$Lpar[[s]])
 }
 
-#' @title A function to set up adult mosquito models
-#' @description This method dispatches on `Lname`.
+#' @title Create and configure **`Lpar`** for \eqn{\cal L}-Models
+#' @description
+#' Each instance of `make_Lpar` calls a function (usually `create_Lpar_*`) that
+#' creates an object **`Lpar`.**
+#' It is attached the **`xds`** object as `pars$Lpar[[s]].` Each instance of `create_Lpar_*`
+#' should assign default parameter values. These will be over-written by `Lopts`
+#' @note This method assigns `Lname` to class(`Lname`) and dispatches on `Lname`.
 #' @param Lname the class name of the aquatic model
 #' @param pars an **`xds`** object
 #' @param s the species index
-#' @param Lopts a [list]
+#' @param Lopts a named [list] to configure **`Lpar`**
 #' @return an **`xds`** object
 #' @export
 make_Lpar = function(Lname, pars, s, Lopts=list()){
   class(Lname) <- Lname
   UseMethod("make_Lpar", Lname)
 }
 
-
-#' @title Derivatives for aquatic stage mosquitoes
-#' @description This method dispatches on the type of `pars$Lpar`.
-#' @param t current simulation time
-#' @param y state vector
-#' @param pars an **`xds`** object
-#' @param s the species index
-#' @return a [numeric] vector of length `pars$L_ix`
-#' @export
-Update_Lt <- function(t, y, pars, s) {
-  UseMethod("Update_Lt", pars$Lpar[[s]])
-}
-
-#' @title Compute the steady states as a function of the daily EIR
-#' @description This method dispatches on the type of `Lpar`.
-#' @inheritParams xde_steady_state_L
-#' @return none
-#' @export
-dts_steady_state_L = function(eta, Lpar){
-  UseMethod("dts_steady_state_L", Lpar)
-}
-
 #' @title Set aquatic bionomic parameter rates relative to baseline
-#' @description This method dispatches on the type of `pars$Lpar`. It should
-#' compute the values of parameters as a function of exogenous variables
+#' @description It should compute the values of parameters
+#' as a function of exogenous variables
 #' or reset the values of the bionomic parameters to baseline values.
+#' @note This method dispatches on the class of `pars$Lpar[[s]]`
 #' @param t current simulation time
 #' @param y state vector
 #' @param pars an **`xds`** object
@@ -72,8 +63,10 @@ LBionomics <- function(t, y, pars, s) {
   UseMethod("LBionomics", pars$Lpar[[s]])
 }
 
-#' @title Number of newly emerging adults from each larval habitat
-#' @description This method dispatches on the type of `pars$Lpar`.
+#' @title Emerging adults
+#' @description This function computes the rate or number of emerging adults: a
+#' rate for differential equations, or a number for difference equations.
+#' @note This method dispatches on the class of `pars$Lpar[[s]]`
 #' @param t current simulation time
 #' @param y state vector
 #' @param pars an **`xds`** object
@@ -84,19 +77,21 @@ F_emerge <- function(t, y, pars, s) {
   UseMethod("F_emerge", pars$Lpar[[s]])
 }
 
-#' @title Return the variables as a list
-#' @description This method dispatches on the type of `pars$Lpar[[s]]`.
+#' @title Return \eqn{\cal L} variables as a list
+#' @description Extract the variables describing the states of \eqn{\cal L}
+#' for the \eqn{s^{th}} species and return them as a named list
+#' @note This method dispatches on the class of `pars$Lpar[[s]]`.
 #' @param y the variables
 #' @param pars an **`xds`** object
 #' @param s the vector species index
-#' @return a [list]
+#' @return a named [list]: the variables of \eqn{\cal L} by name
 #' @export
 list_Lvars <- function(y, pars, s) {
   UseMethod("list_Lvars", pars$Lpar[[s]])
 }
 
 #' @title Put Lvars in place of the L variables in y
-#' @description This method dispatches on the type of `pars$Lpar[[s]]`.
+#' @description This method dispatches on the class of `pars$Lpar[[s]]`.
 #' @param Lvars the L variables to insert into y
 #' @param y the variables
 #' @param pars an **`xds`** object
@@ -112,24 +107,24 @@ put_Lvars <- function(Lvars, y, pars, s) {
 #' @param pars an **`xds`** object
 #' @param s the species index
 #' @param Lopts a [list]
-#' @return an `xds` object
+#' @return an **`xds`** object
 #' @export
 make_Linits = function(pars, s, Lopts=list()){
   UseMethod("make_Linits", pars$Lpar[[s]])
 }
 
-#' @title Return initial values as a vector
-#' @description This method dispatches on the type of `pars$Lpar`.
+#' @title Get the stored initial values
+#' @note This method dispatches on the class of `pars$Lpar`.
 #' @param pars an **`xds`** object
 #' @param s the species index
-#' @return [list]
+#' @return a named [list]
 #' @export
 get_Linits <- function(pars, s=1) {
-  UseMethod("get_Linits", pars$Lpar[[s]])
+  pars$Linits[[s]]
 }
 
 #' @title Set the initial values from a vector of model states
-#' @description This method dispatches on the type of `pars$Lpar`.
+#' @description This method dispatches on the class of `pars$Lpar`.
 #' @param pars an **`xds`** object
 #' @param y0 a vector of variable values from a simulation
 #' @param s the species index
@@ -139,9 +134,8 @@ update_Linits <- function(pars, y0, s) {
   UseMethod("update_Linits", pars$Lpar[[s]])
 }
 
-
 #' @title Add indices for aquatic stage mosquitoes to parameter list
-#' @description This method dispatches on the type of `pars$Lpar`. Adds field `L_ix`
+#' @description This method dispatches on the class of `pars$Lpar`. Adds field `L_ix`
 #' to parameter list.
 #' @param pars an **`xds`** object
 #' @param s the species index
@@ -151,16 +145,38 @@ make_indices_L <- function(pars, s) {
   UseMethod("make_indices_L", pars$Lpar[[s]])
 }
 
-#' @title Parse the outputs of solving a dynamical system and return the variables by name in a list
-#' @description This method dispatches on the type of `pars$Lpar`. Attaches the
-#' state variables for the aquatic ecology model to a list and returns it
+#' @title Parse \eqn{\cal L} Outputs
+#' @description After solving a dynamical system, parse the outputs and
+#' return the variables by name in a list.
+#' @note This method dispatches on the class of `pars$Lpar[[s]]`
 #' @param outputs a [matrix] with the solutions to a dynamical system
 #' @param pars an **`xds`** object
 #' @param s the species index
+#' @return a [list]
 #' @export
 parse_outputs_L <- function(outputs, pars, s) {
   UseMethod("parse_outputs_L", pars$Lpar[[s]])
 }
 
+#' @title Steady States for \eqn{\cal L}
+#' @description For differential equation models, compute
+#' steady states as a function of daily eggs laid, \eqn{\eta}
+#' @note This method dispatches on the class of `Lpar`.
+#' @param eta the egg-laying rate
+#' @param Lpar a list that defines an xde model
+#' @return a named [list]: values of the state variables at the steady state
+#' @export
+xde_steady_state_L = function(eta, Lpar){
+  UseMethod("xde_steady_state_L", Lpar)
+}
 
-
+#' @title Steady States for \eqn{\cal L}
+#' @description For discrete time systems, compute
+#' steady states as a function of daily eggs laid, \eqn{\eta}
+#' @note This method dispatches on the class of `Lpar`.
+#' @inheritParams xde_steady_state_L
+#' @return a named [list]: values of the state variables at the steady state
+#' @export
+dts_steady_state_L = function(eta, Lpar){
+  UseMethod("dts_steady_state_L", Lpar)
+}

R/aquatic-trace.R

@@ -3,7 +3,7 @@
 #' @title Reset aquatic parameters to baseline
 #' @description Implements [LBionomics] for the RM model
 #' @inheritParams LBionomics
-#' @return a named [list]
+#' @return an **`xds`** object
 #' @export
 LBionomics.trace <- function(t, y, pars, s) {
   return(pars)
@@ -90,7 +90,7 @@ create_Lpar_trace = function(nHabitats, Lopts=list(), Lambda=1000, Lt = NULL){
     return(Lpar)
   })}
 
-#' @title Setup the trace model
+#' @title Setup \eqn{\cal L}-trace
 #' @description Implements [make_Linits] for the trace model
 #' @inheritParams make_Linits
 #' @return a [list]
@@ -100,8 +100,6 @@ make_Linits.trace = function(pars, s, Lopts=list()){
   return(pars)
 }
 
-
-
 #' @title Add indices for aquatic stage mosquitoes to parameter list
 #' @description Implements [make_indices_L] for trace (forced emergence) model.
 #' @inheritParams make_indices_L
@@ -111,18 +109,6 @@ make_indices_L.trace <- function(pars, s) {
   return(pars)
 }
 
-
-
-
-#' @title Return initial values as a vector
-#' @description Implements [get_Linits] for the GeRM model.
-#' @inheritParams get_Linits
-#' @return none
-#' @export
-get_Linits.trace <- function(pars, s=1){
-  numeric(0)
-}
-
 #' @title Update inits for the basic aquatic mosquito competition model
 #' @inheritParams update_Linits
 #' @return none

R/emergence.R

@@ -4,7 +4,7 @@
 #' @param t the time
 #' @param y the state variables
 #' @param pars a `xds` object
-#' @return a [list] -- the modified `xds` object
+#' @return an `xds` object
 #' @export
 Emergence = function(t, y, pars){
   for(s in 1:pars$nVectors)

R/runtime.R

@@ -1,5 +1,5 @@
 
-#' @title Set up runtime time step support for `dts` models
+#' @title Set up run-time time step support for `dts` models
 #' @description Set the time steps for various discrete time models
 #' @param pars an `xds` object
 #' @param Xday is the run-time time step for X component (in days): integer or 1/integer
@@ -12,8 +12,8 @@ make_runtime = function(pars, Xday, MYZday, Lday, Lname){
   UseMethod("make_runtime", pars$xds)
 }
 
-#' @title Set up runtime time step support for `xde` models
-#' @description Continuous time models don't use runtime support,
+#' @title Set up run-time time step support for `xde` models
+#' @description Continuous time models don't use run-time support,
 #' so this returns the `xds` object without modification
 #' @inheritParams make_runtime
 #' @return the unmodified `xds` object
@@ -23,7 +23,7 @@ make_runtime.xde= function(pars, Xday, MYZday, Lday, Lname){
   return(pars)
 }
 
-#' @title Set up runtime time step support for `dts` models
+#' @title Set up run-time time step support for `dts` models
 #' @description Set the time steps for various discrete time models
 #' @inheritParams make_runtime
 #' @return the unmodified `xds` object
@@ -64,11 +64,11 @@ set_Dday = function(Xday, MYZday, Lday, Lname="trace"){
 }
 
 
-#' @title A runtime switch function for mismatched dynamical component runtimes
+#' @title A run-time switch function for mismatched dynamical component run-times
 #' @description Determine whether to update the variables at time t
 #' @param t current simulation time
-#' @param Dday the runtime time step for the simulation
-#' @param xday the runtime time step for a component
+#' @param Dday the run-time time step for the simulation
+#' @param xday the run-time time step for a component
 #' @return [logical] TRUE or FALSE
 #' @export
 runt = function(t, Dday, xday){

R/xds_setup.R

@@ -286,6 +286,7 @@ xds_setup_human = function(xds = 'xde', dlay = 'ode',
 
   # Aquatic Mosquito Dynamics
   pars       <- make_Lpar("trace", pars, 1, list())
+  pars       <- make_Linits(pars, 1)
 
   # Mosquito Dynamics
   pars           <- make_MYZpar("trace", pars, 1, MYZopts)
@@ -364,6 +365,7 @@ xds_setup_cohort = function(F_eir,
 
   # Aquatic Mosquito Dynamics
   pars       <- make_Lpar("trace", pars, 1, list())
+  pars       <- make_Linits(pars, 1)
 
   # Adult Mosquito Dynamics
   pars           <- make_MYZpar("trace", pars, 1, list())

_pkgdown.yml

@@ -410,7 +410,6 @@ reference:
   - put_Lvars.trace
   - make_indices_L.trace
   - parse_outputs_L.trace
-  - get_Linits.trace
   - update_Linits.trace
 - subtitle: basicL
   desc: |
@@ -428,7 +427,6 @@ reference:
   - list_Lvars.basicL
   - make_indices_L.basicL
   - parse_outputs_L.basicL
-  - get_Linits.basicL
   - update_Linits.basicL
 - title: Mosquito Bionomics
   desc: |