\name{lmeWinsor}
\alias{lmeWinsor}
\title{
Winsorized Regression with mixed effects
}
\description{
Clip inputs and mixed-effects predictions to (upper, lower) or to
selected quantiles to limit wild predictions outside the training
set.
}
\usage{
lmeWinsor(fixed, data, random, lower=NULL, upper=NULL, trim=0,
quantileType=7, correlation, weights, subset, method,
na.action, control, contrasts = NULL, keep.data=TRUE,
...)
}
\arguments{
\item{fixed}{
a two-sided linear formula object describing the fixed-effects part
of the model, with the response on the left of a '~' operator and
the terms, separated by '+' operators, on the right. The left hand
side of 'formula' must be a single vector in 'data', untransformed.
}
\item{data}{
an optional data frame containing the variables named in 'fixed',
'random', 'correlation', 'weights', and 'subset'. By default the
variables are taken from the environment from which \link[nlme]{lme}
is called.
}
\item{random}{
a random- / mixed-effects specification, as described with
\link[nlme]{lme}.
NOTE: Unlike \link[nlme]{lme}, 'random' must be provided; it can
not be inferred from 'data'.
}
\item{lower, upper}{
optional numeric vectors with names matching columns of 'data'
giving limits on the ranges of predictors and predictions: If
present, values below 'lower' will be increased to 'lower', and
values above 'upper' will be decreased to 'upper'. If absent, these
limit(s) will be inferred from quantile(..., prob=c(trim, 1-trim),
na.rm=TRUE, type=quantileType).
}
\item{trim}{
the fraction (0 to 0.5) of observations to be considered outside the
range of the data in determining limits not specified in 'lower' and
'upper'.
NOTES:
(1) trim>0 with a singular fit may give an error. In such cases,
fix the singularity and retry.
(2) trim = 0.5 should NOT be used except to check the algorithm,
because it trims everything to the median, thereby providing zero
leverage for estimating a regression.
(3) The current algorithm does does NOT adjust any of the variance
parameter estimates to account for predictions outside 'lower' and
'upper'. This will have no effect for trim = 0 or trim otherwise so
small that there are not predictions outside 'lower' and 'upper'.
However, for more substantive trimming, this could be an issue.
This is different from \link{lmWinsor}.
}
\item{quantileType}{
an integer between 1 and 9 selecting one of the nine quantile
algorithms to be used with 'trim' to determine limits not provided
with 'lower' and 'upper'.
}
\item{correlation}{
an optional correlation structure, as described with
\link[nlme]{lme}.
}
\item{weights}{
an optional heteroscedasticity structure, as described with
\link[nlme]{lme}.
}
\item{ subset }{
an optional vector specifying a subset of observations to be used in
the fitting process, as described with \link[nlme]{lme}.
}
\item{method}{
a character string. If '"REML"' the model is fit by maximizing the
restricted log-likelihood. If '"ML"' the log-likelihood is
maximized. Defaults to '"REML"'.
}
\item{ na.action }{
a function that indicates what should happen when the data contain
'NA's. The default action ('na.fail') causes 'lme' to print an
error message and terminate if there are any incomplete
observations.
}
\item{control}{
a list of control values for the estimation algorithm to replace the
default values returned by the function
\link[nlme]{lmeControl}. Defaults to an empty list.
NOTE: Other control parameters such as 'singular.ok' as documented
in \link[nlme]{glsControl} may also work, but should be used with
caution.
}
\item{ contrasts }{
an optional list. See the 'contrasts.arg' of
'model.matrix.default'.
}
\item{keep.data}{
logical: should the 'data' argument (if supplied and a data frame)
be saved as part of the model object?
}
\item{\dots}{
additional arguments to be passed to the low level regression
fitting functions; see \link[nlme]{lme}.
}
}
\details{
1. Identify inputs and outputs as follows:
1.1. mdly <- mdlx <- fixed; mdly[[3]] <- NULL; mdlx[[2]] <- NULL;
1.2. xNames <- c(all.vars(mdlx), all.vars(random)).
1.3. yNames <- all.vars(mdly). Give an error if
as.character(mdly[[2]]) != yNames.
2. Do 'lower' and 'upper' contain limits for all numeric columns of
'data? Create limits to fill any missing.
3. clipData = data with all xNames clipped to (lower, upper).
4. fit0 <- lme(...)
5. Add components lower and upper to fit0 and convert it to class
c('lmeWinsor', 'lme').
6. Clip any stored predictions at the Winsor limits for 'y'.
NOTE: This is different from \link{lmWinsor}, which uses quadratic
programming with predictions outside limits, transferring extreme
points one at a time to constraints that force the unWinsorized
predictions for those points to be at least as extreme as the limits.
}
\value{
an object of class c('lmeWinsor', 'lme') with 'lower', 'upper', and
'message' components in addition to the standard 'lm' components. The
'message' is a list with its first component being either 'all
predictions inside limits' or 'predictions outside limits'. In the
latter case, there rest of the list summarizes how many and which
points have predictions outside limits.
}
\author{ Spencer Graves }
\seealso{
\code{\link{lmWinsor}}
\code{\link{predict.lmeWinsor}}
\code{\link[nlme]{lme}}
\code{\link{quantile}}
}
\examples{
fm1w <- lmeWinsor(distance ~ age, data = Orthodont,
random=~age|Subject)
fm1w.1 <- lmeWinsor(distance ~ age, data = Orthodont,
random=~age|Subject, trim=0.1)
}
\keyword{ models }