Merge pull request #1246 from metrumresearchgroup/documentation

General updates to Rd documentation

DESCRIPTION

@@ -33,7 +33,7 @@ Description: Fast simulation from ordinary differential equation
     (ODE) based models typically employed in quantitative pharmacology and
     systems biology.
 License: GPL (>=2)
-URL: https://github.com/metrumresearchgroup/mrgsolve
+URL: https://mrgsolve.org/docs, https://github.com/metrumresearchgroup/mrgsolve
 BugReports: 
     https://github.com/metrumresearchgroup/mrgsolve/issues
 Depends:

R/chain.R

@@ -1,4 +1,4 @@
-# Copyright (C) 2013 - 2019  Metrum Research Group
+# Copyright (C) 2013 - 2024  Metrum Research Group
 #
 # This file is part of mrgsolve.
 #
@@ -16,34 +16,35 @@
 # along with mrgsolve.  If not, see <http://www.gnu.org/licenses/>.
 
 
-##' Request simulated output
-##' 
-##' Use this function to select, by name, either compartments or derived 
-##' variables that have been captured (see \code{\link{CAPTURE}}) into
-##' the simulated output.
-##'
-##' @param x model object
-##' @param ... unquoted names of compartments or tabled items
-##' 
-##' @details
-##' There is also a \code{Req} argument to \code{\link{mrgsim}} that can 
-##' be set to accomplish the same thing as a call to \code{Req} in 
-##' the pipeline.
-##' 
-##' Note the difference between \code{req} and \code{Req}: the former only 
-##' selects compartments to appear in output while the latter selects both 
-##' compartments and captured items.  Also, when there are items are explicitly
-##' listed in \code{Req}, all other compartments or captured items not listed
-##' there are ignored.  But when compartments are selected with \code{req}
-##' all of the captured items are returned.  Remember that \code{req} is 
-##' strictly for compartments.
-##' 
-##' @examples
-##' mod <- mrgsolve::house()
-##'
-##' mod %>% Req(CP,RESP) %>% ev(amt=1000) %>%  mrgsim
-##'
-##' @export
+#' Request simulated output
+#' 
+#' Use this function to select, by name, either compartments or derived 
+#' variables that have been captured (see [CAPTURE]) into
+#' the simulated output.
+#'
+#' @param x model object.
+#' @param ... unquoted names of compartments or tabled items.
+#' 
+#' @details
+#' There is also a `Req` argument to [mrgsim()] that can 
+#' be set to accomplish the same thing as a call to `Req` in 
+#' the pipeline.
+#' 
+#' Note the difference between `req` and `Req`: the former only 
+#' selects compartments to appear in output while the latter selects both 
+#' compartments and captured items.  Also, when there are items explicitly
+#' listed in `Req`, all other compartments or captured items not listed
+#' there are ignored.  But when compartments are selected with `req`
+#' all of the captured items are returned.  Remember that `req` is 
+#' strictly for compartments.
+#' 
+#' @examples
+#' mod <- mrgsolve::house()
+#'
+#' mod %>% Req(CP,RESP) %>% ev(amt=1000) %>%  mrgsim()
+#'
+#' @md
+#' @export
 Req <- function(x,...) UseMethod("Req")
 
 #' @export
@@ -52,85 +53,95 @@ Req.mrgmod <- function(x,...) {
   x  
 }
 
-##' @rdname Req
-##' @export
+#' @rdname Req
+#' @export
 req <- function(x,...) UseMethod("req")
 
-##' @export
-##' @rdname Req
+#' @export
+#' @rdname Req
 req.mrgmod <- function(x,...) {
   x <- update_request(x,as.character(match.call()[-1]))
   x
 }
 
-##' Select items to carry into simulated output
-##' 
-##' When items named in this function are found in the input data set (either 
-##' \code{\link{data_set}} or \code{\link{idata_set}}), they are copied
-##' into the simulated output.  Special items like \code{evid} or \code{amt} or
-##' the like are not copied from the data set per se, but they are copied from
-##' \code{datarecord} objects that are created during the simulation.
-##'
-##' @param x model object
-##' @param ... passed along
-##' 
-##' @details
-##' There is also a \code{carry.out} argument to \code{\link{mrgsim}} that can 
-##' be set to accomplish the same thing as a call to \code{carry_out} in 
-##' the pipeline.
-##' 
-##' \code{carry.out} and \code{carry_out}.  Using the underscore version is 
-##' now preferred.
-##' 
-##' @export
+#' Select items to carry into simulated output
+#' 
+#' When items named in this function are found in the input data set (either 
+#' [data_set()] or [idata_set()]), they are copied
+#' into the simulated output.  Special items like `evid` or `amt` or
+#' the like are not copied from the data set per se, but they are copied from
+#' `datarecord` objects that are created during the simulation.
+#'
+#' @param x model object.
+#' @param ... unquoted names of data items to copy into the simulated output.
+#' 
+#' @details
+#' There is also a `carry_out` argument to [mrgsim()] that can be set to 
+#' accomplish the same thing as a call to `carry_out` in the pipeline.
+#' 
+#' `carry.out` and `carry_out` both do the same thing; using the underscore 
+#' version is now preferred.
+#' 
+#' @examples
+#' mod <- mrgsolve::house()
+#' 
+#' e <- ev(amt = 100, ii = 6, addl = 3, WT = 70, dose = amt)
+#' 
+#' out <- mod %>% ev(e) %>% carry_out(amt, dose, WT) %>% mrgsim()
+#' 
+#' head(out)
+#' 
+#' @md
+#' @export
 carry_out <- function(x,...) {
   x@args[["carry_out"]] <- as_character_args(match.call()[-1])
   x
 }
 
-##' @export
-##' @rdname carry_out
+#' @export
+#' @rdname carry_out
 carry.out <- function(x,...) {
   x@args[["carry_out"]] <- as_character_args(match.call()[-1])
   x
 }
 
-##' Re-scale time in the simulated output
-##'
-##' @param x model object
-##' @param value value by which time will be scaled
-##' @param ... passed along
-##' 
-##' @details
-##' There is also a \code{tscale} argument to \code{\link{mrgsim}} that can 
-##' be set to accomplish the same thing as a call to \code{tscale} in 
-##' the pipeline.
-##' 
-##' @examples
-##' # The model is in hours:
-##' mod <- mrgsolve::house()
-##' 
-##' # The output is in days:
-##' mod %>% tscale(1/24) %>% mrgsim
-##' 
-##' @export
+#' Re-scale time in the simulated output
+#'
+#' @param x model object.
+#' @param value value by which time will be scaled.
+#' @param ... not used.
+#' 
+#' @details
+#' There is also a `tscale` argument to [mrgsim()] that can 
+#' be set to accomplish the same thing as a call to `tscale` in 
+#' the pipeline.
+#' 
+#' @examples
+#' # The model is in hours:
+#' mod <- mrgsolve::house()
+#' 
+#' # The output is in days:
+#' mod %>% tscale(1/24) %>% mrgsim()
+#' 
+#' @md
+#' @export
 tscale <- function(x,value=1,...) {
   x@args[["tscale"]] <- value
   x
 }
 
-##' Collect only observations in the simulated output
-##'
-##' @param x model object
-##' @param value the value for \code{obsonly}
-##' @param ... passed along
-##' 
-##' @details
-##' There is also a \code{obsonly} argument to \code{\link{mrgsim}} that can 
-##' be set to accomplish the same thing as a call to \code{obsonly} in 
-##' the pipeline.
-##' 
-##' @export
+#' Collect only observation records in the simulated output
+#'
+#' @param x model object.
+#' @param value use `TRUE` to collect and return observation records only.
+#' @param ... not used.
+#' 
+#' @details
+#' There is also an `obsonly` argument to [mrgsim()] that can 
+#' be set to accomplish the same thing as a call to `obsonly()` in 
+#' the pipeline.
+#' 
+#' @export
 obsonly <- function(x,value=TRUE,...) {
   x@args[["obsonly"]] <- value
   x

R/class_ev.R

@@ -1,4 +1,4 @@
-# Copyright (C) 2013 - 2022  Metrum Research Group
+# Copyright (C) 2013 - 2024  Metrum Research Group
 #
 # This file is part of mrgsolve.
 #
@@ -25,7 +25,7 @@
 #' If an event object, return `data` slot; otherwise, call as.data.frame. This 
 #' is supposed to be optimized for handling event objects. 
 #' 
-#' @param x An R object. 
+#' @param x an R object. 
 #' 
 #' @noRd
 to_data_frame <- function(x) {
@@ -90,12 +90,13 @@ is.ev <- function(x) {
   inherits(x, "ev")  
 }
 
-##' dplyr verbs for event objects
-##' 
-##' @param .data the event object
-##' @param ... passed to the \code{dplyr} function
-##' @rdname ev_dplyr
-##' @export
+#' dplyr verbs for event objects
+#' 
+#' @param .data the event object.
+#' @param ... passed to the `dplyr` function.
+#' @rdname ev_dplyr
+#' @md
+#' @export
 mutate.ev <- function(.data, ...) {
   input_cols <- names(match.call(expand.dots=TRUE))
   .data@data <- as.data.frame(mutate(.data@data, ...))
@@ -124,15 +125,15 @@ mutate.ev <- function(.data, ...) {
   .data
 }
 
-##' @rdname ev_dplyr
-##' @export
+#' @rdname ev_dplyr
+#' @export
 select.ev <- function(.data, ...) {
   .data@data <- as.data.frame(dplyr::select(.data@data, ...))
   .data 
 }
 
-##' @rdname ev_dplyr
-##' @export
+#' @rdname ev_dplyr
+#' @export
 filter.ev <-  function(.data, ...) {
   .data@data <- as.data.frame(dplyr::filter(.data@data, ...))
   .data

R/class_mrgmod.R

@@ -1,4 +1,4 @@
-# Copyright (C) 2013 - 2022 Metrum Research Group
+# Copyright (C) 2013 - 2024 Metrum Research Group
 #
 # This file is part of mrgsolve.
 #
@@ -379,7 +379,8 @@ as_pack_mod <- function(model, project, PACKAGE) {
 #' @param x any object
 #' 
 #' @examples
-#' is.mrgmod(house())
+#' mod <- mrgsolve::house()
+#' is.mrgmod(mod)
 #' 
 #' @return 
 #' `TRUE` if the object inherits from either `mrgmod` or `packmod` class.
@@ -405,7 +406,7 @@ setMethod("project", "packmod", function(x,...) {
 })
 
 #' @rdname cmtn
-#' @param tag compartment name
+#' @param tag compartment name.
 #' @export
 setMethod("cmtn", "mrgmod", function(x,tag,...) {
   return(which(cmt(x)==tag))
@@ -433,9 +434,9 @@ CAPTUREI <- function(x) c(length(x@capture),x@Icap-1L)
 #' This is also the directory where the model is built, which could be the 
 #' value of [tempdir()].
 #'
-#' @param x model object
-#' @param short logical; if `TRUE`, `soloc`s will
-#'  be rendered  with a short path name
+#' @param x model object.
+#' @param short logical; if `TRUE`, `soloc`s will be rendered  with a short 
+#' path name.
 #' 
 #' @examples
 #' mod <- mrgsolve::house()
@@ -490,16 +491,21 @@ setMethod("names", "mrgmod", function(x) {
 
 #' Coerce a model object to list
 #' 
-#' @param x mrgmod object
-#' @param deep if `TRUE`, extra information is returned
-#' (see details). 
-#' @param ... not used
+#' @param x a model object.
+#' @param deep if `TRUE`, extra information is returned in the output list
+#' (see **Details**). 
+#' @param ... not used.
 #' 
 #' @details 
-#' If `deep` is `TRUE`, then the values for
-#' `trans`,`advan`, and `mindt` are
-#' returned as well as a summary of internal model 
-#' functions (with a call to `mrgsolve:::funset`).
+#' If `deep` is `TRUE`, then the values for `trans`, `advan`, and `mindt` are
+#' returned as well as a summary of internal model functions (with a call to 
+#' `mrgsolve:::funset()`).
+#' 
+#' @examples
+#' mod <- mrgsolve::house()
+#' l <- as.list(mod)
+#' 
+#' @return A named list containing formatted contents from `x`.
 #' 
 #' @section Slots:
 #' - `npar`: number of parameters
@@ -836,9 +842,9 @@ all.equal.mrgmod <- function(target, current,...) {
 #' Outputs can include model compartments or variables defined in the model 
 #' that have been marked to `capture` in simulated output.
 #' 
-#' @param x mrgmod object
+#' @param x model object.
 #' @param unlist if `TRUE` then a character vector (rather than list) is 
-#' returned
+#' returned.
 #' 
 #' @return
 #' When `unlist` is `FALSE` (default) : a named list, with `cmt` showing names 
@@ -847,8 +853,8 @@ all.equal.mrgmod <- function(target, current,...) {
 #' of outvar names is returned.
 #' 
 #' @examples
-#' 
-#' outvars(mrgsolve::house())
+#' mod <- mrgsolve::house()
+#' outvars(mod)
 #' 
 #' @md
 #' @export