Make various minor roxygen/package structure/vignette suggestions.

Author: paciorek

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: nimbleMacros
 Version: 0.1.0
 Date: 2025-01-28
-Title: Macros Generating 'nimble' Code for Linear Models
+Title: Macros Generating 'nimble' Code for Linear Models. 
 Authors@R: c(person("Ken", "Kellner", email="contact@kenkellner.com", 
                     role=c("cre","aut")),
              person("Perry", "de Valpine", role = "aut"),
@@ -16,8 +16,8 @@ Suggests:
     knitr,
     markdown,
     testthat
-Description: Macros to generate 'nimble' code from a concise syntax. Included are macros for generating linear modeling code using a formula-based syntax, and for 'for' loops. (de Valpine et al. (2015) <doi:10.1080/10618600.2016.1172487>).
-License: GPL-3
+Description: Macros to generate 'nimble' code from a concise syntax. Included are macros for generating linear modeling code using a formula-based syntax and for 'for' loops.
+License: BSD_3_clause + file LICENSE | GPL (>= 2)
 NeedsCompilation: no
 Encoding: UTF-8
 VignetteBuilder: knitr

LICENSE

@@ -0,0 +1,3 @@
+YEAR: 2025
+COPYRIGHT HOLDER: Ken Kellner, Perry de Valpine, Christopher Paciorek, Daniel Turek
+ORGANIZATION: University of California

R/FORLOOP.R

@@ -17,7 +17,7 @@
 #'    mu[1:n] <- FORLOOP(beta[1] + beta[2]*x[1:n])
 #' })
 #'
-#' mod <- nimbleModel(code, constants=list(n=10))
+#' mod <- nimbleModel(code, constants = list(n=10))
 #' mod$getCode()
 NULL
 

R/LINPRED.R

@@ -10,20 +10,21 @@
 #' @param formula An R formula, possibly with the parameters followed by 
 #'  brackets containing indices. If there are no indices, the macro attempts
 #'  to guess the correct indices from the context. The formula must be 
-#'  right-hand side only (e.g. ~x). This must always be the first argument supplied
-#'  to LINPRED.
-#' @param link A link function which will be applied to the 
+#'  right-hand side only (e.g. \code{~x}). This must always be the first argument supplied
+#'  to \code{LINPRED}.
+#' @param link A link function that will be applied to the 
 #'  left-hand-side (the response) in the final linear predictor. Default is none.
 #' @param coefPrefix All model coefficient names will begin with this prefix.
-#'  default is beta_ (so x becomes beta_x, etc.)
+#'  default is \code{"beta_"} (so 'x' becomes 'beta_x', etc.)
 #' @param sdPrefix All dispersion parameters will begin with this prefix.
-#'  default is no prefix.
-#' @param priorSpecs Prior specifications, should be generated with setPrior()
-#' @param modMatNames Logical, should parameters be named so they match the
-#'  names you would get from R's model.matrix function?
-#' @param noncenter Logical; use noncentered parameterization?
-#' @param centerVar Grouping covariate to 'center' on in parameterization. By
-#'  default all random effects have mean 0 as with lme4.
+#'  Default is no prefix.
+#' @param priorSpecs Prior specifications, generated with \code{setPrior()}
+#' @param modMatNames Logical indicating if parameters should be named so they match the
+#'  names one would get from R's \code{model.matrix}. Default is \code{FALSE}.
+#' @param noncenter Logical indicating whether to use noncentered parameterization.
+#'  Default is \code{FALSE}.
+#' @param centerVar Grouping variable (covariate) to 'center' the random effects on. By
+#'  default all random effects have mean 0 as with \code{lme4}.
 #'
 #' @author Ken Kellner
 #'
@@ -33,7 +34,7 @@
 #'   mu[1:3] <- LINPRED(~x + x2)
 #' })
 #'
-#' mod <- nimbleModel(code, constants=constants)
+#' mod <- nimbleModel(code, constants = constants)
 #' mod$getCode()
 NULL
 
@@ -92,29 +93,31 @@ unpackArgs=TRUE
 )
 
 
-#' Macro to build code for priors on a linear predictor from R formula
+#' Macro to build code for priors on a linear predictor from an R formula
 #'
 #' Generates appropriate priors for a linear predictor derived from an 
 #' R formula. As such it makes the most sense to use this macro together with
-#' the LINPRED macro which takes similar arguments.
+#' the LINPRED macro, which takes similar arguments.
 #'
 #' @name LINPRED_PRIORS
 #' @author Ken Kellner
 #'
-#' @param formula An R formula The formula must be right-hand side only (e.g. ~x). 
-#'  This must always be the first argument supplied to LINPRED_PRIORS
+#' @param formula An R formula The formula must be right-hand side only (e.g., \code{~x}). 
+#'  This must always be the first argument supplied to \code{LINPRED_PRIORS}.
 #' @param coefPrefix All model coefficient names will begin with this prefix.
-#'  default is beta_ (so x becomes beta_x, etc.)
+#'  default is \code{"beta_"} (so 'x' becomes 'beta_x', etc.)
 #' @param sdPrefix All dispersion parameters will begin with this prefix.
-#'  default is no prefix.
-#' @param priorSpecs List of prior specifications, should be generated using 
+#'  Default is no prefix.
+#' @param priorSpecs List of prior specifications, generated using \code{setPriors}.
 #'  setPriors()
-#' @param modMatNames Logical, should parameters be named so they match the
-#'  names you would get from R's model.matrix function?
-#' @param noncenter Logical, use noncentered parameterization?
-#' @param centerVar Grouping covariate to 'center' on in parameterization. By
-#'  default all random effects have mean 0 as with lme4.
+#' @param modMatNames Logical indicating if parameters should be named so they match the
+#'  names one would get from R's \code{model.matrix}. Default is \code{FALSE}.
+#' @param noncenter Logical indicating whether to use noncentered parameterization.
+#'  Default is \code{FALSE}.
+#' @param centerVar Grouping variable (covariate) to 'center' the random effects on. By
+#'  default all random effects have mean 0 as with \code{lme4}.
 #'
+#' 
 #' @author Ken Kellner
 #'
 #' @examples
@@ -1378,12 +1381,12 @@ correlatedRandomPrior <- function(x, priorSpecs, sdPrefix, sd_name, modelInfo, c
 #' uppertri_mult_diag
 #' 
 #' nimbleFunction needed when fitting correlated random effects.
-#' Generates upper triangular Cholesky factor of covariance matrix (U in code)
-#' from upper tri Cholesky factor of correlation matrix (Ustar in code)
+#' Generates upper triangular Cholesky factor of covariance matrix ("U" in code)
+#' from upper triangular Cholesky factor of correlation matrix ("Ustar" in code)
 #' and vector of standard deviations. Taken from the NIMBLE manual, 
-#' section 5.2.4.1.2 LKJ distribution for correlation matrices.
+#' section 5.2.4.1.2 (LKJ Distribution for Correlation Matrices).
 #' 
-#' @param mat upper triangular Cholesky factor of correlation matrix (Ustar)
+#' @param mat upper triangular Cholesky factor of correlation matrix ("Ustar")
 #' @param vec vector of standard deviations for individual random effects
 #'
 #' @name uppertri_mult_diag

R/LM.R

@@ -1,7 +1,8 @@
 #' Macro for fitting linear models, GLMs, and GLMMs
 #'
 #' This macro generates code for LMs, GLMs, and GLMMs using formula notation 
-#' and arguments similar to R functions such as lm(), glm(), and lmer()/glmer(). 
+#' and arguments similar to R functions such as \code{lm()}, \code{glm()},
+#' and \code{lmer()}/\code{glmer()}. 
 #' Currently only normal, Poisson, and binomial models are supported.
 #'
 #' @name LM
@@ -10,19 +11,19 @@
 #' @param formula An R formula, possibly with the parameters followed by 
 #'  brackets containing indices. If there are no indices, the macro attempts
 #'  to guess the correct indices from the context. Formulas can include
-#'  random effects via lme4-style notation (e.g. ~ x + (1|group))
+#'  random effects via lme4-style notation (e.g., \code{~ x + (1|group)})
 #' @param family A description of the error distribution and link function to
 #'  be used in the model. This can be a character string naming a family function, 
-#'  a family function or the result of a call to a family function. See ?family.
-#'  Supported families are gaussian (default), binomial, and poisson.
-#' @param coefPrefix All model coefficient names will begin with this prefix.
-#'  default is beta_ (so x becomes beta_x, etc.)
-#' @param sdPrefix All dispersion parameters will begin with this prefix.
+#'  a family function or the result of a call to a family function. See \code{?family}.
+#'  Supported families are \code{gaussian} (default), \code{binomial}, and \code{poisson}.
+#' @param coefPrefix Character. All model coefficient names will begin with this prefix.
+#'  default is \code{"beta_"} (so 'x' becomes 'beta_x', etc.)
+#' @param sdPrefix Character. All dispersion parameters will begin with this prefix.
 #'  default is no prefix.
-#' @param priorSpecs List of prior specifications, should be generated using 
-#'  setPriors()
-#' @param modMatNames Logical, should parameters be named so they match the
-#'  names you would get from R's model.matrix function?
+#' @param priorSpecs List of prior specifications, generated using 
+#'  \code{setPriors()}.
+#' @param modMatNames Logical indicating if parameters be named so they match the
+#'  names one would get from R's \code{model.matrix}.
 #'
 #' @author Ken Kellner
 #'
@@ -35,7 +36,7 @@
 #'    LM(y ~ x + x2)
 #' })
 #' 
-#' mod <- nimbleModel(code, constants=constants)
+#' mod <- nimbleModel(code, constants = constants)
 #' mod$getCode()
 NULL
 
@@ -81,7 +82,7 @@ LM <- list(process = function(code, modelInfo, .env){
     # Check that LHS is in the constants, otherwise this won't work
     LHS_name <- safeDeparse(LHS)
     if(! LHS_name %in% names(modelInfo$constants)){
-      stop(paste0("If you don't provide dimensions for the data ", LHS_name, 
+      stop(paste0("LM: If you don't provide dimensions for the data ", LHS_name, 
                   ", you must include ", LHS_name, " in the constants instead."), call.=FALSE)
     }
     idx <- substitute(1:LEN, list(LEN=as.numeric(length(modelInfo$constants[[LHS_name]]))))
@@ -145,10 +146,10 @@ processFamily <- function(fam){
   }
 
   if(is.null(fam$family)){
-    stop("'family' not recognized")
+    stop("processFamily: 'family' not recognized: ", fam, call. = FALSE)
   }
   if(!fam$link %in% c("log", "identity","logit","probit","cloglog")){
-    stop("Unsupported link function", call.=FALSE)
+    stop("processFamily: Unsupported link function: ", fam$link, call.=FALSE)
   }
   fam
 }
@@ -167,7 +168,7 @@ getDataDistCode <- function(family, response, idx, dispParName){
     out <- substitute(DAT ~ FORLOOP(DIST(mu_[IDX], size=N)),
                       list(DAT=response, DIST=quote(dbinom), N=dispParName, IDX=idx))
   } else {
-    stop("Family not supported", call.=FALSE)
+    stop("getDataDistCode: Family not supported: ", family, call.=FALSE)
   }
   out
 }

R/setPriors.R

@@ -1,16 +1,9 @@
 #' Set up prior values for different categories of nodes
 #'
 #' Generates a list of custom specifications of priors for parameters in the model.
-#' It is possible to set priors for a category of parameters (e.g. intercept,
+#' It is possible to set priors for a category of parameters (e.g., intercept,
 #' coefficient, sd, factor, continuous) or to set a prior for a specific
 #' parameter name (optionally including brackets with indices).
-#' Exact name matches including brackets/indices are used first, followed by
-#' name matches without indices, followed by data type (factor/continuous)
-#' followed by parameter type (intercept/coefficient/sd).
-#' Arguments can be supplied as quoted code, a character string, or
-#' as a list of prior components. For example, to specify the prior
-#' \code{dnorm(0, sd = 10)} you could specify \code{quote(dnorm(0, sd = 10))},
-#' or \code{"dnorm(0, sd = 10)"}, or \code{list("dnorm", 0, sd = 10)}.
 #'
 #' @name setPriors
 #' @author Ken Kellner
@@ -28,6 +21,16 @@
 #'
 #' @seealso [nimble::dlkj_corr_cholesky] for more on the LKJ distribution
 #'
+#' @details
+#'
+#' Exact name matches including brackets/indices are used first, followed by
+#' name matches without indices, followed by data type (factor/continuous)
+#' followed by parameter type (intercept/coefficient/sd).
+#' Arguments can be supplied as quoted code, a character string, or
+#' as a list of prior components. For example, to specify the prior
+#' \code{dnorm(0, sd = 10)} you could specify \code{quote(dnorm(0, sd = 10))},
+#' or \code{"dnorm(0, sd = 10)"}, or \code{list("dnorm", 0, sd = 10)}.
+#' 
 #' @author Ken Kellner
 #'
 #' @examples
@@ -46,7 +49,7 @@ setPriors <- function(intercept = quote(dnorm(0, sd = 1000)),
                       sd = quote(dunif(0, 100)),
                       factor = NULL,
                       continuous = NULL,
-                      eta = 1.3,
+                      eta = 1,
                       ...){
   # Get specific prior names
   extra <- list(...)
@@ -57,7 +60,7 @@ setPriors <- function(intercept = quote(dnorm(0, sd = 1000)),
 
   # Check if any outputs are numeric (indicating they were passed without quote())
   lapply(1:length(out), function(i) if(is.numeric(out[[i]])){
-    stop("Prior code for ", names(out)[i], " should be wrapped in quote()", call.=FALSE)
+    stop("setPriors: Prior code for ", names(out)[i], " should be wrapped in quote()", call.=FALSE)
   })
 
   # Remove any null values
@@ -82,7 +85,7 @@ setPriors <- function(intercept = quote(dnorm(0, sd = 1000)),
 convertListToPrior <- function(input){
   if(!is.list(input)) return(input)
   if(is.function(input[[1]])){
-    stop("Function name must be a character string or wrapped in quote()", call.=FALSE)
+    stop("convertListToPrior: Function name must be a character string or wrapped in quote()", call.=FALSE)
   }
 
   out <- input
@@ -101,7 +104,7 @@ removeBracket <- function(node){
 #' Match a prior from a list of prior settings
 #'
 #' Attempts to determine which prior to put on a parameter based on a list of settings,
-#' such as the output from setPriors(). The function follows the following
+#' such as the output from \code{setPriors()}. The function follows the following
 #' search pattern: (1) looks for an exact match to the parameter name including brackets;
 #' (2) a match to the parameter name without brackets; (3) goes through each value
 #' supplied to \code{...} in order and looks for a match in the names of the
@@ -116,7 +119,7 @@ removeBracket <- function(node){
 #' @param ... Character strings that categorize the parameter and match
 #'  the names of elements in \code{priorSpecs}. The order is important:
 #'  the first match found is used.
-#' @param priorSpecs A named list of prior settings, e.g. as generated by
+#' @param priorSpecs A named list of prior settings, e.g., as generated by
 #'  \code{setPriors}
 #'
 #' @author Ken Kellner
@@ -161,10 +164,10 @@ matchPrior <- function(parName, ..., priorSpecs){
       return(priorSpecs[[i]])
     }
   }
-  stop("Unable to set prior for parameter ", parName, call.=FALSE)
+  stop("matchPrior: Unable to set prior for parameter: ", parName, call.=FALSE)
 }
 
 checkValidPrior <- function(prior){
-  if(!(is.call(prior) | is.name(prior))) stop("Invalid prior ", prior, call.=FALSE)
+  if(!(is.call(prior) | is.name(prior))) stop("Invalid prior: ", prior, call.=FALSE)
   invisible()
 }

README.md

@@ -4,7 +4,7 @@
 status](https://github.com/nimble-dev/nimbleMacros/workflows/R-CMD-check/badge.svg)](https://github.com/nimble-dev/nimbleMacros/actions)
 
 `nimbleMacros` is an R package that extends [NIMBLE](https://r-nimble.org/), an R package for hierarchical statistical modeling.
-The package provides a set of model macros, which are special code chunks which NIMBLE automatically expands into larger blocks of valid NIMBLE model code.
+The package provides a set of model macros, which are special code chunks that NIMBLE automatically expands into larger blocks of valid NIMBLE model code.
 
 For example, the following NIMBLE model code contains a macro called `LINPRED`, and the objective is to create a linear predictor containing an intercept and a slope for one covariate, `x`.