\Header{ellipsoidhull}{Compute the Ellipsoid Hull or Spanning Ellipsoid of a Point Set}
\alias{print.ellipsoid}{ellipsoidhull}
\keyword{dplot}{ellipsoidhull}
\keyword{hplot}{ellipsoidhull}
\begin{Description}\relax
Compute the ``ellipsoid hull'' or ``spanning ellipsoid'', i.e. the
ellipsoid of minimal volume (`area' in 2D) such that all given points
lie just inside or on the boundary of the ellipsoid.
\end{Description}
\begin{Usage}
\begin{verbatim}
ellipsoidhull(x, tol=0.01, maxit=5000,
              ret.wt = FALSE, ret.sqdist = FALSE, ret.pr = FALSE)
## S3 method for class 'ellipsoid':
print(x, digits = max(1, getOption("digits") - 2), ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] the \eqn{n}{} \eqn{p}{}-dimensional points  asnumeric
\eqn{n\times p}{n x p} matrix.
\item[\code{tol}] convergence tolerance for Titterington's algorithm.
Setting this to much smaller values may drastically increase the number of
iterations needed, and you may want to increas \code{maxit} as well.
\item[\code{maxit}] integer giving the maximal number of iteration steps for
the algorithm.
\item[\code{ret.wt, ret.sqdist, ret.pr}] logicals indicating if additional
information should be returned, \code{ret.wt} specifying the
\emph{weights}, \code{ret.sqdist} the \emph{\bold{sq}uared
\bold{dist}ances} and \code{ret.pr} the final \bold{pr}obabilities
in the algorithms.
\item[\code{digits,...}] the usual arguments to \code{\Link{print}} methods.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The ``spanning ellipsoid'' algorithm is said to stem from
Titterington(1976), in Pison et al(1999) who use it for
\code{\Link{clusplot.default}}.\\
The problem can be seen as a special case of the ``Min.Vol.''
ellipsoid of which a more more flexible and general implementation is
\code{\Link{cov.mve}} in the \code{lqs} package.
\end{Details}
\begin{Value}
an object of class \code{"ellipsoid"}, basically a \code{\Link{list}}
with several components, comprising at least
\begin{ldescription}
\item[\code{cov}] \eqn{p\times p}{p x p} \emph{covariance} matrix description
the ellipsoid.
\item[\code{loc}] \eqn{p}{}-dimensional location of the ellipsoid center.
\item[\code{d2}] average squared radius.
\item[\code{wt}] the vector of weights iff \code{ret.wt} was true.
\item[\code{sqdist}] the vector of squared distances iff \code{ret.sqdist} was true.
\item[\code{prob}] the vector of algorithm probabilities iff \code{ret.pr} was true.
\item[\code{it}] number of iterations used.
\item[\code{tol, maxit}] just the input argument, see above.
\item[\code{eps}] the achieved tolerance which is the maximal squared radius
minus \eqn{p}{}.
\item[\code{ierr}] error code as from the algorithm; \code{0} means \emph{ok}.
\item[\code{conv}] logical indicating if the converged.  This is defined as
\code{it < maxit \&\& ierr == 0}.
\end{ldescription}
\end{Value}
\begin{Author}\relax
Martin Maechler did the present class implementation; Rousseeuw
et al did the underlying code.
\end{Author}
\begin{References}\relax
Pison, G., Struyf, A. and Rousseeuw, P.J. (1999)
Displaying a Clustering with CLUSPLOT,
\emph{Computational Statistics and Data Analysis}, \bold{30}, 381--392.\\
A version of this is available as technical report from
\url{http://win-www.uia.ac.be/u/statis/abstract/Disclu99.htm}

D.N. Titterington. (1976)
Algorithms for computing {D}-optimal design on finite design spaces.  In
\emph{Proc.\ of the 1976 Conf.\ on Information Science and Systems},
213--216; John Hopkins University.
\end{References}
\begin{SeeAlso}\relax
\code{\Link{chull}} for the convex hull,
\code{\Link{clusplot}} which makes use of this; \code{\Link{cov.mve}}.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
x <- rnorm(100)
xy <- unname(cbind(x, rnorm(100) + 2*x + 10))
exy <- ellipsoidhull(xy)
exy # >> calling print.ellipsoid()

plot(xy)
lines(predict(exy))
points(rbind(exy$loc), col = "red", cex = 3, pch = 13)

exy <- ellipsoidhull(xy, tol = 1e-7, ret.wt = TRUE, ret.sq = TRUE)
str(exy) # had small `tol', hence many iterations
(ii <- which(zapsmall(exy $ wt) > 1e-6)) # only about 4 to 6 points
round(exy$wt[ii],3); sum(exy$wt[ii]) # sum to 1
\end{ExampleCode}
\end{Examples}

