spca_path: Sparse PCA regularization paths

View source: R/spca_path.R

spca_pathR Documentation

Sparse PCA regularization paths

Description

Fit a sequence of sparsity penalties while reusing preprocessing and the initial matrix factorization or randomized sketch. Each fit provides the initial loading coefficients for the next penalty in the supplied order.

Usage

spca_path(
  X,
  k = NULL,
  alpha = c(1e-04, 0.001, 0.01),
  beta = 1e-04,
  center = TRUE,
  scale = FALSE,
  max_iter = 1000,
  tol = 1e-05,
  method = c("spca", "rspca"),
  o = 20,
  q = 2,
  verbose = TRUE,
  penalty = c("elasticnet", "l0"),
  B_init = NULL
)

## S3 method for class 'spca_path'
print(x, ...)

Arguments

X

A real numeric matrix, numeric data frame, or real Matrix object, with observations in rows and variables in columns. The deterministic method uses dense workspace; the randomized method preserves sparse input storage for products and implicit preprocessing. Missing rows are omitted with a warning. At least two complete rows are required; infinite and complex values are unsupported.

k

Positive integer number of components. NULL uses min(nrow(X), ncol(X)) after incomplete rows are omitted. Larger values are reduced to that limit. A component can have zero scores when the data are rank deficient or its loadings are all zero.

alpha

A nonempty numeric vector of finite nonnegative relative sparsity penalties. Fits follow this order without sorting. Increasing penalties from a weakly regularized fit is a convenient starting point.

beta

Finite nonnegative relative ridge penalty (default 1e-4), shared by all fits. Both penalties are scaled by the squared leading singular value of the processed input for method = "spca", or of the shared sketch for method = "rspca".

center

Logical; subtract column means before fitting (default TRUE). The fitted means are stored for prediction.

scale

Logical; divide each processed column by its scale factor (default FALSE). Factors are square roots of column sums of squares divided by n-1, after any centering. This is the sample standard deviation for centered data and a root-mean-square quantity otherwise. Factors below 1e-8 are replaced by one.

max_iter

Positive integer limit on optimization iterations. Reaching the limit does not establish convergence.

tol

Finite nonnegative tolerance for relative objective change. This controls an optimization stopping rule, not a reconstruction-error bound or a statistical accuracy guarantee. An objective increase larger than a roundoff allowance stops with a warning and does not count as convergence; see Details.

method

Fit with deterministic "spca" (the default) or randomized "rspca". All randomized fits share one sketch. o and q are used only by the randomized method.

o

Nonnegative integer oversampling parameter (default 20). The sketch width is min(k + o, nrow(X), ncol(X)) after incomplete rows are omitted. Additional columns can improve the approximation while increasing memory and computation.

q

Nonnegative integer number of power iterations (default 2). Each iteration requires additional products with the processed input and its transpose, with intermediate orthogonalization. Increasing q can help for a slowly decaying singular spectrum.

verbose

Logical, or the equivalent numeric zero/one; print optimization progress when enabled.

penalty

Sparsity penalty: "elasticnet" (the default) uses an entrywise absolute-value penalty and soft thresholding; "l0" counts nonzero coefficients and uses hard thresholding. With penalty = "l0" and beta > 0, the combination of cardinality and ridge penalties is also called ZeroNet.

B_init

Optional real finite p by k loading matrix for the first fit. Later fits initialize from the preceding fit's raw loadings.

x

An object returned by spca_path.

...

Additional arguments; currently ignored by the print method.

Details

A path saves the preprocessing and factorization work that separate calls would repeat. Warm starts may also reduce optimization iterations, but this is not guaranteed. The objective is nonconvex, so a path fit can differ from a fresh SVD initialization at the same penalty.

Penalties encourage sparse coefficients; they do not impose an exact count. Counts can jump or be nonmonotone. nonzero reports the number of active coefficients in each component, whereas selected_features counts variables active in at least one component. These answer different questions when components overlap. Inspect reconstruction quality and stability in addition to counts. Use spca_target to search penalties for an approximate desired number of variables without retaining every candidate fit.

Centering, scaling, the component count, the ridge penalty, and the chosen penalty type are shared across fits. For randomized paths, set.seed controls the single initial sketch. Each fit uses the result class, variance conventions, and convergence diagnostics of the selected method. Predict with an individual element of fits.

Value

A list of class "spca_path" with:

fits

A list of fitted spca or rspca objects in the supplied penalty order.

alpha

The user-supplied penalties before singular-value scaling.

nonzero

A matrix of counts with one row per penalty and one column per component, containing colSums(loadings != 0).

selected_features

The number of variables with a nonzero loading in at least one component, for each fit.

iterations

The number of stored objective values for each fit; this equals the completed iterations except for the single zero value used for zero-energy input.

method, penalty

The selected fitting method and sparsity penalty.

The print method displays a compact table of penalties, selected variable counts, iteration counts, and convergence indicators; per-component nonzero counts are available in nonzero.

Choosing a member of the path

A path is a collection of candidate models, not an automatic model selection procedure. Inspect the tradeoff between reconstruction, interpretable variables, and the purpose of the analysis. Compare validation rows in the shared training-centered/scaled coordinates; do not estimate a separate transformation for each validation batch. The example below reports validation reconstruction error beside the number of selected variables without claiming a universally best penalty.

Penalized objectives at different alpha values are different criteria, so the smallest recorded objective does not by itself select the best path member. A small number of active coefficients is not sufficient either: an all-zero loading matrix is sparse but uninformative. nonzero counts active coefficients per component, while selected_features counts the union of variables used anywhere. For example, two components with three coefficients each can together use only four variables if their supports overlap.

Warm starts follow the supplied sequence, even if it decreases or repeats penalties. They can lead to a different fit than restarting from the default singular vectors. If the path settles on an implausible representation, compare a shortlisted penalty with an independent fresh fit using the same settings. When comparing component patterns across fits, account for possible sign changes, reordering, and tied subspaces rather than relying on signed elementwise equality.

Computation and storage

The fits share preprocessing and one factorization or randomized sketch. Their effective penalties use the same spectral scale, which makes the supplied alpha sequence easy to interpret. The function still returns a complete fit for every member, including an n by k dense score matrix and two p by k factors. Long paths can therefore use substantial output memory even when input storage is sparse. A concise initial grid followed by closer investigation of useful values is often more informative than retaining a very long grid.

See Also

spca, rspca, spca_target, predict.spca.

Examples

training <- seq_len(nrow(iris)) %% 5 != 0
path <- spca_path(iris[training, 1:4], k = 2,
                  alpha = c(0.001, 0.01, 0.1, 0.3),
                  scale = TRUE, verbose = FALSE)
print(path)
# A strong penalty can leave a requested component with zero loadings.
path$nonzero

# All candidates use the same transformation estimated on training rows.
newX <- as.matrix(iris[!training, 1:4])
first <- path$fits[[1]]
processed <- scale(newX, center = first$center, scale = first$scale)
error <- vapply(path$fits, function(fit) {
  reconstructed <- tcrossprod(predict(fit, newX), fit$transform)
  sqrt(mean((processed - reconstructed)^2))
}, numeric(1))
data.frame(alpha = path$alpha, variables = path$selected_features,
           validation_RMSE = error)
predict(path$fits[[2]], newX[1:3, , drop = FALSE])

# A sparse-input path shares one smaller random sketch.
X <- Matrix::bdiag(outer(1:12, 1:8), outer(1:12, 8:1),
                   outer(1:12, 1:8))
set.seed(42)
randomized <- spca_path(X, k = 3, alpha = c(0.001, 0.01),
                        method = "rspca", o = 3, q = 2,
                        scale = TRUE, verbose = FALSE)
randomized$nonzero

sparsepca documentation built on Nov. 6, 2026, 5:06 p.m.