From a77e6f03f49ddef15d73e74c6dbe3147f06858b0 Mon Sep 17 00:00:00 2001 From: Kyle Baron Date: Wed, 9 Oct 2024 11:43:14 -0500 Subject: [PATCH] documentation --- R/chain.R | 106 ++++++++++++++++++++++++----------------------- R/class_mrgmod.R | 2 +- R/env.R | 2 +- R/events.R | 16 ++++--- R/mrgsim_q.R | 2 +- R/nmxml.R | 2 +- R/utils.R | 44 ++++++++++---------- man/Req.Rd | 20 ++++----- man/env_ls.Rd | 2 +- man/ev_seq.Rd | 15 ++++--- man/obsonly.Rd | 2 +- man/simargs.Rd | 12 +++--- man/tscale.Rd | 12 +++--- 13 files changed, 118 insertions(+), 119 deletions(-) diff --git a/R/chain.R b/R/chain.R index bf7a2a1d7..498a00605 100644 --- a/R/chain.R +++ b/R/chain.R @@ -16,34 +16,35 @@ # along with mrgsolve. If not, see . -##' 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 are 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,12 +53,12 @@ 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 @@ -104,25 +105,26 @@ carry.out <- function(x,...) { 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 @@ -131,7 +133,7 @@ tscale <- function(x,value=1,...) { #' Collect only observation records in the simulated output #' #' @param x model object. -#' @param value the value for `obsonly`. +#' @param value use `TRUE` to collect and return observation records only. #' @param ... not used. #' #' @details diff --git a/R/class_mrgmod.R b/R/class_mrgmod.R index 403932006..7253e57e3 100644 --- a/R/class_mrgmod.R +++ b/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. # diff --git a/R/env.R b/R/env.R index 8f1ce2693..57698ac81 100644 --- a/R/env.R +++ b/R/env.R @@ -39,7 +39,7 @@ env_eval <- function(x,seed=NULL) { #' Each model keeps an internal environment that allows the user #' to carry any `R` object along. Objects are coded in `$ENV`. #' -#' @param x amodel object. +#' @param x a model object. #' @param ... passed to [ls()]. #' #' @md diff --git a/R/events.R b/R/events.R index c81ab555c..c7f379f12 100644 --- a/R/events.R +++ b/R/events.R @@ -554,14 +554,13 @@ ev_repeat <- function(x, n, wait = 0, as.ev = FALSE) { #' Use this function when you want to schedule two or more event objects in time #' according the dosing interval (`ii`) and additional doses (`addl`). #' -#' @param ... Event objects or numeric arguments named `wait` or `ii` to -#' implement a period of no-dosing activity in the sequence (see details). -#' @param ID Numeric vector of subject IDs. -#' @param .dots A list of event objects that replaces `...`. -#' @param id Deprecated; use `ID`. +#' @param ... event objects or numeric arguments named `wait` or `ii` to +#' implement a period of no-dosing activity in the sequence (see **Details**). +#' @param ID numeric vector of subject IDs. +#' @param .dots a list of event objects that replaces `...`. +#' @param id deprecated; use `ID`. #' #' @details -#' #' Use the generic [seq()] when the first argument is an event object. If a #' waiting period (`wait` or `ii`) is the first event, you will need to use #' [ev_seq()]. When an event object has multiple rows, the end time for that @@ -570,7 +569,7 @@ ev_repeat <- function(x, n, wait = 0, as.ev = FALSE) { #' #' The doses for the next event line start after all of the doses from the #' previous event line plus one dosing interval from the previous event line -#' (see examples). +#' (see **Examples**). #' #' When numerics named `wait` or `ii` are mixed in with the event objects, #' a period with no dosing activity is incorporated into the sequence, @@ -595,10 +594,9 @@ ev_repeat <- function(x, n, wait = 0, as.ev = FALSE) { #' warning if you use `.ii`. Please use `ii` instead. #' #' Values for `time` in any event object act like a prefix time spacer wherever -#' that event occurs in the event sequence (see examples). +#' that event occurs in the event sequence (see **Examples**). #' #' @examples -#' #' e1 <- ev(amt = 100, ii = 12, addl = 1) #' #' e2 <- ev(amt = 200) diff --git a/R/mrgsim_q.R b/R/mrgsim_q.R index 0867ee8c9..e2d2c8870 100644 --- a/R/mrgsim_q.R +++ b/R/mrgsim_q.R @@ -1,4 +1,4 @@ -# Copyright (C) 2013 - 2020 Metrum Research Group +# Copyright (C) 2013 - 2024 Metrum Research Group # # This file is part of mrgsolve. # diff --git a/R/nmxml.R b/R/nmxml.R index ad0fe2fa8..7374ea9ff 100644 --- a/R/nmxml.R +++ b/R/nmxml.R @@ -1,4 +1,4 @@ -# Copyright (C) 2013 - 2023 Metrum Research Group +# Copyright (C) 2013 - 2024 Metrum Research Group # # This file is part of mrgsolve. # diff --git a/R/utils.R b/R/utils.R index 60b45e14c..f50ddfedb 100644 --- a/R/utils.R +++ b/R/utils.R @@ -330,28 +330,28 @@ cvec.character <- as.cvec ##' @keywords internal s_ <- function(...) as.character(match.call(expand.dots=TRUE))[-1] #nocov -##' Access or clear arguments for calls to mrgsim -##' -##' As a model object navigates a pipeline prior to simulation, arguments are -##' collected to eventually be passed to [mrgsim()]. `simargs` lets you -##' intercept and possibly clear those arguments. -##' -##' @param x model object -##' @param clear logical indicating whether or not to clear `args` from -##' the model object -##' @param which character with length 1 naming a single arg to get -##' @param ... passed along -##' -##' @return If `clear` is `TRUE`, the argument list is -##' cleared and the model object is returned. Otherwise, the argument -##' list is returned. -##' -##' @examples -##' mod <- mrgsolve::house() -##' mod %>% Req(CP, RESP) %>% carry_out(evid, WT, FLAG) %>% simargs() -##' -##' @md -##' @export +#' Access or clear arguments for calls to mrgsim() +#' +#' As a model object navigates a pipeline prior to simulation, arguments are +#' collected to eventually be passed to [mrgsim()]. `simargs()` lets you +#' intercept and possibly clear those arguments. +#' +#' @param x model object. +#' @param clear logical indicating whether or not to clear `args` from +#' the model object. +#' @param which character with length 1 naming a single arg to get. +#' @param ... not used. +#' +#' @return If `clear` is `TRUE`, the argument list is +#' cleared and the model object is returned. Otherwise, the argument +#' list is returned. +#' +#' @examples +#' mod <- mrgsolve::house() +#' mod %>% Req(CP, RESP) %>% carry_out(evid, WT, FLAG) %>% simargs() +#' +#' @md +#' @export simargs <- function(x, which = NULL, clear = FALSE,...) { if(clear) { diff --git a/man/Req.Rd b/man/Req.Rd index bfb5d62f1..08dfcb135 100644 --- a/man/Req.Rd +++ b/man/Req.Rd @@ -13,31 +13,31 @@ req(x, ...) \method{req}{mrgmod}(x, ...) } \arguments{ -\item{x}{model object} +\item{x}{model object.} -\item{...}{unquoted names of compartments or tabled items} +\item{...}{unquoted names of compartments or tabled items.} } \description{ -Use this function to select, by name, either compartments or derived -variables that have been captured (see \code{\link{CAPTURE}}) into +Use this function to select, by name, either compartments or derived +variables that have been captured (see \link{CAPTURE}) into the simulated output. } \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 +There is also a \code{Req} argument to \code{\link[=mrgsim]{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 +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 +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 +mod \%>\% Req(CP,RESP) \%>\% ev(amt=1000) \%>\% mrgsim() } diff --git a/man/env_ls.Rd b/man/env_ls.Rd index f29dc3368..63b4caccf 100644 --- a/man/env_ls.Rd +++ b/man/env_ls.Rd @@ -7,7 +7,7 @@ env_ls(x, ...) } \arguments{ -\item{x}{amodel object.} +\item{x}{a model object.} \item{...}{passed to \code{\link[=ls]{ls()}}.} } diff --git a/man/ev_seq.Rd b/man/ev_seq.Rd index 415b83a23..257da6374 100644 --- a/man/ev_seq.Rd +++ b/man/ev_seq.Rd @@ -10,14 +10,14 @@ ev_seq(..., ID = NULL, .dots = NULL, id = NULL) \method{seq}{ev}(...) } \arguments{ -\item{...}{Event objects or numeric arguments named \code{wait} or \code{ii} to -implement a period of no-dosing activity in the sequence (see details).} +\item{...}{event objects or numeric arguments named \code{wait} or \code{ii} to +implement a period of no-dosing activity in the sequence (see \strong{Details}).} -\item{ID}{Numeric vector of subject IDs.} +\item{ID}{numeric vector of subject IDs.} -\item{.dots}{A list of event objects that replaces \code{...}.} +\item{.dots}{a list of event objects that replaces \code{...}.} -\item{id}{Deprecated; use \code{ID}.} +\item{id}{deprecated; use \code{ID}.} } \value{ A single event object sorted by \code{time}. @@ -35,7 +35,7 @@ on the last row of the event object. The doses for the next event line start after all of the doses from the previous event line plus one dosing interval from the previous event line -(see examples). +(see \strong{Examples}). When numerics named \code{wait} or \code{ii} are mixed in with the event objects, a period with no dosing activity is incorporated into the sequence, @@ -61,10 +61,9 @@ For now, both \code{ii} and \code{.ii} will be accepted but you will get a depre warning if you use \code{.ii}. Please use \code{ii} instead. Values for \code{time} in any event object act like a prefix time spacer wherever -that event occurs in the event sequence (see examples). +that event occurs in the event sequence (see \strong{Examples}). } \examples{ - e1 <- ev(amt = 100, ii = 12, addl = 1) e2 <- ev(amt = 200) diff --git a/man/obsonly.Rd b/man/obsonly.Rd index 1a26e17b3..733f69bcf 100644 --- a/man/obsonly.Rd +++ b/man/obsonly.Rd @@ -9,7 +9,7 @@ obsonly(x, value = TRUE, ...) \arguments{ \item{x}{model object.} -\item{value}{the value for `obsonly`.} +\item{value}{use `TRUE` to collect and return observation records only.} \item{...}{not used.} } diff --git a/man/simargs.Rd b/man/simargs.Rd index 3773d12d9..c747e871c 100644 --- a/man/simargs.Rd +++ b/man/simargs.Rd @@ -2,19 +2,19 @@ % Please edit documentation in R/utils.R \name{simargs} \alias{simargs} -\title{Access or clear arguments for calls to mrgsim} +\title{Access or clear arguments for calls to mrgsim()} \usage{ simargs(x, which = NULL, clear = FALSE, ...) } \arguments{ -\item{x}{model object} +\item{x}{model object.} -\item{which}{character with length 1 naming a single arg to get} +\item{which}{character with length 1 naming a single arg to get.} \item{clear}{logical indicating whether or not to clear \code{args} from -the model object} +the model object.} -\item{...}{passed along} +\item{...}{not used.} } \value{ If \code{clear} is \code{TRUE}, the argument list is @@ -23,7 +23,7 @@ list is returned. } \description{ As a model object navigates a pipeline prior to simulation, arguments are -collected to eventually be passed to \code{\link[=mrgsim]{mrgsim()}}. \code{simargs} lets you +collected to eventually be passed to \code{\link[=mrgsim]{mrgsim()}}. \code{simargs()} lets you intercept and possibly clear those arguments. } \examples{ diff --git a/man/tscale.Rd b/man/tscale.Rd index 89cb3ad03..32cd2da77 100644 --- a/man/tscale.Rd +++ b/man/tscale.Rd @@ -7,18 +7,18 @@ tscale(x, value = 1, ...) } \arguments{ -\item{x}{model object} +\item{x}{model object.} -\item{value}{value by which time will be scaled} +\item{value}{value by which time will be scaled.} -\item{...}{passed along} +\item{...}{not used.} } \description{ Re-scale time in the simulated output } \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 +There is also a \code{tscale} argument to \code{\link[=mrgsim]{mrgsim()}} that can +be set to accomplish the same thing as a call to \code{tscale} in the pipeline. } \examples{ @@ -26,6 +26,6 @@ the pipeline. mod <- mrgsolve::house() # The output is in days: -mod \%>\% tscale(1/24) \%>\% mrgsim +mod \%>\% tscale(1/24) \%>\% mrgsim() }