% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/S3_decompositions.R
\name{prcomp.HDF5Matrix}
\alias{prcomp.HDF5Matrix}
\title{Principal Component Analysis of an HDF5Matrix}
\usage{
\method{prcomp}{HDF5Matrix}(
  x,
  retx = TRUE,
  center = TRUE,
  scale. = FALSE,
  tol = NULL,
  rank. = NULL,
  ncomponents = 0L,
  k = 2L,
  q = 1L,
  method = "auto",
  rankthreshold = 0,
  svdgroup = "SVD/",
  overwrite = FALSE,
  threads = -1L,
  ...
)
}
\arguments{
\item{x}{An \code{HDF5Matrix} object.}

\item{retx}{Logical.  If \code{TRUE} (default) return the individual
coordinates (\code{x} slot).  If \code{FALSE} the \code{x} slot is
\code{NULL} in the returned object.}

\item{center}{Logical.  Subtract column means before PCA (default \code{TRUE}).}

\item{scale.}{Logical.  Divide by column SDs before PCA (default \code{FALSE}).}

\item{tol}{Ignored (present for interface compatibility with \code{prcomp()}).}

\item{rank.}{Integer. Number of principal components to compute. When
supplied (non-\code{NULL}), takes precedence over \code{ncomponents}.
Present for compatibility with \code{stats::prcomp()}; unlike the base R
method, it is not ignored here.}

\item{ncomponents}{Integer.  Number of PCs to compute (0 = all, default).}

\item{k}{Number of local SVDs per incremental level (default 2).}

\item{q}{Number of incremental levels (default 1).}

\item{method}{Computation method: \code{"auto"} (default), \code{"blocks"},
or \code{"full"}.}

\item{rankthreshold}{Numeric in \code{[0, 0.1]}.  Rank approximation threshold.}

\item{svdgroup}{HDF5 group for intermediate SVD storage (default \code{"SVD/"}).}

\item{overwrite}{Logical.  Recompute even if PCA results exist (default \code{FALSE}).}

\item{threads}{Integer.  OpenMP threads (\code{-1} = auto-detect).}

\item{...}{Ignored (S3 compatibility).}
}
\value{
An object of class \code{c("HDF5PCA", "list")} with elements:
\describe{
\item{\code{sdev}}{Numeric vector.  Standard deviations of the PCs.}
\item{\code{rotation}}{HDF5Matrix.  Variable loadings (rotation matrix).}
\item{\code{x}}{HDF5Matrix or \code{NULL}.  Individual coordinates.}
\item{\code{center}}{Logical.  Whether columns were centered.}
\item{\code{scale}}{Logical.  Whether columns were scaled.}
\item{\code{cumvar}}{Numeric vector.  Cumulative variance explained (percent).}
\item{\code{lambda}}{Numeric vector.  Eigenvalues.}
\item{\code{var.cos2}}{HDF5Matrix.  Squared cosines for variables.}
\item{\code{ind.cos2}}{HDF5Matrix.  Squared cosines for individuals.}
\item{\code{ind.contrib}}{HDF5Matrix.  Contributions of individuals to PCs.}
\item{\code{file}}{Character.  Path to the HDF5 file with all results.}
}
}
\description{
Block-wise PCA entirely on disk, equivalent to \code{\link{prcomp}()}.
Implements the same interface as \code{stats::prcomp()} but operates on
data stored in an HDF5 file without loading it into RAM.
}
\examples{
\donttest{
tmp <- tempfile(fileext = ".h5")
X   <- hdf5_create_matrix(tmp, "data/M", data = matrix(rnorm(1000), 100, 10))
pca <- prcomp(X, center = TRUE, scale. = FALSE)
cat("Variance explained (PC1-3):", pca$cumvar[1:3], "\n")
dim(pca$rotation)   # 10 x nPC
dim(pca$x)          # 100 x nPC

# rank. takes precedence over ncomponents when both are supplied.
# NOTE: this reuses the same output location as the call above, so it
# must come after pca's results have already been read/used -- once
# overwrite = TRUE recreates the output datasets, any earlier
# HDF5Matrix handle pointing at that location (here, pca$rotation and
# pca$x) becomes invalid by design (see HDF5Matrix lifecycle, Section
# 5.3.3): the package proactively clears stale external pointers when
# overwriting to convert what would otherwise be a memory-unsafe crash
# into a clean R-level error.

pca5 <- prcomp(X, rank. = 5, ncomponents = 10, overwrite = TRUE)
dim(pca5$rotation)   # 10 x 5 -- rank. (5) was used, not ncomponents (10)

hdf5_close_all()
unlink(tmp)
}

}
