updated roxygen to use markdown

DESCRIPTION

@@ -16,5 +16,6 @@ LinkingTo: Rcpp, RcppEigen
 LazyData: true
 Suggests: testthat, knitr, rmarkdown
 Encoding: UTF-8
-RoxygenNote: 7.2.1
+RoxygenNote: 7.3.2
 VignetteBuilder: knitr
+Roxygen: list(markdown = TRUE)

R/Hierarchical.R

@@ -1,14 +1,14 @@
 #' Bayesian inference for a random-effects regression model.
 #'
-#' Gibbs sampler for posterior distribution of parameters and hyperparameters of a multivariate normal random-effects linear regression model called RxNormLM (see \strong{Details}).
+#' Gibbs sampler for posterior distribution of parameters and hyperparameters of a multivariate normal random-effects linear regression model called RxNormLM (see Details).
 #'
 #' @param nsamples number of posterior samples to draw.
-#' @param Y \code{N x q} matrix of responses.
-#' @param V Either a \code{q x q} variance matrix or an \code{q x q x N} array of such matrices.
-#' @param X \code{N x p} matrix of covariates.
-#' @param prior parameters of the prior MNIW distribution on the hyperparameters (see \strong{Details}).
-#' @param burn integer number of burn-in samples, or fraction of \code{nsamples} to prepend as burn-in.
-#' @param init (optional) list with elements \code{Beta}, \code{Sigma}, and \code{Mu} providing the initial values for these.  Default values are \code{Beta = matrix(0, p, q)}, \code{Sigma = diag(q)}, and \code{Mu = Y}.
+#' @param Y `N x q` matrix of responses.
+#' @param V Either a `q x q` variance matrix or an `q x q x N` array of such matrices.
+#' @param X `N x p` matrix of covariates.
+#' @param prior parameters of the prior MNIW distribution on the hyperparameters (see Details).
+#' @param burn integer number of burn-in samples, or fraction of `nsamples` to prepend as burn-in.
+#' @param init (optional) list with elements `Beta`, `Sigma`, and `Mu` providing the initial values for these.  Default values are `Beta = matrix(0, p, q)`, `Sigma = diag(q)`, and `Mu = Y`.
 #' @param updateHyp,storeHyp logical. Whether or not to update/store the hyperparameter draws.
 #' @param updateRX,storeRX logical. Whether or not to update/store the random-effects draws.
 #' @details The RxNormLM model is given by
@@ -23,12 +23,12 @@
 #' }
 #' where \eqn{y_i} and \eqn{\mu_i} are response and random-effects vectors of length \eqn{q}, \eqn{x_i} are covariate vectors of length \eqn{p}, and \eqn{(\beta, \Sigma)} are hyperparameter matrices of size \eqn{p \times q} and \eqn{q \times q}.
 #'
-#' The MNIW prior distribution is given by a list with elements \code{Lambda}, \code{Omega}, \code{Psi}, and \code{nu}.  If any of these is \code{NULL} or missing, the default value is 0.  Note that \code{Omega == 0} gives a Lebesgue prior to \eqn{\beta}.
+#' The MNIW prior distribution is given by a list with elements `Lambda`, `Omega`, `Psi`, and `nu`.  If any of these is `NULL` or missing, the default value is 0.  Note that `Omega == 0` gives a Lebesgue prior to \eqn{\beta}.
 #' @return A list with (potential) elements:
 #' \describe{
-#'   \item{\code{Beta}}{An \code{p x q x nsamples} array of regression coefficient iterations (if \code{storeHyp == TRUE})}
-#'   \item{\code{Sigma}}{An \code{q x q x nsamples} array of regression variance matrices (if \code{storeHyp == TRUE})}
-#'   \item{\code{Mu}}{An \code{n x q x nsamples} array of random effects (if \code{storeRX == TRUE})}
+#'   \item{`Beta`}{An `p x q x nsamples` array of regression coefficient iterations (if `storeHyp == TRUE`)}
+#'   \item{`Sigma`}{An `q x q x nsamples` array of regression variance matrices (if `storeHyp == TRUE`)}
+#'   \item{`Mu`}{An `n x q x nsamples` array of random effects (if `storeRX == TRUE`)}
 #' }
 #'
 #' @example examples/Hierarchical.R

R/MNIW.R → R/MNIW-dist.R

@@ -2,23 +2,26 @@
 
 #' Generate samples from the Matrix-Normal Inverse-Wishart distribution.
 #'
-#' @name MNIW
+#' @name MNIW-dist
+#' @aliases rMNIW rmniw MNIW
 #' @param n number of samples.
-#' @param Lambda A mean matrix of size \code{p x q} or an array of size \code{p x q x n}.  Defaults to matrix of zeros when missing.
-#' @param Sigma A row-wise variance or precision matrix of size \code{p x p}, or an array of size \code{p x p x n}.  Defaults to the identity matrix when missing.
-#' @param Omega A between-row precision matrix of size \code{p x p}, or an array of size \code{p x p x n}.  Defaults to the identity matrix when missing.
-#' @param Psi A scale matrix of size \code{q x q}, or an array of size \code{q x q x n}.  Defaults to identity matrix when missing.
+#' @param Lambda A mean matrix of size `p x q` or an array of size `p x q x n`.  Defaults to matrix of zeros when missing.
+#' @param Sigma A row-wise variance or precision matrix of size `p x p`, or an array of size `p x p x n`.  Defaults to the identity matrix when missing.
+#' @param Omega A between-row precision matrix of size `p x p`, or an array of size `p x p x n`.  Defaults to the identity matrix when missing.
+#' @param Psi A scale matrix of size `q x q`, or an array of size `q x q x n`.  Defaults to identity matrix when missing.
 #' @param nu Scalar degrees-of-freedom parameter.
-#' @param prec Logical; whether or not \code{Sigma} is on the variance or precision scale.
+#' @param prec Logical; whether or not `Sigma` is on the variance or precision scale.
 #'
 #' @return A list with elements:
 #' \describe{
-#' \item{\code{X}}{Array of size \code{p x q x n} random samples from the Matrix-Normal component (see \strong{Details}).}
-#' \item{\code{V}}{Array of size \code{q x q x n} of random samples from the Inverse-Wishart component.}
+#' \item{`X`}{Array of size `p x q x n` random samples from the Matrix-Normal component (see Details).}
+#' \item{`V`}{Array of size `q x q x n` of random samples from the Inverse-Wishart component.}
 #' }
 #' @template details-mniw
-#' @details \code{rmniw} is a convenience wrapper to \code{rMNIW(Sigma = Omega, prec = TRUE)}, for the common situation in Bayesian inference with conjugate priors when between-row variances are naturally parametrized on the precision scale.
+#' @details `rmniw()` is a convenience wrapper to `rMNIW(Sigma = Omega, prec = TRUE)`, for the common situation in Bayesian inference with conjugate priors when between-row variances are naturally parametrized on the precision scale.
 #' @example examples/MNIW.R
+
+#' @rdname MNIW-dist
 #' @export
 rMNIW <- function(n, Lambda, Sigma, Psi, nu, prec = FALSE) {
   # get dimensions
@@ -50,7 +53,7 @@ rMNIW <- function(n, Lambda, Sigma, Psi, nu, prec = FALSE) {
   XV
 }
 
-#' @rdname MNIW
+#' @rdname MNIW-dist
 #' @export
 rmniw <- function(n, Lambda, Omega, Psi, nu) {
   rMNIW(n = n, Lambda = Lambda, Sigma = Omega,

R/MatrixNormal.R → R/MatrixNormal-dist.R

@@ -4,8 +4,8 @@
 #'
 #' Density and random sampling for the Matrix-Normal distribution.
 #'
-#' @name MatrixNormal
-#' @aliases dMNorm rMNorm
+#' @name MatrixNormal-dist
+#' @aliases dMNorm rMNorm MatrixNormal
 #' @template param-n
 #' @template param-Xpq
 #' @template param-Lambda
@@ -20,7 +20,7 @@
 
 #--- lower-level functions -------------------------------------------------
 
-#' @rdname MatrixNormal
+#' @rdname MatrixNormal-dist
 #' @export
 dMNorm <- function(X, Lambda, SigmaR, SigmaC, log = FALSE) {
   # get dimensions
@@ -48,7 +48,7 @@ dMNorm <- function(X, Lambda, SigmaR, SigmaC, log = FALSE) {
   ans
 }
 
-#' @rdname MatrixNormal
+#' @rdname MatrixNormal-dist
 #' @export
 rMNorm <- function(n, Lambda, SigmaR, SigmaC) {
   # get dimensions

R/MatrixT.R → R/MatrixT-dist.R

@@ -4,8 +4,8 @@
 #'
 #' Density and sampling for the Matrix-t distribution.
 #'
-#' @name MatrixT
-#' @aliases dMT
+#' @name MatrixT-dist
+#' @aliases dMT rMT MatrixT
 #' @template param-n
 #' @template param-Xpq
 #' @template param-Lambda
@@ -20,7 +20,7 @@
 
 #--- lower-level functions ------------------------------------------------
 
-#' @rdname MatrixT
+#' @rdname MatrixT-dist
 #' @export
 dMT <- function(X, Lambda, SigmaR, SigmaC, nu, log = FALSE) {
   # get dimensions
@@ -49,7 +49,7 @@ dMT <- function(X, Lambda, SigmaR, SigmaC, nu, log = FALSE) {
   ans
 }
 
-#' @rdname MatrixT
+#' @rdname MatrixT-dist
 #' @export
 rMT <- function(n, Lambda, SigmaR, SigmaC, nu) {
   # get dimensions

R/MultiNormal.R → R/MultiNormal-dist.R

@@ -4,16 +4,17 @@
 #'
 #' Density and random sampling for the Multivariate Normal distribution.
 #'
-#' @name MultiNormal
-#' @aliases dmNorm rmNorm
-#' @param x Argument to the density function.  A vector of length \code{q} or an \code{n x q} matrix.
+#' @name MultiNormal-dist
+#' @aliases dmNorm rmNorm MultiNormal
+#' @param x Argument to the density function.  A vector of length `q` or an `n x q` matrix.
 #' @template param-n
-#' @param mu Mean vector(s).  Either a vector of length \code{q} or an \code{n x q} matrix.  If missing defaults to a vector of zeros.
-#' @param Sigma Covariance matrix or matrices.  Either a \code{q x q} matrix or a \code{q x q x n} array.  If missing defaults to the identity matrix.
+#' @param mu Mean vector(s).  Either a vector of length `q` or an `n x q` matrix.  If missing defaults to a vector of zeros.
+#' @param Sigma Covariance matrix or matrices.  Either a `q x q` matrix or a `q x q x n` array.  If missing defaults to the identity matrix.
 #' @template param-log
-#' @return A vector for densities, or a \code{n x q} matrix for random sampling.
+#' @return A vector for densities, or a `n x q` matrix for random sampling.
 #' @example examples/MultiNormal.R
-#' @rdname MultiNormal
+
+#' @rdname MultiNormal-dist
 #' @export
 dmNorm <- function(x, mu, Sigma, log = FALSE) {
   # get dimensions
@@ -44,7 +45,7 @@ dmNorm <- function(x, mu, Sigma, log = FALSE) {
   ans
 }
 
-#' @rdname MultiNormal
+#' @rdname MultiNormal-dist
 #' @export
 rmNorm <- function(n, mu, Sigma) {
   # get dimensions

R/RandomEffects.R

@@ -2,13 +2,13 @@
 
 #' Conditional sampling for Multivariate-Normal Random-Effects model.
 #'
-#' Sample from the conditional parameter distribution given the data and hyperparameters of the Multivariate-Normal Random-Effects (mNormRE) model (see \strong{Details}).
+#' Sample from the conditional parameter distribution given the data and hyperparameters of the Multivariate-Normal Random-Effects (mNormRE) model (see **Details**).
 #'
 #' @template param-n
-#' @param x Data observations.  Either a vector of length \code{q} or a \code{n x q} matrix.  In the latter case each row is a different vector.
-#' @param V Observation variances.  Either a matrix of size \code{q x q} or a \code{q x q x n} array.
-#' @param lambda Prior means.  Either a vector of length \code{q} or an \code{n x q} matrix.  In the latter case each row is a different mean.  Defaults to zeros.
-#' @param Sigma Prior variances.  Either a matrix of size \code{q x q} or a \code{q x q x n} array.  Defaults to identity matrix.
+#' @param x Data observations.  Either a vector of length `q` or a `n x q` matrix.  In the latter case each row is a different vector.
+#' @param V Observation variances.  Either a matrix of size `q x q` or a `q x q x n` array.
+#' @param lambda Prior means.  Either a vector of length `q` or an `n x q` matrix.  In the latter case each row is a different mean.  Defaults to zeros.
+#' @param Sigma Prior variances.  Either a matrix of size `q x q` or a `q x q x n` array.  Defaults to identity matrix.
 #' @details Consider the hierarchical multivariate normal model
 #' \deqn{
 #' \begin{array}{rcl}
@@ -19,7 +19,7 @@
 #' \mu ~ N(\lambda, \Sigma)
 #' x | \mu ~ N(\mu, V).
 #' }
-#' The Multivariate-Normal Random-Effects model \eqn{\boldsymbol{\mu} \sim \textrm{RxNorm}(\boldsymbol{x}, \boldsymbol{V}, \boldsymbol{\lambda}, \boldsymbol{\Sigma})}{\mu ~ RxNorm(x, V, \lambda, \Sigma)} on the random vector \eqn{\boldsymbol{\mu}_q}{\mu_q} is defined as the posterior distribution \eqn{p(\boldsymbol{\mu} \mid \boldsymbol{x}, \boldsymbol{\lambda}, \boldsymbol{\Sigma})}{p(\mu | x, \lambda, \Sigma)}.  This distribution is multivariate normal; for the mathematical specification of its parameters please see \code{vignette("mniw-distributions", package = "mniw")}.
+#' The Multivariate-Normal Random-Effects model \eqn{\boldsymbol{\mu} \sim \textrm{RxNorm}(\boldsymbol{x}, \boldsymbol{V}, \boldsymbol{\lambda}, \boldsymbol{\Sigma})}{\mu ~ RxNorm(x, V, \lambda, \Sigma)} on the random vector \eqn{\boldsymbol{\mu}_q}{\mu_q} is defined as the posterior distribution \eqn{p(\boldsymbol{\mu} \mid \boldsymbol{x}, \boldsymbol{\lambda}, \boldsymbol{\Sigma})}{p(\mu | x, \lambda, \Sigma)}.  This distribution is multivariate normal; for the mathematical specification of its parameters please see `vignette("mniw-distributions", package = "mniw")`.
 #'
 #' @example examples/RandomEffects.R
 #' @export

R/Wishart.R → R/Wishart-dist.R

@@ -8,50 +8,45 @@
 #'
 #' Densities and random sampling for the Wishart and Inverse-Wishart distributions.
 #'
-#' @name Wishart
-#' @aliases dwish rwish diwish riwish dwishart rwishart
+#' @name Wishart-dist
+#' @aliases dwish rwish diwish riwish dwishart rwishart Wishart
 #' @template param-Xqq
 #' @template param-n
 #' @template param-Psi
 #' @template param-nu
 #' @param inverse Logical; whether or not to use the Inverse-Wishart distribution.
 #' @template param-log
 #' @template details-wishart
-#' @details \code{dwish} and \code{diwish} are convenience wrappers for \code{dwishart}, and similarly \code{rwish} and \code{riwish} are wrappers for \code{rwishart}.
+#' @details `dwish()` and `diwish()` are convenience wrappers for `dwishart()`, and similarly `rwish()` and `riwish()` are wrappers for `rwishart()`.
 #'
 #' @example examples/Wishart.R
 #' @template return-rdqq
 
 #--- convenience wrappers --------------------------------------------------
 
-# \deqn{
-# f(\boldsymbol{X} \mid \boldsymbol{\Psi}, \nu) = \frac{|\boldsymbol{X}|^{(\nu-q+1)/2}\exp\big\{-\frac 1 2 \textrm{trace}(\boldsymbol{\Psi}^{-1}\boldsymbol{X})\big\}}{2^{\nu q/2}|\boldsymbol{\Psi}|^{\nu/2} \Gamma_q(\frac \nu 2)}
-# }
-
-
 # wishart density
-#' @rdname Wishart
+#' @rdname Wishart-dist
 #' @export
 dwish <- function(X, Psi, nu, log = FALSE) {
   dwishart(X, Psi, nu, inverse = FALSE, log)
 }
 
 # wishart simulation
-#' @rdname Wishart
+#' @rdname Wishart-dist
 #' @export
 rwish <- function(n, Psi, nu) {
   rwishart(n, Psi, nu, inverse = FALSE)
 }
 
 # inverse wishart density
-#' @rdname Wishart
+#' @rdname Wishart-dist
 #' @export
 diwish <- function(X, Psi, nu, log = FALSE) {
   dwishart(X, Psi, nu, inverse = TRUE, log)
 }
 
 # inverse wishart simulation
-#' @rdname Wishart
+#' @rdname Wishart-dist
 #' @export
 riwish <- function(n, Psi, nu) {
   rwishart(n, Psi, nu, inverse = TRUE)
@@ -61,7 +56,7 @@ riwish <- function(n, Psi, nu) {
 
 # density of wishart and inverse wishart
 
-#' @rdname Wishart
+#' @rdname Wishart-dist
 #' @export
 dwishart <- function(X, Psi, nu, inverse = FALSE, log = FALSE) {
   # get dimensions
@@ -98,7 +93,7 @@ dwishart <- function(X, Psi, nu, inverse = FALSE, log = FALSE) {
 }
 
 # random sampling for wishart and inverse wishart
-#' @rdname Wishart
+#' @rdname Wishart-dist
 #' @export
 rwishart <- function(n, Psi, nu, inverse = FALSE) {
   # get problem dimensions

R/crossprodV.R

@@ -1,12 +1,12 @@
 #' Matrix cross-product.
 #'
-#' Vectorized matrix cross-products \code{t(X) V Y} or \code{t(X) V^{-1} Y}.
+#' Vectorized matrix cross-products `t(X) V Y` or `t(X) V^{-1} Y`.
 #'
-#' @param X A matrix of size \code{p x q}, or an array of size \code{p x q x n}.
-#' @param Y A matrix of size \code{p x r}, or an array of size \code{p x r x n}.  If missing defaults to \code{Y = X}.
-#' @param V A matrix of size \code{p x p}, or an array of size \code{p x p x n}.
-#' @param inverse Logical; whether or not the inner product should be calculated with \code{V} or \code{V^{-1}}.
-#' @return An array of size \code{q x r x n}.
+#' @param X A matrix of size `p x q`, or an array of size `p x q x n`.
+#' @param Y A matrix of size `p x r`, or an array of size `p x r x n`.  If missing defaults to `Y = X`.
+#' @param V A matrix of size `p x p`, or an array of size `p x p x n`.
+#' @param inverse Logical; whether or not the inner product should be calculated with `V` or `V^{-1}`.
+#' @return An array of size `q x r x n`.
 #'
 #' @example examples/crossprodV.R
 #' @export

R/hospitals.R

@@ -4,10 +4,10 @@
 #'
 #' @format A data frame with 27 rows (one for each hospital) and 4 variables:
 #' \describe{
-#'   \item{\code{NSrg}}{Non-surgery related problem rate (\%).}
-#'   \item{\code{Srg}}{Surgery related problem rate (\%).}
-#'   \item{\code{Severity}}{Average health index for surveyed patients.}
-#'   \item{\code{Size}}{Number of patients surveyed.}
+#'   \item{`NSrg`}{Non-surgery related problem rate (percent).}
+#'   \item{`Srg`}{Surgery related problem rate (percent).}
+#'   \item{`Severity`}{Average health index for surveyed patients.}
+#'   \item{`Size`}{Number of patients surveyed.}
 #' }
-#' @references Everson, P.J. and Morris, C.N. "Inference for multivariate normal hierarchical models." \emph{Journal of the Royal Statistical Society, Series B} 62:2 (2000): 399-412.
+#' @references Everson, P.J. and Morris, C.N. "Inference for multivariate normal hierarchical models." *Journal of the Royal Statistical Society, Series B* 62:2 (2000): 399-412.
 "Hospitals"

R/mniw-format.R

@@ -1,9 +1,15 @@
-# format the MNIW inputs correctly
-# that is, get dimensions of problem from the inputs
-# for density evaluation, X and V are given and thus the dimensions of the problem are known immediately.
-# for simulation, need to gather these values from the other inputs.
-# what to do when arguments are vectors?
-# always default to dimensions 1 x 1.  This is the obvious choice for variance arguments.  For mean arguments, the other choice is eg., length(arg) x 1, but this should be handled with the simpler functions mNorm and mNIW.
+#' Format the MNIW inputs correctly.
+#'
+#' Get dimensions of problem from the inputs.
+#'
+#' @details For density evaluation, `X` and `V` are given and thus the dimensions of the problem are known immediately.
+#'
+#' For simulation, need to gather these values from the other inputs.
+#'
+#' What to do when arguments are vectors?
+#'
+#' Always default to dimensions `1 x 1`.  This is the obvious choice for variance arguments.  For mean arguments, the other choice is eg., `length(arg) x 1`, but this should be handled with the simpler functions `mNorm` and `mNIW`.
+#' @noRd
 .getPQ <- function(X, V, Lambda, Sigma, Psi) {
   p <- NA
   q <- NA
@@ -34,13 +40,16 @@
   as.numeric(c(p, q))
 }
 
-# missing or NULL
+#' Is `x` missing or NULL?
+#'
+#' @noRd
 .minu <- function(x) missing(x) || is.null(x)
 
 
-# format a vector, matrix, or array to a matrix with p rows and q columns.
-# if dimensions are incompatible return NA, otherwise the formated matrix.
-# if only
+#' Format a vector, matrix, or array to a matrix with `p` rows and `q` columns.
+#'
+#' @details If dimensions are incompatible return `NA`, otherwise the formated matrix.
+#' @noRd
 .setDims <- function(X, p, q) {
   var.X <- missing(p) || missing(q)
   if(var.X) {
@@ -63,8 +72,10 @@
   X
 }
 
-# get the sample size from arguments for random sampling
-# returns 1 and possibly all sample sizes > 1 detected.
+#' Get the sample size from arguments for random sampling.
+#'
+#' @return A vector of integers concatenating `1` with all sample sizes > 1 detected.
+#' @noRd
 .getN <- function(p, q, X, V, Lambda, Sigma, Psi, nu) {
   N <- NULL
   if(!.minu(X)) N <- c(N, ncol(X)/q)
@@ -77,8 +88,10 @@
   c(1, N[N>1])
 }
 
-# convert a vector or matrix to MN format,
-# i.e., promote to 2- or 3-d array with (second dimension) q = 1
+#' Convert a vector or matrix to MN format.
+#'
+#' @details Promote to 2-d or 3-d array with (second dimension) `q = 1`.
+#' @noRd
 .vec2mn <- function(x) {
   if(is.vector(x)) {
     x <- matrix(x, ncol = 1)