more documentation modernization

R/class_mrgmod.R

@@ -836,9 +836,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 +847,8 @@ all.equal.mrgmod <- function(target, current,...) {
 #' of outvar names is returned.
 #' 
 #' @examples
-#' 
-#' outvars(mrgsolve::house())
+#' mod <- house()
+#' outvars(mod)
 #' 
 #' @md
 #' @export

R/data_set.R

@@ -183,13 +183,14 @@ setMethod("data_set", c("mrgmod", "missing"), function(x, object, ...) {
 #' If both lower and upper case versions of the name are present in the data 
 #' frame, no changes will be made. 
 #' 
-#' @param data a data set with nmtran-like format.
+#' @param data a data set with nmtran-like format or an event object.
 #' @param warn if `TRUE`, a warning will be issued when there are both upper
 #' and lower case versions of any nmtran-like column in the data frame.
 #' @param ... for potential future use.
 #' 
 #' @return 
-#' A data frame or event object with possibly renamed columns.
+#' A data frame or event object, with column names possibly converted to upper
+#' or lower case.
 #' 
 #' @examples
 #' data <- data.frame(TIME = 0, AMT = 5, II = 24, addl = 2, WT = 80)
@@ -205,9 +206,6 @@ setMethod("data_set", c("mrgmod", "missing"), function(x, object, ...) {
 #' data <- data.frame(TIME = 1, time = 2, CMT = 5)
 #' lctran(data)
 #' 
-#' @return 
-#' The input data set, with select columns made lower case.
-#' 
 #' @md
 #' @export
 lctran <- function(data, ...) UseMethod("lctran")

R/generics.R

@@ -98,13 +98,23 @@ unloadso <- function(x,...) UseMethod("unloadso")
 ##' 
 setGeneric("stime", function(x,...) standardGeneric("stime"))
 
-##' Get model random effect variances and covariances
-##'
-##' @param x model object
-##' @param ... passed along
-##'
-##' @export
-##' @rdname revar
+#' Get model random effect variances and covariances
+#' 
+#' Use this function to extract both OMEGA and SIGMA matrices from a 
+#' model object. Typical use is for display on the R console.
+#'
+#' @param x model object.
+#' @param ... passed along.
+#' 
+#' @return A named list containing `omega` and `sigma` matrices.
+#' 
+#' @examples
+#' mod <- mrgsolve::house()
+#' revar(mod)
+#' 
+#' @rdname revar
+#' @md
+#' @export
 setGeneric("revar", function(x,...) standardGeneric("revar"))
 
 ##' Return the code blocks from a model specification file

R/matlist.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.
 #
@@ -16,56 +16,60 @@
 # along with mrgsolve.  If not, see <http://www.gnu.org/licenses/>.
 
 
-##' Manipulate OMEGA matrices
-##'
-##' The primary function is \code{omat} that can be used to both get the 
-##' \code{$OMEGA} matrices out of a model object and to update \code{$OMEGA} 
-##' matrices in a model object.
-##'
-##' @param .x a matrix, list of matrices or \code{matlist} object
-##' @param x  \code{matlist} object
-##' @param labels character vector of names for \code{$OMEGA} elements; must 
-##' be equal to number of rows/columns in the matrix
-##' @param open passed to \code{\link{merge.list}}
-##' @param make logical; if TRUE, matrix list is rendered into a single matrix
-##' @param ... passed to other functions, including \code{\link{modMATRIX}}
-##' @export
-##' @name omega
-##' @rdname omega
-##' @aliases omat  OMEGA
-##' @examples
-##' ## example("omega")
-##' mat1 <- matrix(1)
-##' mat2 <- diag(c(1,2,3))
-##' mat3 <- matrix(c(0.1, 0.002, 0.002, 0.5), 2,2)
-##' mat4 <- dmat(0.1, 0.2, 0.3, 0.4)
-##'
-##' omat(mat1)
-##' omat(mat1, mat2, mat3)
-##' omat(A=mat1, B=mat2, C=mat3)
-##'
-##' mod <- mrgsolve::house() %>% omat(mat4)
-##'
-##' omat(mod)
-##' omat(mod, make=TRUE)
-##'
-##'
-##' \dontrun{
-##'
-##' $OMEGA
-##' 1 2 3
-##'
-##' $OMEGA \@block
-##' 1 0.1 2
-##'
-##' $OMEGA \@cor
-##' \@ prefix ETA_
-##' \@ labels CL VC KA
-##' 0.1
-##' 0.67 0.2
-##' 0 0 0.3
-##'
-##' }
+#' Manipulate OMEGA matrices
+#'
+#' The primary function is `omat()` that can be used to both get the 
+#' `$OMEGA` matrices out of a model object and to update `$OMEGA` 
+#' matrices in a model object.
+#'
+#' @param .x a matrix, list of matrices or `matlist` object.
+#' @param x  `matlist` object.
+#' @param labels character vector of names for `$OMEGA` elements; must 
+#' be equal to number of rows/columns in the matrix.
+#' @param open passed to [merge.list()].
+#' @param make logical; if `TRUE`, matrix list is rendered into a single matrix.
+#' @param ... passed to other functions, including [modMATRIX()].
+#' 
+#' @seealso [smat()], [dmat()], [bmat()], [cmat()]
+#' 
+#' @examples
+#' ## example("omega")
+#' mat1 <- matrix(1)
+#' mat2 <- diag(c(1,2,3))
+#' mat3 <- matrix(c(0.1, 0.002, 0.002, 0.5), 2,2)
+#' mat4 <- dmat(0.1, 0.2, 0.3, 0.4)
+#'
+#' omat(mat1)
+#' omat(mat1, mat2, mat3)
+#' omat(A=mat1, B=mat2, C=mat3)
+#'
+#' mod <- mrgsolve::house() %>% omat(mat4)
+#'
+#' omat(mod)
+#' omat(mod, make=TRUE)
+#'
+#'
+#' \dontrun{
+#'
+#' $OMEGA
+#' 1 2 3
+#'
+#' $OMEGA \@block
+#' 1 0.1 2
+#'
+#' $OMEGA \@cor
+#' \@ prefix ETA_
+#' \@ labels CL VC KA
+#' 0.1
+#' 0.67 0.2
+#' 0 0 0.3
+#'
+#' }
+#' @name omega
+#' @rdname omega
+#' @aliases omat  OMEGA
+#' @md
+#' @export
 
 setGeneric("omat",function(.x,...) standardGeneric("omat"))
 ##' @export
@@ -116,42 +120,44 @@ setMethod("omat", "mrgsims", function(.x,make=FALSE,...) {
   as.matrix(mod(.x)@omega)
 })
 
-##' Manipulate SIGMA matrices
-##'
-##' The primary function is \code{smat} that can be used to both get the 
-##' \code{$SIGMA} matrices out of a model object and to update \code{$SIGMA} 
-##' matrices in a model object.
-##'
-##' @param .x a matrix, list of matrices or \code{matlist} object
-##' @param x  \code{matlist} object
-##' @param labels character vector of names for \code{$SIGMA} elements; must be
-##' equal 
-##' to number of rows/columns in the matrix
-##' @param make logical; if TRUE, matrix list is rendered into a single matrix
-##' @param ... passed to other functions, including \code{\link{modMATRIX}}
-##' @param open passed to \code{\link{merge.list}}
-##' 
-##' @name sigma
-##' @rdname sigma
-##' 
-##' @aliases smat SIGMA
-##' 
-##' @examples
-##' ## example("sigma")
-##' mat1 <- matrix(1)
-##' mat2 <- diag(c(1,2))
-##' mat3 <- matrix(c(0.1, 0.002, 0.002, 0.5), 2,2)
-##' mat4 <- dmat(0.1, 0.2, 0.3, 0.4)
-##'
-##' smat(mat1)
-##' smat(mat1, mat2, mat3)
-##' smat(A=mat1, B=mat2, C=mat3)
-##'
-##' mod <- mrgsolve::house() %>% smat(mat1)
-##'
-##' smat(mod)
-##' smat(mod, make=TRUE)
-##' @export
+#' Manipulate SIGMA matrices
+#'
+#' The primary function is `smat()` which can be used to both get the 
+#' `$SIGMA` matrices out of a model object and to update `$SIGMA` 
+#' matrices in a model object.
+#'
+#' @param .x a matrix, list of matrices or `matlist` object.
+#' @param x  `matlist` object.
+#' @param labels character vector of names for `$SIGMA` elements; must be
+#' equal to number of rows/columns in the matrix.
+#' @param make logical; if `TRUE`, matrix list is rendered into a single matrix.
+#' @param ... passed to other functions, including [modMATRIX()].
+#' @param open passed to [merge.list()].
+#' 
+#' 
+#' @seealso [dmat()], [bmat()], [cmat()]
+#' 
+#' @examples
+#' ## example("sigma")
+#' mat1 <- matrix(1)
+#' mat2 <- diag(c(1,2))
+#' mat3 <- matrix(c(0.1, 0.002, 0.002, 0.5), 2,2)
+#' mat4 <- dmat(0.1, 0.2, 0.3, 0.4)
+#'
+#' smat(mat1)
+#' smat(mat1, mat2, mat3)
+#' smat(A=mat1, B=mat2, C=mat3)
+#'
+#' mod <- mrgsolve::house() %>% smat(mat1)
+#'
+#' smat(mod)
+#' smat(mod, make=TRUE)
+#' 
+#' @name sigma
+#' @rdname sigma
+#' @aliases smat SIGMA
+#' @md
+#' @export
 setGeneric("smat",function(.x,...) standardGeneric("smat"))
 
 ##' @export
@@ -202,17 +208,16 @@ setMethod("smat", "mrgsims", function(.x,make=FALSE,...) {
 
 #' Zero out random effects in a model object
 #' 
-#' Sets all elements of the OMEGA or SIGMA matrix to zero
+#' Sets all elements of the OMEGA or SIGMA matrix to zero.
 #' 
-#' @param .x a model object
+#' @param .x a model object.
 #' @param ... which matrix to zero out; pass `omega` to just zero out `omega`, 
-#' `sigma` to just zero out `sigma`; passing nothing will zero out both
+#' `sigma` to just zero out `sigma`; passing nothing will zero out both.
 #' 
 #' @return 
-#' An updated object with elements of OMEGA and / or SIGMA set to zero..
+#' An updated object with elements of OMEGA and/or SIGMA set to zero.
 #' 
 #' @examples
-#' 
 #' mod <- house()
 #' revar(mod)
 #' mod <- zero_re(mod)

R/matrix.R

@@ -1,4 +1,4 @@
-# Copyright (C) 2013 - 2021  Metrum Research Group
+# Copyright (C) 2013 - 2024  Metrum Research Group
 # This file is part of mrgsolve.
 #
 # mrgsolve is free software: you can redistribute it and/or modify it
@@ -131,46 +131,52 @@ Diag <- function(x) {
   diag(x, nrow=length(x),ncol=length(x))
 }
 
-##' Create matrices from vector input
-##'
-##' @param ... matrix data
-##' @param correlation logical; if TRUE, off-diagonal elements are assumed 
-##' to be correlations and converted to covariances
-##' @param digits if greater than zero, matrix is passed to signif (along 
-##' with digits) prior to returning
-##' @details
-##' \code{bmat} makes a block matrix.  \code{cmat} makes a correlation matrix. 
-##' \code{dmat} makes a diagonal matrix.
-##' 
-##' @seealso \code{\link{as_bmat}}
-##' 
-##' @examples
-##'
-##' dmat(1,2,3)/10
-##'
-##' bmat(0.5,0.01,0.2)
-##'
-##' cmat(0.5, 0.87,0.2)
-##' 
-##' @rdname matrix_helpers
-##' @name matrix_helpers
-##' @export
+#' Create matrices from vector input
+#' 
+#' These functions are simple utilities for creating diagonal, block or 
+#' correlation matrices. 
+#' 
+#' @param ... matrix data.
+#' @param correlation logical; if `TRUE`, off-diagonal elements are assumed 
+#' to be correlations and converted to covariances.
+#' @param digits if greater than zero, matrix is passed to [signif()] (along 
+#' with digits) prior to returning.
+#' 
+#' @details
+#' `bmat()` makes a block matrix. `cmat()` makes a correlation matrix. 
+#' `dmat()` makes a diagonal matrix.
+#' 
+#' @return A matrix.
+#' 
+#' @seealso [as_bmat()], [as_dmat()]
+#' 
+#' @examples
+#'
+#' dmat(1,2,3)/10
+#'
+#' bmat(0.5,0.01,0.2)
+#'
+#' cmat(0.5, 0.87,0.2)
+#' 
+#' @rdname matrix_helpers
+#' @name matrix_helpers
+#' @md
+#' @export
 bmat <- function(...,correlation=FALSE, digits=-1) {
   x <- lower2matrix(unlist(list(...)),context="bmat")
   if(correlation) decorr(x)
   if(digits>0) x <- signif(x,digits=digits)
   return(x)
 }
 
-##' @rdname matrix_helpers
-##' @export
+#' @rdname matrix_helpers
+#' @export
 cmat <- function(...,digits=-1) {
   bmat(...,digits=digits,correlation=TRUE)
 }
 
-##' @rdname matrix_helpers
-##' @seealso \code{\link{as_dmat}}
-##' @export
+#' @rdname matrix_helpers
+#' @export
 dmat <- function(...) {
   Diag(as.numeric(unlist(list(...))))
 }