% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/LRTSim.R
\name{LRTSim}
\alias{LRTSim}
\alias{RLRTSim}
\title{Simulation of the (Restricted) Likelihood Ratio Statistic}
\usage{
LRTSim(
  X,
  Z,
  q,
  sqrt.Sigma,
  seed = NA,
  nsim = 10000,
  log.grid.hi = 8,
  log.grid.lo = -10,
  gridlength = 200,
  parallel = c("no", "multicore", "snow"),
  ncpus = 1L,
  cl = NULL
)
}
\arguments{
\item{X}{The fixed effects design matrix of the model under the alternative}

\item{Z}{The random effects design matrix of the model under the alternative}

\item{q}{The number of parameters restrictions on the fixed effects (see
Details)}

\item{sqrt.Sigma}{The upper triangular Cholesky factor of the correlation
matrix of the random effect}

\item{seed}{Specify a seed for \code{set.seed}}

\item{nsim}{Number of values to simulate}

\item{log.grid.hi}{Lower value of the grid on the log scale. See
\bold{Details}}

\item{log.grid.lo}{Lower value of the grid on the log scale. See
\bold{Details}}

\item{gridlength}{Length of the grid for the grid search over lambda. See
\bold{Details}}

\item{parallel}{The type of parallel operation to be used (if any). If
missing, the default is "no parallelization").}

\item{ncpus}{integer: number of processes to be used in parallel operation:
typically one would chose this to the number of available CPUs. Defaults to
1, i.e., no parallelization.}

\item{cl}{An optional parallel or snow cluster for use if parallel = "snow".
If not supplied, a cluster on the local machine is created for the duration
of the call.}
}
\value{
A vector containing the the simulated values of the (R)LRT under the
  null, with attribute 'lambda' giving \eqn{\arg\min(f(\lambda))} (see
  Crainiceanu, Ruppert (2004)) for the simulations.
}
\description{
These functions simulate values from the (exact) finite sample distribution
of the (restricted) likelihood ratio statistic for testing the presence of
the variance component (and restrictions of the fixed effects) in a simple
linear mixed model with known correlation structure of the random effect and
i.i.d. errors. They are usually called by \code{exactLRT} or
\code{exactRLRT}.
}
\details{
The model under the alternative must be a linear mixed model
\eqn{y=X\beta+Zb+\varepsilon}{y=X*beta+Z*b+epsilon} with a single random
effect \eqn{b} with known correlation structure \eqn{Sigma} and i.i.d errors.
The simulated distribution of the likelihood ratio statistic was derived by
Crainiceanu & Ruppert (2004). The simulation algorithm uses a grid search over
a log-regular grid of values of
\eqn{\lambda=\frac{Var(b)}{Var(\varepsilon)}}{lambda=Var(b)/Var(epsilon)} to
maximize the likelihood under the alternative for \code{nsim} realizations of
\eqn{y} drawn under the null hypothesis. \code{log.grid.hi} and
\code{log.grid.lo} are the lower and upper limits of this grid on the log
scale. \code{gridlength} is the number of points on the grid.\ These are just
wrapper functions for the underlying C code.
}
\examples{

library(lme4)
g <- rep(1:10, e = 10)
x <- rnorm(100)
y <- 0.1 * x + rnorm(100)
m <- lmer(y ~ x + (1|g), REML=FALSE)
m0 <- lm(y ~ 1)

(obs.LRT <- 2*(logLik(m)-logLik(m0)))
X <- getME(m,"X")
Z <- t(as.matrix(getME(m,"Zt")))
sim.LRT <- LRTSim(X, Z, 1, diag(10))
(pval <- mean(sim.LRT > obs.LRT))

}
\references{
Crainiceanu, C. and Ruppert, D. (2004) Likelihood ratio tests in
  linear mixed models with one variance component, \emph{Journal of the Royal
  Statistical Society: Series B},\bold{66},165--185.

  Scheipl, F. (2007) Testing for nonparametric terms and random effects in
  structured additive regression.  Diploma thesis (unpublished).

  Scheipl, F., Greven, S. and Kuechenhoff, H (2008) Size and power of tests
  for a zero random effect variance or polynomial regression in additive and
  linear mixed models, \emph{Computational Statistics & Data Analysis},
  \bold{52}(7):3283-3299
}
\seealso{
\code{\link{exactLRT}}, \code{\link{exactRLRT}} for tests
}
\author{
Fabian Scheipl; parallelization code adapted from \code{boot} package
}
\keyword{datagen}
\keyword{distribution}
