% file lqs/man/cov.rob.Rd
% copyright (C) 1998-9 B. D. Ripley
%
\name{cov.rob}
\alias{cov.rob}
\alias{cov.mve}
\alias{cov.mcd}
\title{
  Resistant Estimation of Multivariate Location and Scatter
}
\description{
  Compute a multivariate location and scale estimate with a high
  breakdown point -- this can be thought of as estimating the mean and
  covariance of the \code{good} part of the data. \code{cov.mve} and
  \code{cov.mcd} are compatibility wrappers.
}
\usage{
cov.rob(x, cor = FALSE, quantile.used = floor((n + p + 1)/2),
        method = c("mve", "mcd", "classical"), nsamp = "best", seed)
cov.mve(x, cor = FALSE, quantile.used = floor((n + p + 1)/2),
        nsamp = "best", seed)
cov.mcd(x, cor = FALSE, quantile.used = floor((n + p + 1)/2),
        nsamp = "best", seed)
}
\synopsis{
cov.rob(x, cor = FALSE, quantile.used = floor((n + p + 1)/2),
        method = c("mve", "mcd", "classical"), nsamp = "best", seed)
cov.mve(\dots)
cov.mcd(\dots)
}
\arguments{
\item{x}{
  a matrix or data frame.
}
\item{cor}{
  should the returned result include a correlation matrix?
}
\item{quantile.used}{
  the minimum number of the data points regarded as \code{good} points.
}
\item{method}{
  the method to be used -- minimum volume ellipsoid, minimum
  covariance determinant or classical product-moment. Using
  \code{cov.mve} or \code{cov.mcd} forces \code{mve} or \code{mcd}
  respectively.
}
\item{nsamp}{
  the number of samples or \code{"best"} or \code{"exact"} or
  \code{"sample"}.
  If \code{"sample"} the number chosen is \code{min(5*p, 3000)}, taken
  from Rousseeuw and Hubert (1997). If \code{"best"} exhaustive
  enumeration is done up to 5000 samples: if \code{"exact"}
  exhaustive enumeration will be attempted however many samples are needed.
}
\item{seed}{
  the seed to be used for random sampling: see \code{\link{RNGkind}}. The
  current value of \code{.Random.seed} will be preserved if it is set.
}}
\value{
  A list with components

  \item{center}{
    the final estimate of location.
  }
  \item{cov}{
    the final estimate of scatter.
  }
  \item{cor}{
    (only is \code{cor = TRUE}) the estimate of the correlation
    matrix.
  }
  \item{sing}{
    message giving number of singular samples out of total
  }
  \item{crit}{
    the value of the criterion on log scale. For MCD this is
    the determinant, and for MVE it is proportional to the volume.
  }
  \item{best}{
    the subset used. For MVE the best sample, for MCD the best
    set of size \code{quantile.used}.
  }
  \item{n.obs}{
    total number of observations.
}}
\details{
  For method \code{"mve"}, an approximate search is made of a subset of
  size \code{quantile.used} with an enclosing ellipsoid of smallest volume; in
  method \code{"mcd"} it is the volume of the Gaussian confidence
  ellipsoid, equivalently the determinant of the classical covariance
  matrix, that is minimized. The mean of the subset provides a first
  estimate of the location, and the rescaled covariance matrix a first
  estimate of scatter. The Mahalanobis distances of all the points from
  the location estimate for this covariance matrix are calculated, and
  those points within the 97.5\% point under Gaussian assumptions are
  declared to be \code{good}. The final estimates are the mean and rescaled
  covariance of the \code{good} points.

  The rescaling is by the appropriate percentile under Gaussian data; in
  addition the first covariance matrix has an \emph{ad hoc} finite-sample
  correction given by Marazzi.

  For method \code{"mve"} the search is made over ellipsoids determined
  by the covariance matrix of \code{p} of the data points. For method
  \code{"mcd"} an additional improvement step suggested by Rousseeuw and
  van Driessen (1997) is used, in which once a subset of size
  \code{quantile.used} is selected, an ellipsoid based on its covariance
  is tested (as this will have no larger a determinant, and may be smaller).
}
\author{B.D. Ripley}
\references{
  P. J. Rousseeuw and A. M. Leroy (1987) 
  \emph{Robust Regression and Outlier Detection.}
  Wiley.

  A. Marazzi (1993) 
  \emph{Algorithms, Routines and S Functions for Robust Statistics.}
  Wadsworth and Brooks/Cole. 

  P. J. Rousseeuw and B. C. van Zomeren (1990) Unmasking
  multivariate outliers and leverage points, 
  \emph{Journal of the American Statistical Association}, \bold{85}, 633--639.

  P. J. Rousseeuw and K. van Driessen (1999) A fast algorithm for the
  minimum covariance determinant estimator. \emph{Technometrics}
  \bold{41}, 212--223.

  P. Rousseeuw and M. Hubert (1997) Recent developments in PROGRESS. In
  \emph{L1-Statistical Procedures and Related Topics }
  ed Y. Dodge, IMS Lecture Notes volume \bold{31}, pp. 201--214.
}
\seealso{
\code{\link{lqs}}
}
\examples{
data(stackloss)
set.seed(123)
cov.rob(stackloss)
cov.rob(stack.x, method = "mcd", nsamp = "exact")
}
\keyword{robust}
\keyword{multivariate}
% file lqs/man/lqs.Rd
% copyright (C) 1998-9 B. D. Ripley    (C) 2001-2 R Core Development Team
%
\name{lqs}
\alias{lqs}
\alias{lqs.formula}
\alias{lqs.default}
\alias{lmsreg}
\alias{ltsreg}
\alias{print.lqs}
\title{
Resistant Regression
}
\description{
  Fit a regression to the \emph{good} points in the dataset, thereby
  achieving a regression estimator with a high breakdown point.
  \code{lmsreg} and \code{ltsreg} are compatibility wrappers.
}
\synopsis{
lqs(x, \dots)
lqs.formula(formula, data, \dots,
            method = c("lts", "lqs", "lms", "S", "model.frame"),
            subset, na.action = na.fail, model = TRUE,
            x.ret = FALSE, y.ret = FALSE, contrasts = NULL)
lqs.default(x, y, intercept = TRUE, method = c("lts", "lqs", "lms", "S"),
            quantile, control = lqs.control(\dots), k0 = 1.548, seed, \dots)
lmsreg(\ldots)
ltsreg(\ldots)
}
\usage{
lqs(x, \dots)
lqs.formula(formula, data, \dots,
            method = c("lts", "lqs", "lms", "S", "model.frame"),
            subset, na.action = na.fail, model = TRUE,
            x = FALSE, y = FALSE, contrasts = NULL)
lqs.default(x, y, intercept = TRUE, method = c("lts", "lqs", "lms", "S"),
            quantile, control = lqs.control(\dots), k0 = 1.548, seed, \dots)
lmsreg(\ldots)
ltsreg(\ldots)
}
\arguments{
  \item{formula}{a formula of the form \code{y ~ x1 + x2 + \dots}.}
  \item{data}{data frame from which variables specified in
    \code{formula} are preferentially to be taken.}
  \item{subset}{an index vector specifying the cases to be used in
    fitting. (NOTE: If given, this argument must be named exactly.)}
  \item{na.action}{function to specify the action to be taken if
    \code{NA}s are found.  The default action is for the procedure to
    fail.  Alternatives include \code{\link{na.omit}} and
    \code{\link{na.exclude}}, which lead to omission of
    cases with missing values on any required variable.  (NOTE: If
    given, this argument must be named exactly.)
  }
  \item{model}{logical. If \code{TRUE} the model frame is returned.}
  \item{contrasts}{an optional list.  See the \code{contrasts.arg}
    of \code{\link{model.matrix.default}}.}
  \item{x}{a matrix or data frame containing the explanatory variables.}
  \item{y}{the response: a vector of length the number of rows of \code{x}.}
  \item{intercept}{should the model include an intercept?}
  \item{method}{
    the method to be used. \code{model.frame} returns the model frame: for the
    others see the \code{Details} section. Using \code{lmsreg} or
    \code{ltsreg} forces \code{"lms"} and \code{"lts"} respectively.
  }
  \item{quantile}{
    the quantile to be used: see \code{Details}. This is over-ridden if
    \code{method = "lms"}.
  }
  \item{control}{additional control items: see \code{Details}.}
  \item{k0}{the cutoff / tuning constant used for \eqn{\chi()}{chi()}
    and \eqn{\psi()}{psi()} functions when \code{method = "S"}, currently
    corresponding to Tukey's ``biweight''.}
  \item{seed}{
    the seed to be used for random sampling: see \code{.Random.seed}. The
    current value of \code{.Random.seed} will be preserved if it is set..
  }
  \item{\dots}{arguments to be passed to \code{lqs.default} or
    \code{lqs.control}, see \code{control} above and \code{Details}.}
}
\value{
  An object of class \code{"lqs"}.  This is a list with components
  \item{crit}{the value of the criterion for the best solution found, in
    the case of \code{method == "S"} before IWLS refinement.}
  \item{sing}{character. A message about the number of samples which
    resulted in singular fits.}
  \item{coefficients}{of the fitted linear model}
  \item{bestone}{the indices of those points fitted by the best sample
    found (prior to adjustment of the intercept, if requested).}
  \item{fitted.values}{the fitted values.}
  \item{residuals}{the residuals.}
  \item{scale}{estimate(s) of the scale of the error. The first is based
    on the fit criterion.  The second (not present for \code{method ==
      "S"}) is based on the variance of those residuals whose absolute
    value is less than 2.5 times the initial estimate.}
}
\details{
  Suppose there are \code{n} data points and \code{p} regressors,
  including any intercept.

  The first three methods minimize some function of the sorted squared
  residuals. For methods \code{"lqs"} and \code{"lms"} is the
  \code{quantile} squared residual, and for \code{"lts"} it is the sum
  of the \code{quantile} smallest squared residuals. \code{"lqs"} and
  \code{"lms"} differ in the defaults for \code{quantile}, which are
  \code{floor((n+p+1)/2)} and \code{floor((n+1)/2)} respectively.
  For \code{"lts"} the default is \code{floor(n/2) + floor((p+1)/2)}.

  The \code{"S"} estimation method solves for the scale \code{s}
  such that the average of a function chi of the residuals divided
  by \code{s} is equal to a given constant.

  The \code{control} argument is a list with components
  \describe{
    \item{\code{psamp}:}{the size of each sample. Defaults to \code{p}.}
    \item{\code{nsamp}:}{the number of samples or \code{"best"} (the
      default) or \code{"exact"} or \code{"sample"}.
      If \code{"sample"} the number chosen is \code{min(5*p, 3000)},
      taken from Rousseeuw and Hubert (1997).
      If \code{"best"} exhaustive enumeration is done up to 5000 samples;
      if \code{"exact"} exhaustive enumeration will be attempted however
      many samples are needed.}
    \item{\code{adjust}:}{should the intercept be optimized for each
      sample?  Defaults to \code{TRUE}.}
    }
}
\note{
  There seems no reason other than historical to use the \code{lms} and
  \code{lqs} options.  LMS estimation is of low efficiency (converging
  at rate \eqn{n^{-1/3}}) whereas LTS has the same asymptotic efficiency
  as an M estimator with trimming at the quartiles (Marazzi, 1993, p.201).
  LQS and LTS have the same maximal breakdown value of
  \code{(floor((n-p)/2) + 1)/n} attained if
  \code{floor((n+p)/2) <= quantile <= floor((n+p+1)/2)}.
  The only drawback mentioned of LTS is greater computation, as a sort
  was thought to be required (Marazzi, 1993, p.201) but this is not
  true as a partial sort can be used (and is used in this implementation).

  Adjusting the intercept for each trial fit does need the residuals to
  be sorted, and may be significant extra computation if \code{n} is large
  and \code{p} small.

  Opinions differ over the choice of \code{psamp}.  Rousseeuw and Hubert
  (1997) only consider p; Marazzi (1993) recommends p+1 and suggests
  that more samples are better than adjustment for a given computational
  limit.

  The computations are exact for a model with just an intercept and
  adjustment, and for LQS for a model with an intercept plus one
  regressor and exhaustive search with adjustment. For all other cases
  the minimization is only known to be approximate.
}
\author{B. D. Ripley}
\references{
  P. J. Rousseeuw and A. M. Leroy (1987)
  \emph{Robust Regression and Outlier Detection.}
  Wiley.

  A. Marazzi (1993)
  \emph{Algorithms, Routines and S Functions for Robust Statistics.}
  Wadsworth and Brooks/Cole.

  P. Rousseeuw and M. Hubert (1997) Recent developments in PROGRESS. In
  \emph{L1-Statistical Procedures and Related Topics},
  ed Y. Dodge, IMS Lecture Notes volume \bold{31}, pp. 201--214.
}
\seealso{
\code{\link{predict.lqs}}
}
\examples{
data(stackloss)
set.seed(123)
lqs(stack.loss ~ ., data = stackloss)
lqs(stack.loss ~ ., data = stackloss, method = "S", nsamp = "exact")
}
\keyword{models}
\keyword{robust}
% file lqs/man//predict.lqs.Rd
% copyright (C) 1999 B. D. Ripley
%
\name{predict.lqs}
\alias{predict.lqs}
\title{
  Predict from an lqs Fit
}
\description{
  Predict from an resistant regression fitted by \code{lqs}.
}
\usage{
\method{predict}{lqs}(object, newdata, \dots)
}
\arguments{
  \item{object}{
    object inheriting from class \code{"lqs"}
  }
  \item{newdata}{
    matrix or data frame of cases to be predicted or, if object
    has a formula, a data frame with columns of the same names as the
    variables used. A vector will be interpreted
    as a row vector.  If \code{newdata} is missing, an attempt will be
    made to retrieve the data used to fit the \code{lqs} object.
  }
  \item{\dots}{arguments to be passed from or to other methods.}
}
\value{
  A vector of predictions.
}
\details{
  This function is a method for the generic function
  \code{predict()} for class \code{lqs}.
  It can be invoked by calling \code{predict(x)} for an
  object \code{x} of the appropriate class, or directly by
  calling \code{predict.lqs(x)} regardless of the
  class of the object.

  Missing values in \code{newdata} are handled by returning \code{NA} if the
  linear discriminants cannot be evaluated. If \code{newdata} is omitted and
  the \code{na.action} of the fit omitted cases, these will be omitted on the
  prediction.
}
\author{B.D. Ripley}
\seealso{
\code{\link{lqs}}
}
\examples{
data(stackloss)
set.seed(123)
fm <- lqs(stack.loss ~ ., data = stackloss, method = "S", nsamp = "exact")
predict(fm, stackloss)
}
\keyword{models}
