Extensive documentation updates (fix #81)

NEWS.md

@@ -21,6 +21,7 @@ the dosing including dose amount and route.
 * `PKNCAdata()` is more restrictive on unknown arguments issuing an error
   when unknonwn arguments are present.
 * `intervals` argument to `PKNCAdata()` may now be a tibble (fixes #72).
+* Documentation has been extensively updated (fixes #81).
 
 # PKNCA 0.8.5
 

R/001-add.interval.col.R

@@ -71,6 +71,7 @@ assign("interval.cols", list(), envir=.PKNCAEnv)
 #'                  depends=c("cmax"))
 #' }
 #' @importFrom utils getAnywhere
+#' @family Interval specifications
 #' @export
 add.interval.col <- function(name,
                              FUN,
@@ -186,6 +187,7 @@ sort.interval.cols <- function() {
 #'   Calculation Intervals"
 #' @examples
 #' get.interval.cols()
+#' @family Interval specifications
 #' @export
 get.interval.cols <- function() {
   sort.interval.cols()

R/002-pk.business.rules.R

@@ -54,12 +54,14 @@ geomean <- function(x, na.rm=FALSE) {
   }
 }
 
-#' @describeIn geomean Compute the geometric standard deviation.
+#' @describeIn geomean Compute the geometric standard deviation,
+#'   \code{exp(sd(log(x)))}.
 #' @export
 geosd <- function(x, na.rm=FALSE)
   exp(stats::sd(log(x), na.rm=na.rm))
 
-#' @describeIn geomean Compute the geometric coefficient of variation.
+#' @describeIn geomean Compute the geometric coefficient of variation,
+#'   \code{sqrt(exp(sd(log(x))^2)-1)*100}.
 #' @export
 geocv <- function(x, na.rm=FALSE)
   sqrt(exp(stats::sd(log(x), na.rm=na.rm)^2)-1)*100

R/PKNCA.options.R

@@ -311,7 +311,7 @@
 #'   \item{a single value is requested}{the current value of that option is returned as a scalar} 
 #'   \item{multiple values are requested}{the current values of those options are returned as a list}
 #' }
-#' @seealso \code{\link{PKNCA.choose.option}}
+#' @family PKNCA calculation and summary settings
 #' @examples
 #' 
 #' PKNCA.options()
@@ -404,7 +404,7 @@ PKNCA.options <- function(..., default=FALSE, check=FALSE, name, value) {
 #' @param options The non-default options to choose from.
 #' @return The value of the option first from the \code{options} list and if it
 #'   is not there then from the current settings.
-#' @seealso \code{\link{PKNCA.options}}
+#' @family PKNCA calculation and summary settings
 #' @export
 PKNCA.choose.option <- function(name, value=NULL, options=list())
   if (!is.null(value)) {
@@ -446,6 +446,7 @@ PKNCA.options.describe <- function(name) {
 #' @param reset Reset all the summary instructions
 #' @return All current summary settings (invisibly)
 #' @seealso \code{\link{summary.PKNCAresults}}
+#' @family PKNCA calculation and summary settings
 #' @export
 PKNCA.set.summary <- function(name, point, spread, rounding=list(signif=3),
                               reset=FALSE) {

R/auc.R

@@ -45,8 +45,8 @@
 #'   passed to \code{pk.calc.auxc}
 #' @return A numeric value for the AU(M)C
 #' @aliases pk.calc.auc pk.calc.aumc pk.calc.auc.last
-#' @seealso \code{\link{pk.calc.auc.all}}, \code{\link{pk.calc.auc.last}},
-#'   \code{\link{clean.conc.blq}}
+#' @family AUC calculations
+#' @seealso \code{\link{clean.conc.blq}}
 #' @references
 #' 
 #' Gabrielsson J, Weiner D.  "Section 2.8.1 Computation methods - Linear

R/aucint.R

@@ -29,8 +29,8 @@
 #'   \code{interp.extrap.conc}
 #' @param options List of changes to the default
 #'   \code{\link{PKNCA.options}} for calculations.
-#' @seealso \code{\link{pk.calc.auxc}}, \code{\link{PKNCA.options}},
-#'   \code{\link{interp.extrap.conc.dose}}
+#' @family AUC calculations
+#' @seealso \code{\link{PKNCA.options}}, \code{\link{interp.extrap.conc.dose}}
 #' @export
 pk.calc.aucint <- function(conc, time,
                            interval=NULL, start=NULL, end=NULL,

R/check.intervals.R

@@ -16,14 +16,13 @@
 #' @return x The potentially updated data frame with the interval 
 #'   calculation specification.
 #'
-#' @seealso \code{\link{check.interval.deps}}, \code{\link{get.parameter.deps}},
-#'   \code{\link{get.interval.cols}}, and the vignette "Selection of Calculation
-#'   Intervals"
+#' @family Interval specifications
+#' @seealso The vignette "Selection of Calculation Intervals"
 #' @export
 check.interval.specification <- function(x) {
   if (!is.data.frame(x)) {
-    ## Just a warning and let as.data.frame make it an error if
-    ## it can't be coerced.
+    # Just a warning and let as.data.frame make it an error if it can't be
+    # coerced.
     warning("Interval specification must be a data.frame")
     x <- as.data.frame(x, stringsAsFactors=FALSE)
   }
@@ -94,6 +93,7 @@ check.interval.specification <- function(x) {
 #' @return A character vector of parameter names that depend on the 
 #'   parameter \code{x}.  If none depend on \code{x}, then the result 
 #'   will be an empty vector.
+#' @family Interval specifications
 #' @export
 get.parameter.deps <- function(x) {
   all.intervals <- get.interval.cols()
@@ -166,15 +166,15 @@ get.parameter.deps <- function(x) {
 #' @param x A data frame with one or morw rows of the PKNCA interval
 #' @return The interval specification with additional calculations
 #' added where requested outputs require them.
-#' @seealso \code{\link{check.interval.specification}}
+#' @family Interval specifications
 check.interval.deps <- function(x) {
-  ## Ensure that the input is a valid interval specification
+  # Ensure that the input is a valid interval specification
   ret <- check.interval.specification(x)
   colspec <- get.interval.cols()
   for (n in names(colspec)) {
     if (is.logical(ret[,n])) {
-      ## This is a calculation to complete, otherwise it's something
-      ## informative but not caluclated.
+      # This is a calculation to complete, otherwise it's something informative
+      # but not caluclated.
       mask.calculated <- ret[,n]
       for (deps in colspec[[n]]$depends)
         ret[,deps] <- mask.calculated | ret[,deps]

R/choose.intervals.R

@@ -23,9 +23,10 @@
 #' \code{auc.type}, and \code{half.life}.  See
 #' \code{\link{check.interval.specification}} for column definitions.
 #' The data frame may have zero rows if no intervals could be found.
+#' @family Interval specifications
+#' @family Interval determination
 #' @seealso \code{\link{pk.calc.auc}}, \code{\link{pk.calc.aumc}},
-#' \code{\link{pk.calc.half.life}}, \code{\link{find.tau}},
-#' \code{\link{check.interval.specification}}, \code{\link{PKNCA.options}}
+#' \code{\link{pk.calc.half.life}}, \code{\link{PKNCA.options}}
 #' @export
 choose.auc.intervals <- function(time.conc, time.dosing,
                                  options=list(),
@@ -126,6 +127,7 @@ choose.auc.intervals <- function(time.conc, time.dosing,
 #'   \item If none of the \code{choices} can minimize the number of
 #'         unique values, then -1 is returned.
 #' }
+#' @family Interval determination
 #' @export
 find.tau <- function(x, na.action=na.omit,
                      options=list(),

R/class-PKNCAconc.R

@@ -34,7 +34,7 @@
 #'   those points and bypassing automatic point selection).
 #' @param ... Ignored.
 #' @return A PKNCAconc object that can be used for automated NCA.
-#' @seealso \code{\link{PKNCAdata}}, \code{\link{PKNCAdose}}
+#' @family PKNCA objects
 #' @export
 PKNCAconc <- function(data, ...)
   UseMethod("PKNCAconc")

R/class-PKNCAdata.R

@@ -28,8 +28,8 @@
 #' @details If \code{data.dose} is not given or is \code{NA}, then the 
 #'   \code{intervals} must be given.  At least one of \code{data.dose}
 #'   and \code{intervals} must be given.
-#' @seealso \code{\link{PKNCAconc}}, \code{\link{PKNCAdose}}, 
-#'   \code{\link{choose.auc.intervals}}, \code{\link{pk.nca}}
+#' @family PKNCA objects
+#' @seealso \code{\link{choose.auc.intervals}}, \code{\link{pk.nca}}
 #' @export
 PKNCAdata <- function(data.conc, data.dose, ...)
   UseMethod("PKNCAdata", data.conc)

R/class-PKNCAdose.R

@@ -43,7 +43,7 @@
 #'   per group.  When the right side is missing, PKNCA assumes that the 
 #'   same dose is given in every interval.  When given as a two-sided 
 #'   formula
-#' @seealso \code{\link{PKNCAconc}}, \code{\link{PKNCAdata}}
+#' @family PKNCA objects
 #' @export
 PKNCAdose <- function(data, ...)
   UseMethod("PKNCAdose")

R/class-PKNCAresults.R

@@ -12,6 +12,7 @@
 #'   should have values of \code{NA} or \code{""} for concentrations to
 #'   include and non-empty text for concentrations to exclude.
 #' @return A PKNCAresults object with each of the above within.
+#' @family PKNCA objects
 #' @export
 PKNCAresults <- function(result, data, exclude) {
   ## Add all the parts into the object

R/class-general.R

@@ -8,6 +8,7 @@ nlme::getGroups
 #' @param x The object to extract the formula from
 #' @param \dots Unused
 #' @return The vector of the dependent variable from the object.
+#' @family PKNCA object extractors
 #' @export
 getDepVar <- function(x, ...)
   UseMethod("getDepVar", x)
@@ -18,6 +19,7 @@ getDepVar <- function(x, ...)
 #' @param x The object to extract the formula from
 #' @param \dots Unused
 #' @return The vector of the independent variable from the object.
+#' @family PKNCA object extractors
 #' @export
 getIndepVar <- function(x, ...)
   UseMethod("getIndepVar", x)
@@ -54,6 +56,7 @@ getColumnValueOrNot <- function(data, value, prefix="X") {
 #' object.
 #'
 #' @param object The object to get the data name from.
+#' @family PKNCA object extractors
 #' @return A character scalar with the name of the data object (or NULL
 #'   if the method does not apply).
 getDataName <- function(object)

R/cleaners.R

@@ -14,6 +14,7 @@
 #' @param check Run \code{\link{check.conc.time}}?
 #' @return The concentration and time measurements (data frame) filtered
 #'   and cleaned as requested relative to NA in the concentration.
+#' @family Data cleaners
 #' @export
 clean.conc.na <- function(conc, time, ...,
                           options=list(),
@@ -79,7 +80,7 @@ clean.conc.na <- function(conc, time, ...,
 #'   \item{a number}{Set the BLQ values to that number}
 #' }
 #'
-#' @seealso \code{\link{clean.conc.na}}
+#' @family Data cleaners
 #' @export
 clean.conc.blq <- function(conc, time,
                            ...,

R/exclude.R

@@ -30,6 +30,7 @@
 #'         reason="Carryover",
 #'         mask=c(TRUE, rep(FALSE, 6)))
 #' @export
+#' @family Result exclusions
 #' @importFrom dplyr "%>%"
 #' @importFrom dplyr n
 #' @importFrom rlang syms

R/exclude_nca.R

@@ -22,6 +22,7 @@
 #'                               FUN=exclude_nca_max.aucinf.pext())
 #' as.data.frame(my_result_excluded)
 #' @name exclude_nca
+#' @family Result exclusions
 NULL
 
 #' @describeIn exclude_nca Exclude based on span.ratio

R/half.life.R

@@ -70,6 +70,7 @@
 #' lambda-z."  Pharmacokinetic & Pharmacodynamic Data Analysis: Concepts
 #' and Applications, 4th Edition.  Stockholm, Sweden: Swedish 
 #' Pharmaceutical Press, 2000.  167-9.
+#' @family NCA parameter calculations
 #' @export
 pk.calc.half.life <- function(conc, time, tmax, tlast,
                               manually.selected.points=FALSE,

R/parseFormula.R

@@ -28,6 +28,7 @@
 #' ## parseFormula("a~b", require.groups=TRUE) # This is an error
 #' parseFormula("a~b|c")
 #' parseFormula("a~b|c")$groups
+#' @family Formula parsing
 #' @export
 parseFormula <- function (form,
                           require.groups=FALSE,
@@ -103,6 +104,7 @@ print.parseFormula <- function(x, ...) {
 #' dropping the left hand side?
 #' @param \dots Unused.
 #' @return A formula (optionally with portions removed)
+#' @family Formula parsing
 #' @export
 formula.parseFormula <- function(x, drop.groups=FALSE, drop.lhs=FALSE, ...) {
   if (identical(x$lhs, NA) | drop.lhs) {
@@ -127,6 +129,7 @@ formula.parseFormula <- function(x, drop.groups=FALSE, drop.lhs=FALSE, ...) {
 #' @return The side of the operator requested, NA if requesting the
 #' left side of a unary operator, and NULL if the operator is not
 #' found.
+#' @family Formula parsing
 #' @export
 findOperator <- function(x, op, side) {
   side <- match.arg(tolower(side),

R/pk.calc.all.R

@@ -14,7 +14,8 @@
 #' @param data A PKNCAdata object
 #' @return A \code{PKNCAresults} object.
 #' @seealso \code{\link{PKNCAdata}}, \code{\link{PKNCA.options}},
-#'  \code{\link{summary.PKNCAresults}}, \code{\link{as.data.frame.PKNCAresults}}
+#'  \code{\link{summary.PKNCAresults}}, \code{\link{as.data.frame.PKNCAresults}},
+#'  \code{\link{exclude}}
 #' @export
 #' @importFrom utils capture.output
 #' @importFrom dplyr bind_rows