% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/lmm.rrpp.r
\name{lmm.rrpp}
\alias{lmm.rrpp}
\title{Mixed Linear Model Evaluation with RRPP performed within subjects}
\usage{
lmm.rrpp(
  fixed,
  subjects,
  type = c("intercepts", "slopes"),
  slopeTerm = NULL,
  estimation = c("REML", "ML", "LS"),
  iter = 999,
  data,
  ...
)
}
\arguments{
\item{fixed}{A formula for the fixed effects of linear model (e.g., y~x1+x2).}

\item{subjects}{A variable that can be found in the data frame indicating the research subjects
for the analysis.  This variable must be in the data frame.  Is can be either numeric 
(if its slot in the data frame is known) or a character, e.g., "sub_id".  It is imperative that
it is ordered the same as the data but that the data do not have row names the same as subjects.
For example, the subjects variable in the data frame might be sub_id: sub1, sub1, sub1, sub2,
sub2, sub2, ... and the row names of the data might be obs1, obs2, obs3, obs4, obs5, obs6, ...  
The data do not need to have row names but the subjects variable has to be provided.}

\item{type}{An indication whether to use random intercepts ("intercepts") or random intercepts 
and slopes ("slopes") for random effects associated with subjects.}

\item{slopeTerm}{An optional character value (e.g., "mass") indicating which term in the data frame is to be
used in the estimation of random slopes.  This term should also be in the fixed formula.}

\item{estimation}{One of "LS", "ML", or "REML", for guiding how random effects should be estimated.}

\item{iter}{Number of iterations for significance testing}

\item{data}{A data frame for the function environment, see 
\code{\link{rrpp.data.frame}}.  A data frame is required for this analysis.}

\item{...}{Arguments typically used in \code{\link{lm}}, \code{\link{lm.rrpp}},
or \code{\link{lm.rrpp.ws}} such as weights or offset, seed for permutations, etc., passed on to
\code{lm.rrpp.ws} for estimation of coefficients.}
}
\value{
An object of class \code{lmm.rrpp} is a list containing the 
following
\item{call}{The matched call.}
\item{LM}{Linear Model objects, including data (Y), coefficients, 
design matrix (X), sample size
(n), number of dependent variables (p), dimension of data space (p.prime),
QR decomposition of the design matrix, fitted values, residuals,
weights, offset, model terms, data (model) frame, random coefficients 
(through permutations),
random vector distances for coefficients (through permutations), 
whether OLS or GLS was performed, 
and the mean for OLS and/or GLS methods. Note that the data returned 
resemble a model frame rather than 
a data frame; i.e., it contains the values used in analysis, which 
might have been transformed according to 
the formula.  The response variables are always labeled Y.1, Y.2, ..., 
in this frame.  Most important objects for mixed models are also found here. }
\item{ANOVA}{Analysis of variance objects, including the SS type, 
random SS outcomes, random MS outcomes,
random R-squared outcomes, random F outcomes, random Cohen's f-squared 
outcomes, P-values based on random F
outcomes, effect sizes for random outcomes, sample size (n), number of 
variables (p), and degrees of freedom for
model terms (df).  These objects are used to construct ANOVA tables.}
\item{PermInfo}{Permutation procedure information, including the number 
of permutations (perms), The method
of residual randomization (perm.method), and each permutation's sampling 
frame (perm.schedule), which
is a list of reordered sequences of 1:n, for how residuals were 
randomized.}
\item{devcomp}{Deviance components, a list of components used
in deviance and likelihood calculations.}
}
\description{
Function performs a mixed linear model fit over many random permutations of 
data, using a randomized residual permutation procedure restricted to
subjects.  This function is likely to evolve greater flexibility in the future.
}
\details{
The function fits a mixed linear model using ordinary least squares (OLS) or 
generalized least squares (GLS) estimation of coefficients for fixed effects, and 
maximum likelihood (ML) or restricted ML (REML) for random effects, over any 
number of random permutations of the data, but the permutations are mostly 
restricted to occur with subject blocks for any model terms other than subjects.  
Most functionality should resemble that of \code{\link{lm.rrpp}} and \code{\link{lm.rrpp.ws}},  
with some caveats.  First, estimation of random effects uses the methodology of the 
\code{\link[lme4]{lmer}} function (Bates et al., 2015), 
for only one random term based on a subjects designation.  
Second, this means that a "random slopes" model involves an interaction between subjects and a numeric 
variable (not a categorical variable).  Third, although any number of fixed effects can be used,
only one fixed effect can interaction with subjects. Finally, the function is intended to allow
analysis of variance (ANOVA), like with \code{\link{lm.rrpp.ws}}, but not treated random 
effects as fixed.  
There is not a coefficients test associated with this function, as with other \code{\link{lm.rrpp}}
that include only fixed effects.

Although this function allows covariance matrices to be used for generalized least squares (GLS)
estimation of fixed effects, it does not currently 
expand the covariance mnatrix based only on subjects, as does 
\code{\link{lm.rrpp.ws}}.  However, that function can be used to obtain a covariance matrix for this 
function.  The covariance structure (Lambda matrix) among subjects is estimated via ML or REML (Bates et al., 2015) and 
is not impacted by the expected covariances among fixed effects, however, the expected covariances
will influence interactions between fixed and random effects.  The Lambda matrix is estimated as a single matrix,
even for multivariate data.  This matrix is obtained by projecting data onto the first component of
a singular value decomposition of the product between the data and a hat matrix of the the fixed effects 
(basically projection following a principal component analysis of model fitted values).  This is a computationally
proficient step that is similar to averaging covariance parameters (theta) over all variables.
If independent Lambda matrices are desired, then this function can be used on, e.g., each principal
component of data, followed by combining the coefficients.  For ANOVA, the precise estimation of Lambda
is not as important for tests of fixed effects, as it means a linear transformation of coefficients
that would be consistent across random permutations of RRPP.  It might be more important for model 
comparison and selection, in which case whether to use LS, ML, REML, and whether to use separate Lambda matrices
is a much deeper consideration.

A data frame (preferably an \code{\link{rrpp.data.frame}} object) must be
used for this function.  Not all "downstream" functions (e.g., logLik, predict) are guaranteed 
to work as expected, as this function is still very much under development.

The \code{\link{lm.rrpp}} arguments not available for this function include: 
full.resid, block, and SS.type.  These arguments are fixed because of
the within-subject blocking for tests, plus the requirement for type II SS
for within-subject effects.
}
\examples{
\dontrun{
# Random intercepts models

data(ReptAbund)
fit_ls <- lmm.rrpp(fixed = reptile_abundance ~ Year, 
subjects = "Site",      
type = "intercepts", 
estimation = "LS", 
data = ReptAbund)

fit_ml <- lmm.rrpp(fixed = reptile_abundance ~ Year, 
subjects = "Site",      
type = "intercepts", 
estimation = "ML", 
data = ReptAbund)

fit_reml <- lmm.rrpp(fixed = reptile_abundance ~ Year, 
subjects = "Site",      
type = "intercepts", 
estimation = "REML", 
data = ReptAbund) 

anova(fit_ls, error = c("Site", "Residuals"))
anova(fit_ml, error = c("Site", "Residuals"))
anova(fit_reml, error = c("Site", "Residuals"))

coef(fit_ls, type = "list")
coef(fit_ml, type = "list")
coef(fit_reml, type = "list")

# Random slopes models
# none should not work!

fit_ls <- lmm.rrpp(fixed = reptile_abundance ~ Year, 
subjects = "Site",      
type = "slopes",
slopeTerm = "Year", 
estimation = "LS", 
data = ReptAbund)

fit_ml <- lmm.rrpp(fixed = reptile_abundance ~ Year, 
subjects = "Site",      
type = "slopes",
slopeTerm = "Year", 
estimation = "ML", 
data = ReptAbund)


fit_reml <- lmm.rrpp(fixed = reptile_abundance ~ Year, 
subjects = "Site",      
type = "slopes",
slopeTerm = "Year",  
estimation = "REML", 
data = ReptAbund) 

anova(fit_ls, error = c("Year:Site", "Year:Site", "Residuals"))
anova(fit_ml, error = c("Year:Site", "Year:Site", "Residuals"))

coef(fit_ls, type = "list")
coef(fit_ml, type = "list")
 }
}
\references{
Douglas Bates, Martin Maechler, Ben Bolker, Steve Walker (2015). Fitting Linear
Mixed-Effects Models Using lme4. Journal of Statistical Software, 67(1), 1-48.
doi:10.18637/jss.v067.i01.

\subsection{Limitations}{
This function currently only works for "Random Intercepts" and "Random slopes" models,
where the intercepts or slopes of a single subject term (random effect) are free to vary.  
If a Random Slopes model is used, a single covariate (numeric variable) must be specified for slopes.  
Generally, this is term that is also among the fixed effects.  These limitations are imposed
to allow ML or REML estimation.  More complex models can be entertained with \code{lmm.rrpp.ws},
but using only "LS" estimation.  If "LS" estimation is used in this function, results should be the same
with a comparable formula, using \code{lmm.rrpp.ws}

If a ML or REML fit is near singular (one or more covariance parameters are 0), the analysis will be arrested
rather than continued with some random effects rendered as 0.  This should be an indication that the model
is over-fit with the type of estimation used. 

These limitations might be addressed with future versions of this function, as theoretical advances are made.
 }
}
\seealso{
\code{\link{lm.rrpp}}; \code{\link{lm.rrpp.ws}}; \code{\link{measurement.error}}
}
\author{
Michael Collyer
}
\keyword{analysis}
