genpca

An R package for Generalized Principal Component Analysis (GPCA) and related matrix decompositions when data is observed in non-Euclidean inner-product spaces.

What is Generalized PCA?

Standard PCA assumes all observations and variables are equally important and that Euclidean distance is the appropriate similarity measure. However, many real-world datasets violate these assumptions:

Weighted observations: Survey data where rows represent different population sizes
Variable precision: Measurements with different accuracies or importance
Correlated features: Spatial/temporal data with known dependency structures
Domain-specific geometry: Functional data, shape analysis, or other specialized metrics

GPCA extends standard PCA by incorporating row and column metrics (M and A) that encode prior knowledge about data structure, following the framework of Allen, Grosenick & Taylor (2014). The package also implements generalized PLS methods building on ideas from Beaton et al. (2016).

Key Features

Core Functionality

Generalized PCA (genpca): Decomposition with row metric M and column metric A
Covariance-based GPCA (genpca_cov): Direct analysis of pre-computed covariance matrices
Multiple computational backends:
- eigen: Direct eigendecomposition for small-to-medium problems
- spectra: Iterative partial SVD of the metric-whitened data (via eigencore) for large problems
- randomized: Block-sketch approximation for wide low-rank settings
- deflation: Sequential extraction for memory-constrained scenarios

Advanced Methods

Generalized PLS/PLS-SVD (genpls/genplsc): Two-block analysis with metrics
Operator-level computations (gplssvd_op): Efficient PLS without materializing whitened matrices
Constraint handling: Strict, scale-relative validation of metric matrices (symmetry and positive semi-definiteness); repairs are explicit and reported (repair_metric(), constraints_remedy)

Sparse functional PCA (sfpca): Rank-1 components with sparsity and spatial smoothness penalties, e.g. sfpca(X, K = 2, spat_cds = coords). See ?sfpca.
Regularized PLS (rpls): Single-metric penalized PLS (Allen et al. 2013) with "l1" or "ridge" penalties, e.g. rpls(X, Y, K = 3, lambda = 0.1, penalty = "l1"). See ?rpls.
Matrix-normal PCA (mnpca_mrl): Low-rank factorization with sparse row/column precision matrices under matrix-normal noise, e.g. mnpca_mrl(Y, ncomp = 3, lambda_row = 0.05, lambda_col = 0.05). See ?mnpca_mrl.
Metric learning (gpca_mle): Experimental alternation of GPCA with maximum-likelihood estimation of the row/column metrics themselves, e.g. gpca_mle(X, ncomp = 2). See ?gpca_mle.

Integration

Full compatibility with the multivarious package ecosystem
Unified interface for preprocessing, projection, reconstruction, and transfer learning
Support for sparse matrices via the Matrix package

Backend Selection Guide

The default backend is method = "eigen". "auto" is opt-in: pass it explicitly to let a heuristic pick among "eigen", "spectra", and "randomized" based on problem shape and constraint structure.

Method	Best for	Pros	Cons
`eigen`	Small/medium problems, exact reference runs	Most stable reference behavior	Builds larger intermediate matrices; for very large sparse constraints may rely on truncated eigensolve (`maxeig`) and become slower/approximate
`spectra`	Large problems with few components	Iterative partial SVD of the whitened operator (eigencore); lower memory	Both metrics are factored once (Cholesky or sparse Cholesky); a large dense general metric costs one factorization
`randomized`	Wide (`p >> n`), sparse-metric, low-rank workloads	Often fastest in wide settings; block GEMM/SpMM path	Approximate by design; tune `oversample`, `n_power`, `n_polish`
`deflation`	Few components with limited memory	Low memory, component-by-component extraction	Can converge slowly; C++ path currently expects sparse metrics
`auto`	Default production usage	Chooses among `eigen`/`spectra`/`randomized` heuristically	Heuristics may not be optimal for every hardware/data regime

Installation

# install.packages("devtools")
devtools::install_github("bbuchsbaum/genpca")

You’ll also want these runtime dependencies installed:

install.packages(c("Matrix", "eigencore", "multivarious"))
# Optional for some utilities / tests
install.packages(c("irlba", "knitr", "rmarkdown"))

Quick Start

Basic Usage

library(genpca)
set.seed(1)
X <- matrix(rnorm(200 * 50), 200, 50)

# Standard PCA (identity metrics by default)
fit <- genpca(X, ncomp = 5, preproc = multivarious::center())
fit$sdev                             # generalized singular values;
                                      # with identity metrics this is
                                      # prcomp(X)$sdev * sqrt(nrow(X) - 1)
head(multivarious::scores(fit))      # scores (n × k)
head(multivarious::components(fit))  # loadings (p × k)

Weighted GPCA

# Example: Survey data with population weights
library(Matrix)
pop_weights <- runif(nrow(X), 0.5, 1.5)  # population sizes
M <- Diagonal(nrow(X), x = pop_weights)  # row metric

# Variable importance weights  
var_importance <- c(rep(2, 10), rep(1, 30), rep(0.5, 10))
A <- Diagonal(ncol(X), x = var_importance)  # column metric

fit_weighted <- genpca(X, M = M, A = A, ncomp = 5, 
                      preproc = multivarious::center())

Covariance-based GPCA

# When you have pre-computed covariance C = X'MX. fit_weighted above used
# preproc = multivarious::center(), so C must be built from centered X for
# the two fits to agree exactly.
Xc <- scale(X, center = TRUE, scale = FALSE)
C  <- crossprod(Xc, M %*% Xc)
fit_cov <- genpca_cov(C, R = A, ncomp = 5, method = "gmd")
# Mathematically equivalent to fit_weighted above
all.equal(fit_weighted$sdev, fit_cov$d, tolerance = 1e-8)

Generalized PLS

# Two-block analysis with canonical PLS
Y <- matrix(rnorm(200 * 20), 200, 20)
pls <- genpls(X, Y, ncomp = 3, 
              preproc_x = multivarious::center(), 
              preproc_y = multivarious::center())
pls$d                    # singular values of the whitened cross-product
                          # Xe'Ye (covariance scale, NOT canonical correlations)
dim(pls$vx); dim(pls$vy) # X/Y weight matrices

# To get canonical-correlation-like quantities, correlate the latent
# variable pairs directly:
diag(cor(pls$lx, pls$ly))

Understanding Metrics in GPCA

The metrics M and A define inner products and distances in the observation and variable spaces:

Row Metric M (n × n)

Defines relationships between observations
Inner product: ||x||_M^2 = x^T M x
Distance: d_M(x,y)^2 = (x−y)^T M (x−y)
Common choices:
- Identity: Standard equal weighting
- Diagonal: Population/sample weights
- Precision matrix: Account for observation correlations
- Kernel matrices: Encode similarity structures

Column Metric A (p × p)

Defines relationships between variables
Inner product: ||v||_A^2 = v^T A v
Distance: d_A(v,w)^2 = (v−w)^T A (v−w)
Common choices:
- Identity: Standard equal importance
- Diagonal: Variable weights/importance
- Covariance/precision: Variable dependencies
- Graph Laplacian: Spatial/temporal smoothness

When M = I and A = I, GPCA reduces to standard PCA.

Documentation

Vignettes
- Getting Started with genpca
- GPCA Metrics: Building M and A
- Modelling Structured Noise
- GPCA at Scale and Special Cases
- Generalized PLS-SVD: Explicit Whitening Reference

Build locally:

devtools::build_vignettes()
browseVignettes("genpca")

Testing and guarantees

Eigen vs spectra (eigencore): unit tests assert tight agreement on modest problems (sdev within 1e‑6, scores within 1e‑5 up to sign).
Deflation vs Eigen: additional tests (n≈60, p≈40, k=8) assert:
- sdev within 1e‑4,
- subspace agreement via principal angles,
- scores/components close after Procrustes alignment (≈ 1e‑3 relative).

Run tests locally:

library(testthat)
library(pkgload)
pkgload::load_all()
testthat::test_dir("tests/testthat")

References

The methods in this package are based on:

Allen, G. I., Grosenick, L., & Taylor, J. (2014). A generalized least-square matrix decomposition. Journal of the American Statistical Association, 109(505), 145-159. doi:10.1080/01621459.2013.852978
Beaton, D., ADNI, et al. (2016). Generalized partial least squares: A framework for simultaneously capturing common and individual variation. NeuroImage, 141, 346-363. doi:10.1016/j.neuroimage.2016.07.034

For additional theoretical background on generalized decompositions, see:

Beaton, D. (2020). Generalized eigen, singular value, and partial least squares decompositions: The GSVD package. arXiv preprint arXiv:2010.14734.

License

MIT (see LICENSE).

Contributing

Issues and PRs welcome. Please open a ticket with a minimal example, your R session info, and (if relevant) a pointer to the metric matrices that reproduce the behavior.

Albers theme

This package uses the albersdown theme. Existing vignette theme hooks are replaced so albers.css and local albers.js render consistently on CRAN and GitHub Pages. The defaults are configured via params$family and params$preset (family = ‘red’, preset = ‘interaction’). The pkgdown site uses template: { package: albersdown } together with generated pkgdown/extra.css and pkgdown/extra.js so the theme is linked and activated on site pages.