R/glmmVCtest.R

In stchen3/glmmVCtest: Testing variance components in generalized linear mixed models (GLMMs)

#' glmmVCtest: Testing variance components in generalized linear mixed models.
#'
#' The \code{glmmVCtest} package implements four methods for testing a single
#' random effect (variance components) in a generalized linear mixed model (GLMM):
#' \itemize{
#' \item \strong{Normalized restricted likelihood ratio test} (nRLRT): Chen et al. (2019)
#' (recommended).
#' \item \strong{Asymptotic-normalized restricted likelihood ratio test} (as-nRLRT).
#' \item \strong{Asymptotic likelihood ratio test} (asLRT): Molenberghs and Verbeke (2007).
#' \item \strong{Normalized Score test} (nScore): (Zhang and Lin 2003).
#' }
#' We recommend using the nRLRT method.
#' This method uses penalized quasi-likelihood (PQL) to approximate the GLMM with a
#' working linear mixed model (LMM), then compares the RLRT statistic to its finite-sample
#' null distribution for hypothesis testing. Compared to the other methods, it
#' a) applies to a greater range of models, b) has better type I error rates, and
#' c) has higher power.
#'
#' These methods are intended for testing a single variance component in a GLMM for
#' responses from an exponential family distribution. This is limited to the distributions
#' that can be estimated using \code{MASS::glmmPQL} or \code{lme4::glmer}. Currently, normal
#' responses are not supported; testing can be done directly with the \code{RLRsim} package.
#'
#' @section glmmVCtest functions:
#' \itemize{
#' \item \code{asymptotic.null}: asymptotic null distribution from Self and Liang (1987)
#' \item \code{nScore}: normalized Score test (Zhang and Lin 2003)
#' \item \code{glmmPQL.mod}: estimate a GLMM using PQL (modification of MASS::glmmPQL)
#' \item \code{test.asnRLRT}: approximate-normalized RLRT
#' \item \code{test.nRLRT}: normalized RLRT (recommended)
#' \item \code{test.asLRT}: asymptotic LRT (Molenberghs and Verbeke 2007)
#' }
#'
#' @docType package
#' @name glmmVCtest
#'
#' @seealso
#' Chen, S. T., Xiao, L., Staicu, A. M. (in prep).
#' Restricted Likelihood Ratio Tests for Variance Components in Generalized Linear Models.
#'
#' Molenberghs, G. and Verbeke, G. (2007).
#' Likehood ratio, score, and wald tests in a constrained parameter space.
#' \emph{The American Statistician} \strong{61}, 22--27.
#'
#' Zhang, D. and Lin, X. (2003).
#' Hypothesis testing in semiparametric additive mixed models.
#' \emph{Biostatistics} \strong{4}, 57--74.
NULL