\HeaderA{princomp}{Principal Components Analysis}{princomp}
\aliasA{plot.princomp}{princomp}{plot.princomp}
\aliasA{predict.princomp}{princomp}{predict.princomp}
\methaliasA{princomp.default}{princomp}{princomp.default}
\methaliasA{princomp.formula}{princomp}{princomp.formula}
\aliasA{print.princomp}{princomp}{print.princomp}
\keyword{multivariate}{princomp}
\begin{Description}\relax
\code{princomp} performs a principal components analysis on the given
numeric data matrix and returns the results as an object of class
\code{princomp}.
\end{Description}
\begin{Usage}
\begin{verbatim}
princomp(x, ...)

## S3 method for class 'formula':
princomp(formula, data = NULL, subset, na.action, ...)

## Default S3 method:
princomp(x, cor = FALSE, scores = TRUE, covmat = NULL,
         subset = rep(TRUE, nrow(as.matrix(x))), ...)

## S3 method for class 'princomp':
predict(object, newdata, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{formula}] a formula with no response variable, referring only to
numeric variables.
\item[\code{data}] an optional data frame (or similar: see
\code{\LinkA{model.frame}{model.frame}}) containing the variables in the
formula \code{formula}.  By default the variables are taken from
\code{environment(formula)}.
\item[\code{subset}] an optional vector used to select rows (observations) of the
data matrix \code{x}.
\item[\code{na.action}] a function which indicates what should happen
when the data contain \code{NA}s.  The default is set by
the \code{na.action} setting of \code{\LinkA{options}{options}}, and is
\code{\LinkA{na.fail}{na.fail}} if that is unset. The \sQuote{factory-fresh}
default is \code{\LinkA{na.omit}{na.omit}}.
\item[\code{x}] a numeric matrix or data frame which provides the data for the
principal components analysis.
\item[\code{cor}] a logical value indicating whether the calculation should
use the correlation matrix or the covariance matrix.  (The
correlation matrix can only be used if there are no constant variables.)
\item[\code{scores}] a logical value indicating whether the score on each
principal component should be calculated.
\item[\code{covmat}] a covariance matrix, or a covariance list as returned by
\code{\LinkA{cov.wt}{cov.wt}} (and \code{\LinkA{cov.mve}{cov.mve}} or
\code{\LinkA{cov.mcd}{cov.mcd}} from package \pkg{MASS}).
If supplied, this is used rather than the covariance matrix of
\code{x}.
\item[\code{...}] arguments passed to or from other methods. If \code{x} is
a formula one might specify \code{cor} or \code{scores}.
\item[\code{object}] Object of class inheriting from \code{"princomp"}
\item[\code{newdata}] An optional data frame or matrix in which to look for
variables with which to predict.  If omitted, the scores are used.
If the original fit used a formula or a data frame or a matrix with
column names, \code{newdata} must contain columns with the same
names. Otherwise it must contain the same number of columns, to be
used in the same order.

\end{ldescription}
\end{Arguments}
\begin{Details}\relax
\code{princomp} is a generic function with \code{"formula"} and
\code{"default"} methods.

The calculation is done using \code{\LinkA{eigen}{eigen}} on the correlation or
covariance matrix, as determined by \code{\LinkA{cor}{cor}}.  This is done for
compatibility with the S-PLUS result.  A preferred method of
calculation is to use \code{\LinkA{svd}{svd}} on \code{x}, as is done in
\code{prcomp}.

Note that the default calculation uses divisor \code{N} for the
covariance matrix.

The \code{\LinkA{print}{print}} method for these objects prints the
results in a nice format and the \code{\LinkA{plot}{plot}} method produces
a scree plot (\code{\LinkA{screeplot}{screeplot}}).  There is also a
\code{\LinkA{biplot}{biplot}} method.

If \code{x} is a formula then the standard NA-handling is applied to
the scores (if requested): see \code{\LinkA{napredict}{napredict}}.

\code{princomp} only handles so-called R-mode PCA, that is feature
extraction of variables.  If a data matrix is supplied (possibly via a
formula) it is required that there are at least as many units as
variables.  For Q-mode PCA use \code{\LinkA{prcomp}{prcomp}}.
\end{Details}
\begin{Value}
\code{princomp} returns a list with class \code{"princomp"}
containing the following components:
\begin{ldescription}
\item[\code{sdev}] the standard deviations of the principal components.
\item[\code{loadings}] the matrix of variable loadings (i.e., a matrix
whose columns contain the eigenvectors).  This is of class
\code{"loadings"}: see \code{\LinkA{loadings}{loadings}} for its \code{print}
method.
\item[\code{center}] the means that were subtracted.
\item[\code{scale}] the scalings applied to each variable.
\item[\code{n.obs}] the number of observations.
\item[\code{scores}] if \code{scores = TRUE}, the scores of the supplied
data on the principal components.  These are non-null only if
\code{x} was supplied, and if \code{covmat} was also supplied if it
was a covariance list.  For the formula method, \code{napredict} is
applied to handle the treatment of values omitted by the \code{na.action}.
\item[\code{call}] the matched call.
\item[\code{na.action}] If relevant.
\end{ldescription}
\end{Value}
\begin{Note}\relax
The signs of the columns of the loadings and scores are arbitrary, and
so may differ between different programs for PCA, and even between
different builds of \R.
\end{Note}
\begin{References}\relax
Mardia, K. V., J. T. Kent and J. M. Bibby (1979).
\emph{Multivariate Analysis}, London: Academic Press.

Venables, W. N. and B. D. Ripley (2002).
\emph{Modern Applied Statistics with S}, Springer-Verlag.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{summary.princomp}{summary.princomp}}, \code{\LinkA{screeplot}{screeplot}},
\code{\LinkA{biplot.princomp}{biplot.princomp}},
\code{\LinkA{prcomp}{prcomp}}, \code{\LinkA{cor}{cor}}, \code{\LinkA{cov}{cov}},
\code{\LinkA{eigen}{eigen}}.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
require(graphics)

## The variances of the variables in the
## USArrests data vary by orders of magnitude, so scaling is appropriate
(pc.cr <- princomp(USArrests))  # inappropriate
princomp(USArrests, cor = TRUE) # =^= prcomp(USArrests, scale=TRUE)
## Similar, but different:
## The standard deviations differ by a factor of sqrt(49/50)

summary(pc.cr <- princomp(USArrests, cor = TRUE))
loadings(pc.cr)  ## note that blank entries are small but not zero
plot(pc.cr) # shows a screeplot.
biplot(pc.cr)

## Formula interface
princomp(~ ., data = USArrests, cor = TRUE)
# NA-handling
USArrests[1, 2] <- NA
pc.cr <- princomp(~ Murder + Assault + UrbanPop,
                  data = USArrests, na.action=na.exclude, cor = TRUE)
pc.cr$scores
\end{ExampleCode}
\end{Examples}

