The R Project SVN – R – Diff – /trunk/src/library/stats/man/prcomp.Rd

 % File src/library/stats/man/prcomp.Rd
 % Part of the R package, https://www.R-project.org
-% Copyright 1995-2012 R Core Team
+% Copyright 1995-2016 R Core Team
 % Distributed under GPL 2 or later
 \name{prcomp}
+\title{Principal Components Analysis}
 \alias{prcomp}
 \alias{prcomp.formula}
 \alias{prcomp.default}
 \alias{plot.prcomp}
 \alias{predict.prcomp}
 \alias{print.prcomp}
 \alias{summary.prcomp}
 \alias{print.summary.prcomp}
 \concept{PCA}
-\title{Principal Components Analysis}
 \description{
   Performs a principal components analysis on the given data matrix
   and returns the results as an object of class \code{prcomp}.}
 \usage{
 prcomp(x, \dots)
 \method{prcomp}{formula}(formula, data = NULL, subset, na.action, \dots)
 \method{prcomp}{default}(x, retx = TRUE, center = TRUE, scale. = FALSE,
-       tol = NULL, \dots)
+       tol = NULL, rank. = NULL, \dots)
 \method{predict}{prcomp}(object, newdata, \dots)
+}
 \arguments{
   \item{formula}{a formula with no response variable, referring only to
   \item{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{\link{options}}, and is
     \code{\link{na.fail}} if that is unset. The \sQuote{factory-fresh}
     default is \code{\link{na.omit}}.}
-  \item{\dots}{arguments passed to or from other methods. If \code{x} is
+  \item{\dots}{arguments passed to or from other methods.  If \code{x} is
     a formula one might specify \code{scale.} or \code{tol}.}
   \item{x}{a numeric or complex matrix (or data frame) which provides
     the data for the principal components analysis.}
   \item{retx}{a logical value indicating whether the rotated variables
     should be returned.}
     should be shifted to be zero centered. Alternately, a vector of
     length equal the number of columns of \code{x} can be supplied.
     The value is passed to \code{scale}.}
   \item{scale.}{a logical value indicating whether the variables should
     be scaled to have unit variance before the analysis takes
-    place. The default is \code{FALSE} for consistency with S, but
+    place.  The default is \code{FALSE} for consistency with S, but
     in general scaling is advisable.  Alternatively, a vector of length
     equal the number of columns of \code{x} can be supplied.  The
     value is passed to \code{\link{scale}}.}
   \item{tol}{a value indicating the magnitude below which components
     should be omitted. (Components are omitted if their
     standard deviations are less than or equal to \code{tol} times the
-    standard deviation of the first component.)
+    standard deviation of the first component.)  With the default null
-    With the default null setting, no components
+    setting, no components are omitted (unless \code{rank.} is specified
-    are omitted.  Other settings for tol could be \code{tol = 0} or
+    less than \code{min(dim(x))}.).  Other settings for tol could be
-    \code{tol = sqrt(.Machine$double.eps)}, which would omit
+    \code{tol = 0} or \code{tol = sqrt(.Machine$double.eps)}, which
-    essentially constant components.}
+    would omit essentially constant components.}
+  \item{rank.}{optionally, a number specifying the maximal rank, i.e.,
+    maximal number of principal components to be used.  Can be set as
+    alternative or in addition to \code{tol}, useful notably when the
+    desired rank is considerably smaller than the dimensions of the matrix.}
-  \item{object}{Object of class inheriting from \code{"prcomp"}}
+  \item{object}{object of class inheriting from \code{"prcomp"}}
   \item{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
 \seealso{
   \code{\link{biplot.prcomp}}, \code{\link{screeplot}},
   \code{\link{princomp}}, \code{\link{cor}}, \code{\link{cov}},
   \code{\link{svd}}, \code{\link{eigen}}.
+}
+\examples{
+C <- chol(S <- toeplitz(.9 ^ (0:31))) # Cov.matrix and its root
+all.equal(S, crossprod(C))
+set.seed(17)
+X <- matrix(rnorm(32000), 1000, 32)
+Z <- X \%*\% C  ## ==>  cov(Z) ~=  C'C = S
+all.equal(cov(Z), S, tol = 0.08)
+pZ <- prcomp(Z, tol = 0.1)
+summary(pZ) # only ~14 PCs (out of 32)
-\examples{\donttest{## signs are random
+## or choose only 3 PCs more directly:
-require(graphics)
+pz3 <- prcomp(Z, rank. = 3)
+summary(pz3) # same numbers as the first 3 above
+stopifnot(ncol(pZ$rotation) == 14, ncol(pz3$rotation) == 3,
+          all.equal(pz3$sdev, pZ$sdev, tol = 1e-15)) # exactly equal typically
+\donttest{## signs are random
+require(graphics)
 ## the variances of the variables in the
 ## USArrests data vary by orders of magnitude, so scaling is appropriate
 prcomp(USArrests)  # inappropriate
 prcomp(USArrests, scale = TRUE)
 prcomp(~ Murder + Assault + Rape, data = USArrests, scale = TRUE)
 plot(prcomp(USArrests))
 summary(prcomp(USArrests, scale = TRUE))
 biplot(prcomp(USArrests, scale = TRUE))
+}
-}}
+}
 \keyword{multivariate}

The R Project SVN R

(root)/trunk/src/library/stats/man/prcomp.Rd – Rev 68948 → 70391