% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/as_factoextra.R
\name{as_factoextra_pca}
\alias{as_factoextra_pca}
\title{Build a factoextra-ready object from pre-computed coordinates}
\usage{
as_factoextra_pca(
  ind.coord,
  var.coord = NULL,
  eig = NULL,
  ind.cos2 = NULL,
  ind.contrib = NULL,
  var.cos2 = NULL,
  var.contrib = NULL,
  var.cor = NULL,
  scale.unit = FALSE
)
}
\arguments{
\item{ind.coord}{individual (observation) coordinates: a numeric matrix or
data frame with one column per dimension (the "scores"). Required.}

\item{var.coord}{optional variable coordinates / loadings: a numeric matrix or
data frame with one column per dimension. Supplying it enables
\code{fviz_pca_var()} and \code{fviz_pca_biplot()}.}

\item{eig}{optional numeric vector of eigenvalues (length \eqn{\ge} number of
dimensions). Used by the scree plot and to label the axes with the percentage
of explained variance. When \code{NULL} (default) it is set to the variance
of each coordinate column (the natural definition of a PCA eigenvalue).}

\item{ind.cos2, ind.contrib, var.cos2, var.contrib, var.cor}{optional pre-computed
quality (\code{cos2}), contribution and (variable) correlation matrices, with
the same dimensions as the corresponding coordinates. When omitted they are
derived from the coordinates (see \strong{Details}).}

\item{scale.unit}{logical. If \code{TRUE}, the variable coordinates are treated
as correlations and the correlation circle is drawn by \code{fviz_pca_var()}.
Default is \code{FALSE}.}
}
\value{
An object of class \code{c("factoextra_pca", "list")} holding the
  standardized \code{ind} (and \code{var}) results and eigenvalues, ready for
  the \code{fviz_pca_*()} functions.
}
\description{
\code{as_factoextra_pca()} wraps pre-computed individual (and, optionally,
variable) coordinates into an object that the \code{\link{fviz_pca}} family
(\code{fviz_pca_ind()}, \code{fviz_pca_var()}, \code{fviz_pca_biplot()}),
\code{\link{fviz_eig}}, \code{\link{fviz_contrib}} and \code{\link{fviz_cos2}}
can plot directly.

It lets you apply factoextra's visualizations to the output of \emph{any}
dimension-reduction method - for example \code{stats::cmdscale()},
\code{ape::pcoa()}, UMAP/t-SNE embeddings, \code{vegan::rda()}/\code{cca()},
or a custom analysis - without having to write a dedicated backend. You bring
the coordinates; factoextra draws the biplot, scree plot, contributions and
cos2.
}
\details{
When \code{cos2}/\code{contrib} are not supplied they are computed from the
coordinates:
\itemize{
  \item \code{contrib = 100 * coord^2 / colSums(coord^2)} - the exact
    contribution of each element to each dimension.
  \item \code{cos2 = coord^2 / rowSums(coord^2)} - the quality of
    representation \emph{within the supplied dimensions}. This equals the true
    cos2 only when all components are provided; with a truncated set of
    dimensions it is the quality restricted to that sub-space. Pass
    \code{ind.cos2}/\code{var.cos2} explicitly if you have the exact values.
}
}
\examples{
# 1. Bring your own coordinates: classical MDS (cmdscale) -> factoextra
d <- dist(scale(mtcars))
mds <- cmdscale(d, k = 3)
obj <- as_factoextra_pca(ind.coord = mds)
fviz_pca_ind(obj, repel = TRUE)
fviz_eig(obj)

# 2. Round-trip a prcomp result through the constructor (biplot)
pca <- prcomp(iris[, -5], scale. = TRUE)
obj2 <- as_factoextra_pca(
  ind.coord = pca$x,
  var.coord = pca$rotation,
  eig       = pca$sdev^2
)
fviz_pca_biplot(obj2, label = "var", col.ind = "steelblue")

}
\author{
Alboukadel Kassambara \email{alboukadel.kassambara@gmail.com}
}
