spca_target: Sparse PCA with an approximate number of selected variables

View source: R/spca_target.R

spca_targetR Documentation

Sparse PCA with an approximate number of selected variables

Description

Search sparsity penalties for a fitted representation using approximately a requested number of variables. The search reuses preprocessing and one deterministic factorization or randomized sketch, then returns the closest converged candidate and a record of every evaluated penalty.

Usage

spca_target(
  X,
  k = NULL,
  n_features,
  alpha = NULL,
  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,
  max_evals = 30L,
  count_tol = 0L
)

## S3 method for class 'spca_target'
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.

n_features

Integer desired number of input variables, between zero and ncol(X). A variable is selected if its loading is nonzero in at least one component. This counts the union across components, not the number of coefficients in each component.

alpha

Optional nonempty numeric vector of finite nonnegative relative penalties for the initial search. Values are evaluated in the supplied order, with warm starts. NULL uses an increasing grid containing zero and logarithmically spaced positive penalties up to one, with at most 13 initial values. A supplied grid must contain no more than max_evals values. Refinement stays within the initial grid's range.

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 candidate. NULL uses the shared factorization's leading right singular vectors. Subsequent initial-grid candidates use the preceding candidate's loadings; refinement uses the best converged candidate so far, or the closest candidate if none has converged.

max_evals

Positive integer maximum number of candidate fits, including the initial grid and refinement. The default is 30. Each candidate has its own max_iter optimization limit.

count_tol

Nonnegative integer acceptable absolute difference between the requested and achieved variable counts. The default zero searches for an exact match, while still returning the closest converged candidate if no exact match is found. This controls the search stopping rule; tol controls each fit's objective stopping rule.

x

An object returned by spca_target.

...

Additional arguments; currently ignored by the print method.

Details

The number of score coordinates k and the number of measured variables n_features answer different questions. For example, two components can each use three measurements while together using only four distinct measurements. This function searches the total number of variables needed to calculate all requested scores.

Each candidate solves the unchanged penalized objective of spca or rspca. The procedure evaluates an initial penalty grid, then prioritizes intervals whose observed endpoint counts lie on either side of the request, followed by intervals near the closest counts. It stops when a converged candidate meets count_tol, the evaluation budget is exhausted, or there are no further penalties to evaluate. It does not assume that the count is monotone in alpha. Counts can jump over the requested value, and the nonconvex optimization can reach different solutions under different warm starts. An exact count need not be attainable within the explored candidates.

Only candidates with converged = TRUE are eligible for selection. The selected candidate minimizes the absolute count difference, with ties resolved by fewer selected variables and then earlier evaluation. Its penalized objective is not compared with objectives at other penalty strengths. A count within count_tol ends the search immediately; the procedure does not compare all representations having that count. If no candidate converges, the function warns and returns fit = NULL, with the attempted fits still recorded in search. A larger max_iter or revised fit settings may be needed in that case.

The result reports both the requested and achieved counts. A nonzero mismatch is an ordinary search outcome and leaves target_met false when it exceeds count_tol. Increasing max_evals permits more refinement, and supplying alpha changes the range and starting sequence explored. Neither change guarantees an exact count or a globally optimal subset. Coefficients are the fitted values; the function does not trim or pad the final loading matrix.

Value

A list of class "spca_target" with:

fit

The selected spca or rspca object, or NULL if none of the evaluated candidates converged.

n_features

The requested number of variables.

selected_features

The achieved number of selected variables, or NA when no candidate was eligible.

alpha

The selected relative penalty before spectral scaling, or NA. In contrast, fit$alpha contains the effective coefficient used in the objective.

target_met

Whether an eligible candidate's count is within count_tol of n_features.

count_tol

The allowed absolute difference in variable count.

index

Row of search identifying the selected candidate, or NA when none was eligible.

search

A data frame in evaluation order with columns alpha, selected_features, difference, iterations, converged, and warm_start. difference is the achieved count minus the requested count; negative values mean that fewer variables were selected. warm_start is the index of the earlier candidate supplying initial loadings, or zero for the caller-supplied/default start.

nonzero

A matrix of nonzero counts, with one row per evaluated candidate and one column per component.

method, penalty

The chosen fitting method and sparsity penalty.

stop_reason

One of "target_met", "max_evals", "no_refinement", or "no_converged_fit".

The print method reports the requested and achieved counts, selected penalty, target status, and number of evaluated candidates.

Computation and sparse input

All candidates share the training means, scales, component count, ridge penalty, penalty type, and spectral penalty scale. The randomized method uses one sketch, so set.seed controls the shared approximation. With method = "rspca", sparse Matrix input retains the implicit centering and scaling behavior described in rspca. The deterministic method uses dense workspace.

The search stores candidate counts and optimization summaries, with full-data scores constructed only for the selected fit. Use spca_path when every complete candidate fit is needed. The returned fit has the usual class, prediction methods, variance conventions, and loading scale of the selected method.

Interpreting the selected representation

Reaching a desired count is a computational convenience. Inspect the variables and reconstruction quality, and assess stability or validation performance when these matter to the analysis. The count does not establish that the selected measurements are unique, necessary, or causally important. A component can have zero loadings, and fewer than k selected variables cannot produce k independent scores. Zero processed data have zero selected variables regardless of the requested count.

See Also

spca_path, spca, rspca, predict.spca.

Examples

X <- as.matrix(iris[, 1:4])
target <- spca_target(X, k = 2, n_features = 3,
                      beta = 0.001, scale = TRUE,
                      tol = 1e-8, max_iter = 3000, verbose = FALSE)
print(target)
target$search
if (!is.null(target$fit)) {
  colnames(X)[rowSums(target$fit$loadings != 0) > 0]
  predict(target$fit, X[1:3, , drop = FALSE])
}

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