Backend-native truncated PCA

pca() computes principal component scores with a backend-native truncated decomposition. CPU uses a package-native float32 blocked randomized SVD (rSVD). Metal uses a package-native float32 block-subspace rSVD whose large matrix products are executed with Metal Performance Shaders. CUDA selects between package-native float32 rSVD and, when enabled, RAPIDS RAFT TSVD from the matrix shape, requested rank, and estimated arithmetic cost. Wide, low-rank problems favor rSVD; smaller, narrower, or less-truncated problems favor TSVD. Without RAFT, CUDA uses native rSVD. CUDA requests fail explicitly when CUDA is unavailable; they never fall back to CPU PCA.

Usage

pca(
  x,
  ncomp = 2L,
  xtest = NULL,
  center = TRUE,
  scale = FALSE,
  backend = NULL,
  n.cores = NULL,
  seed = 4L,
  tsne_init = FALSE,
  massive = "off",
  output = NULL,
  chunk_rows = NULL,
  memory_limit = "512MB",
  checkpoint = FALSE,
  resume = FALSE,
  devices = NULL
)

Arguments

x

Numeric matrix/data frame or float::float32 matrix with observations in rows.

ncomp

Number of principal components.

xtest

Optional test/query matrix with the same columns as x. Projected coordinates are returned in scores_test.

center

If TRUE, mean-center columns before decomposition.

scale

If TRUE, scale centered columns to unit sample standard deviation before decomposition.

backend

PCA backend: "cpu", "cuda", or "metal".

n.cores

Positive integer CPU worker limit. Small stages use fewer workers automatically. On Linux, BLAS and OpenMP are limited to one thread while native workers are active to prevent nested parallelism. On macOS, Accelerate may use the requested limit. In experimental out-of-core CUDA PCA it controls the streamed CPU mean pass. It is otherwise ignored by Metal and CUDA.

seed

Random seed for backends that use a Gaussian subspace sketch, including experimental wide streamed CPU or CUDA PCA. The RAFT covariance-eigensolver route records but does not consume this value.

tsne_init

If TRUE, add tsne_init to the returned PCA object. This matrix is centered and rescaled so its largest component standard deviation is 1e-4, ready to pass as Y_init to tsne() or tsne_knn().

massive

"off" (default) keeps the existing in-memory route. "auto" estimates memory and selects the in-memory route when safe, otherwise streamed PCA. "out_of_core" explicitly activates covariance PCA for a massive_matrix() source with at most 1024 columns on CPU or 2048 on CUDA. Wider matrices use randomized streamed PCA. Wide CUDA streams the mean and scale passes on CPU, runs its sketch and projection on CUDA, and reports stage backends. Metal streaming is unavailable and fails explicitly.

output

Required .f32 score-file path in out-of-core mode, including when auto mode selects that route.

chunk_rows

Maximum rows read per block in out-of-core mode.

memory_limit

Conservative RAM budget for out-of-core buffers and any resident R-matrix input, for example "512MB" or "16GB". This does not limit R itself or linked-library memory.

checkpoint

Save the experimental out-of-core PCA model and completed score batches beside output for recovery.

resume

Continue from a matching PCA checkpoint and partial score file. Available when out-of-core processing is selected.

devices

Optional distinct CUDA device IDs for experimental file-backed PCA score projection. The decomposition runs on the first selected device; projection rows are sharded across devices. Optional checkpointing saves the decomposition and completed shard blocks; resume requires the same input, settings, and device list.

Value

A fastEmbedR_pca list with scores, loadings, singular_values, centering/scaling vectors, backend metadata, and decomposition metadata. When tsne_init = TRUE, the list also contains tsne_init; when xtest is supplied, it also contains scores_test. Metal and CUDA preserve float::float32 scores, loadings, initialization, and compatible test projections when the input is float32. CPU results also record the worker and BLAS limits.

Details

CPU matrix products and factorizations use the BLAS/LAPACK linked to R. Set n.cores to control their CPU core limit. The requested value is applied temporarily through standard BLAS/OpenMP environment variables and, when installed, RhpcBLASctl; the prior process settings are restored after the call. A single-threaded BLAS can still report one effective thread. With float::float32 input, native Metal and CUDA preprocessing and the returned scores/loadings also remain float32. The API intentionally has no decomposition method menu and does not call Python. Explicit unavailable GPU requests fail instead of being reported as GPU work.

Examples

fit <- pca(
    as.matrix(iris[, 1:4]),
    ncomp = 2,
    n.cores = 2,
    seed = 1,
    tsne_init = TRUE
)
plot(fit$scores, pch = 21, bg = iris$Species)

plot(fit$tsne_init, pch = 21, bg = iris$Species)