| spca_target | R Documentation |
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.
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, ...)
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. |
n_features |
Integer desired number of input variables, between zero
and |
alpha |
Optional nonempty numeric vector of finite nonnegative
relative penalties for the initial search. Values are evaluated in the
supplied order, with warm starts. |
beta |
Finite nonnegative relative ridge penalty (default
|
center |
Logical; subtract column means before fitting (default
|
scale |
Logical; divide each processed column by its scale factor
(default |
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 |
o |
Nonnegative integer oversampling parameter (default |
q |
Nonnegative integer number of power iterations (default
|
verbose |
Logical, or the equivalent numeric zero/one; print optimization progress when enabled. |
penalty |
Sparsity penalty: |
B_init |
Optional real finite |
max_evals |
Positive integer maximum number of candidate fits,
including the initial grid and refinement. The default is 30. Each
candidate has its own |
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; |
x |
An object returned by |
... |
Additional arguments; currently ignored by the print method. |
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.
A list of class "spca_target" with:
The selected spca or rspca object, or
NULL if none of the evaluated candidates converged.
The requested number of variables.
The achieved number of selected variables,
or NA when no candidate was eligible.
The selected relative penalty before spectral scaling,
or NA. In contrast, fit$alpha contains the effective
coefficient used in the objective.
Whether an eligible candidate's count is within
count_tol of n_features.
The allowed absolute difference in variable count.
Row of search identifying the selected candidate,
or NA when none was eligible.
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.
A matrix of nonzero counts, with one row per evaluated candidate and one column per component.
The chosen fitting method and sparsity penalty.
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.
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.
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.
spca_path, spca,
rspca, predict.spca.
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])
}
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.