Package {spca}

Least Squares Sparse Principal Components Analysis

Description

The package provides functions to compute LS-SPCA solutions, in which sparsity is imposed on Pearson PCA's least-squares reconstruction objective.

Details

LS-SPCA differs from SPCA methods that compute sparse PCs by maximizing variance. Details are provided in the references below and in the extended vignette.

This release accompanies the related article and supports reproduction of the results reported therein.

Computation relies on efficient C++ routines and includes multiple options for variable selection and sparse weight estimation.

Fitting functions

• spca() Computes LS-SPCA solutions from a data or covariance/correlation matrix. It returns a spca_object of class spca.

• pca() Computes PCA solutions from a data or covariance/correlation matrix. It returns a spca_object inheriting from classes spca_pca and spca.

Methods

• print(), summary(), and plot() inspect and display spca objects.

• change_sign() changes the signs of selected components and their related object elements.

• show_weights() prints or returns the nonzero weights or contributions for selected components.

• aggregate_by_group() aggregates weights or contributions according to a grouping vector.

• screeplot_spca() and qqplot_spca() provide diagnostic plots for objects returned by pca().

Utilities

• is.spca() Verifies whether an object is an spca object.

• compare_spca() Compares two or more LS-SPCA solutions numerically and visually.

• new_spca() Creates an spca object from a set of weights.

The former interfaces change_weights_sign_spca(), change_loadings_sign_spca(), spca_screeplot(), and wachter_qqplot() are retained for backward compatibility and issue deprecation warnings. Objects created by previous package versions with loadings and loadings_list elements remain supported.

Author(s)

Maintainer: Giovanni Maria Merola merolagio@gmail.com

References

Merola, G. M. (2015). Least Squares Sparse Principal Component Analysis: a Backward Elimination approach to attain large weights. Australia & New Zealand Journal of Statistics, 57, 391–429. doi:10.1111/anzs.12128

Merola, G. M. and Chen, G. (2019). Projection sparse principal component analysis: An efficient least squares method. Journal of Multivariate Analysis, 173, 366–382. doi:10.1016/j.jmva.2019.04.001

See Also

Useful links:

• https://github.com/merolagio/spca

• Report bugs at https://github.com/merolagio/spca/issues

Aggregate SPCA Weights or Contributions by Group

Description

Aggregate component weights or contributions according to a grouping variable.

Usage

aggregate_by_group(spca_obj, ...)

## S3 method for class 'spca'
aggregate_by_group(
  spca_obj,
  groups,
  only_nonzero = TRUE,
  contributions = TRUE,
  digits = ifelse(contributions, 1, 3),
  print_table = TRUE,
  return_table = FALSE,
  ...
)

Arguments

Value

The aggregated matrix, visibly when return_table = TRUE and invisibly otherwise.

See Also

Other spca: change_loadings_sign_spca(), change_sign(), change_weights_sign_spca(), compare_spca(), is.spca(), new_spca(), plot.spca(), print.spca(), show_correlations(), show_weights(), spca(), spca_object, summary.spca()

Change Component Signs in an SPCA Object (Deprecated Alias)

Description

change_loadings_sign_spca() is retained for backward compatibility. Use change_sign() in new code.

Usage

change_loadings_sign_spca(spca_obj, index_to_change)

Arguments

Value

The modified spca_obj.

See Also

Other spca: aggregate_by_group(), change_sign(), change_weights_sign_spca(), compare_spca(), is.spca(), new_spca(), plot.spca(), print.spca(), show_correlations(), show_weights(), spca(), spca_object, summary.spca()

Change Component Signs

Description

Change the signs of selected components in a fitted object.

Usage

change_sign(spca_obj, ...)

## S3 method for class 'spca'
change_sign(spca_obj, index_to_change, ...)

Arguments

Value

The modified object.

The modified spca object.

See Also

Other spca: aggregate_by_group(), change_loadings_sign_spca(), change_weights_sign_spca(), compare_spca(), is.spca(), new_spca(), plot.spca(), print.spca(), show_correlations(), show_weights(), spca(), spca_object, summary.spca()

Change Component Signs in an SPCA Object (Deprecated Alias)

Description

change_weights_sign_spca() is retained for backward compatibility. Use change_sign() in new code.

Usage

change_weights_sign_spca(spca_obj, index_to_change)

Arguments

Value

The modified spca_obj.

See Also

Other spca: aggregate_by_group(), change_loadings_sign_spca(), change_sign(), compare_spca(), is.spca(), new_spca(), plot.spca(), print.spca(), show_correlations(), show_weights(), spca(), spca_object, summary.spca()

Compare Two or More spca Solutions

Description

Plots weights and print summary statistics for two or more spca objects side by side. For the meaning of each summary statistic, see summary.spca. Tables and plots can optionally be returned.

Usage

compare_spca(
  obj_list,
  n_comps = NULL,
  contributions = TRUE,
  only_nonzero = TRUE,
  variable_groups = NULL,
  plot_weights = TRUE,
  plot_type = c("bars", "points"),
  methods_names = NULL,
  x_axis_var_names = FALSE,
  col_grouplines = "red",
  color_scale = c("ggplot", "cbb", "printsafe", "bw"),
  col_short_names = TRUE,
  print_tables = TRUE,
  print_weights = FALSE,
  show_plot = TRUE,
  return_tables = FALSE,
  return_plot = FALSE
)

Arguments

Value

Invisibly returns NULL by default. If return_tables = TRUE, returns a list containing the comparison matrix and summary matrix. If return_plot = TRUE, the returned object also includes the weights or contributions plot.

See Also

Other spca: aggregate_by_group(), change_loadings_sign_spca(), change_sign(), change_weights_sign_spca(), is.spca(), new_spca(), plot.spca(), print.spca(), show_correlations(), show_weights(), spca(), spca_object, summary.spca()

Examples

data(holzinger)
ho_uspca = spca(holzinger, n_comps = 4, method = "u")
ho_cspca = spca(holzinger, n_comps = 4, method = "c")
compare_spca(list(ho_uspca, ho_cspca))

Holzinger–Swineford Student Ability Data

Description

This dataset is based on the classic Holzinger and Swineford (1939) Student Ability dataset.

We use the version distributed with the psychTools package. For comparability with previous analyses, we select 12 items and only students from the Grant–White School (see also Ferrara, Martella, and Vichi, 2019).

Usage

holzinger

Format

holzinger

A numeric data frame with 145 rows and 12 variables. The variables are:

visual

Visual perception test (SPL).

cubes

Cubes test (SPL).

flags

Lozenges test (SPL).

paragraph

Paragraph comprehension test (VBL).

sentence

Sentence completion test (VBL).

wordm

Word meaning test (VBL).

addition

Addition test (SPD).

counting

Counting groups of dots test (SPD).

straight

Straight and curved capitals test (SPD).

deduct

Deduction test (MTH).

numeric

Numerical puzzles test (MTH).

series

Series completion test (MTH).

Details

The 12 items correspond to four ability scales: spatial (SPL), verbal (VBL), speed (SPD), and mathematical (MTH). The data provided with this package are scaled to mean zero and unit variance. The scales are available as a factor called holzinger_scales

References

Holzinger, K. J., and Swineford, F. (1939). A study in factor analysis: The stability of a bi-factor solution. Supplementary Educational Monographs, No. 48.

Ferrara, C., Martella, F., and Vichi, M. (2019). Probabilistic disjoint principal component analysis. Multivariate Behavioral Research, 54(1), 47–61.

Holzinger–Swineford Student Ability Scales

Description

Holzinger–Swineford Student Ability Scales

Usage

holzinger_scales

Format

holzinger_scales

A factor listing the 4 scales: SPL, VBL, SPD and MTH, for each variable.

Test for SPCA Objects

Description

Check whether an object has class spca and contains the core elements required by the package.

Usage

is.spca(x)

Arguments

Details

The function checks for class spca and for the presence of the core elements used by the package, including weights, contributions, explained-variance summaries, component counts, cardinalities, weight lists, and active indices. It performs a lightweight structural check; use validate_spca() for a more detailed internal validation.

Value

A logical value. Returns TRUE if x has class spca and contains the required core elements, and FALSE otherwise.

See Also

Other spca: aggregate_by_group(), change_loadings_sign_spca(), change_sign(), change_weights_sign_spca(), compare_spca(), new_spca(), plot.spca(), print.spca(), show_correlations(), show_weights(), spca(), spca_object, summary.spca()

Examples

data(holzinger)
ho_cspca = spca(holzinger, n_comps = 2)
is.spca(ho_cspca)

Construct an SPCA Object from a Set of Weights

Description

Build an object of class spca from a weights matrix and either a covariance or correlation matrix, a data matrix, or both.

Usage

new_spca(A, S = NULL, X = NULL, method_name = NULL)

Arguments

Value

An spca object.

See Also

Other spca: aggregate_by_group(), change_loadings_sign_spca(), change_sign(), change_weights_sign_spca(), compare_spca(), is.spca(), plot.spca(), print.spca(), show_correlations(), show_weights(), spca(), spca_object, summary.spca()

Examples

set.seed(1)
A = round(matrix(runif(24, -1, 1), 12))
A[abs(A) < 0.4] = 0 #no need to scale to unit norm
data(holzinger)
spca_new = new_spca(A, X = holzinger)
is.spca(spca_new)
summary(spca_new)

Computes Principal Components

Description

Compute a principal component analysis (PCA) and return the result as an spca object, so that it can be used with spca methods.

Usage

pca(
  M,
  n_comps = NULL,
  center_data = FALSE,
  scale_data = FALSE,
  fat_matrix = NULL,
  screeplot = FALSE,
  qq_plot = TRUE,
  nrow_data = NULL,
  neigen_toplot = NULL,
  cor = TRUE,
  common_var = 1,
  pm = FALSE,
  eps_pm = 1e-04,
  maxiter_pm = 1000
)

Arguments

Details

n_comps controls how many components are retained in the returned object. The tall backend computes PCA from the covariance or correlation matrix. The fat backend computes PCA in row space and converts the retained eigenvectors back to variable weights.

Value

An spca_object with an additional eigenvalues vector containing the eigenvalues up to the rank used by the selected backend and n_obs stores the number of observations, if a data matrix is passed, or NULL.

See Also

Other pca: qqplot_spca(), screeplot_spca(), spca_screeplot(), wachter_qqplot()

Examples

data(holzinger)
ho_pca = pca(holzinger, n_comps = 4, screeplot = TRUE,
             nrow_data = 144, qq_plot = TRUE)
summary(ho_pca)

Plot an spca Object

Description

Plot the sparse weights, or the corresponding percentage contributions, from an spca object. The plot can be shown as a bar plot, circular bar plot, or heatmap.

Usage

## S3 method for class 'spca'
plot(
  x,
  n_plot = NULL,
  plot_type = c("bars", "circular", "heatmap"),
  contributions = TRUE,
  only_nonzero = TRUE,
  pc_weights = NULL,
  variable_groups = NULL,
  plot_title = NULL,
  return_plot = FALSE,
  show_plot = TRUE,
  controls = list(color_scale = c("ggplot", "cbb", "printsafe", "bw"), variable_names =
    "none", legend_position = c("none", "bottom", "right", "top", "left"), grid_type =
    c("horizontal", "full", "none"), facet_labels = NULL, legend_title = NULL, x_axis_lab
    = "variables", adjust_labels_circ = NULL, flip_heatmap = FALSE, heatmap_color_range =
    c("values", "unit")),
  ...
)

Arguments

Details

If pc_weights is supplied, SPCA and PCA values are plotted side by side for comparison. Circular bar plots are not implemented for this comparison, so a standard bar plot is used instead. In this case all variables are plotted, regardless of only_nonzero.

For character arguments defined by a default vector of accepted values, the first element is the default and the first character of the supplied string is used for matching.

The entries in controls are:

• color_scale: a character vector (default first element "ggplot"). Accepted values are "ggplot", "cbb", "printsafe", and "bw". "cbb" is colorblind-friendly with black, "printsafe" is colorblind- and printer-friendly, "bw" uses gray tones, and "ggplot" uses the default ggplot2 scale.

• variable_names: a character vector or NULL (default "none"). If NULL, row names of the weight matrix are used, or V1, ..., Vp if row names are missing. If set to "none", variable names are not shown. If a character vector of length p is supplied, it is used as the variable names.

• legend_position: a character vector (default first element "none"). Accepted values are "none", "bottom", "right", "top", and "left".

• grid_type: a character vector (default first element "horizontal"). Accepted values are "horizontal", "full", and "none".

• facet_labels: a character vector or NULL (default NULL). Optional facet labels for components.

• legend_title: a character scalar or NULL (default NULL). Optional legend title.

• x_axis_lab: a character scalar (default "variables"). Label for the x axis.

• adjust_labels_circ: a numeric vector or NULL (default NULL). Optional angular adjustments for circular plot labels.

• flip_heatmap: a logical value (default FALSE). If TRUE, flip the heatmap axes.

• heatmap_color_range: a character vector (default first element "values"). Accepted values are "values" and "unit".

When variable groups are supplied, a legend is needed to identify the groups; if the legend is missing or suppressed, it is moved to the bottom. For circular plots, the legend is moved to the right unless it is suppressed.

Value

If return_plot = TRUE, returns the ggplot2 object. Otherwise, returns NULL invisibly.

References

The printsafe palette corresponds to OrRd from https://colorbrewer2.org/.

See Also

Other spca: aggregate_by_group(), change_loadings_sign_spca(), change_sign(), change_weights_sign_spca(), compare_spca(), is.spca(), new_spca(), print.spca(), show_correlations(), show_weights(), spca(), spca_object, summary.spca()

Examples

data(holzinger)
ho_cspca = spca(holzinger, n_comps = 4)
ho_plot = plot(ho_cspca, return_plot = TRUE)

# Change faceting and legend position.
ho_plot + ggplot2::facet_wrap(
  facets = ggplot2::vars(component),
  ncol = 4,
  nrow = 1
) + ggplot2::theme(legend.position = "right")

Print an spca Object

Description

Print sparse weights, or the corresponding percentage contributions, from an spca object. By default, variables with only zero entries are omitted, and cumulative explained variance is shown at the bottom of the table.

Usage

## S3 method for class 'spca'
print(
  x,
  cols = NULL,
  only_nonzero = TRUE,
  contributions = TRUE,
  digits = 3,
  thresh_card = 1e-07,
  return_table = FALSE,
  component_names = NULL,
  ...
)

Arguments

Value

If return_table = TRUE, returns the formatted character matrix. Otherwise, returns NULL invisibly.

See Also

Other spca: aggregate_by_group(), change_loadings_sign_spca(), change_sign(), change_weights_sign_spca(), compare_spca(), is.spca(), new_spca(), plot.spca(), show_correlations(), show_weights(), spca(), spca_object, summary.spca()

Examples

data(holzinger)
ho_cspca = spca(holzinger, n_comps = 4)
ho_cspca
print(ho_cspca, contributions = FALSE, digits = 4)

Wachter QQ Plot for PCA Eigenvalues

Description

Produce a QQ plot comparing the eigenvalues of a fitted PCA with Marchenko–Pastur (Wachter) theoretical quantiles.

Usage

qqplot_spca(
  pca_fit,
  n_vars = NULL,
  n_obs = NULL,
  gamma = NULL,
  cor = TRUE,
  common_var = 1,
  n_plot = NULL,
  n_fitline = NULL,
  addtitle = TRUE,
  show_plot = TRUE,
  return_plot = FALSE
)

## S3 method for class 'spca_pca'
qqplot_spca(
  pca_fit,
  n_vars = NULL,
  n_obs = NULL,
  gamma = NULL,
  cor = TRUE,
  common_var = 1,
  n_plot = NULL,
  n_fitline = NULL,
  addtitle = TRUE,
  show_plot = TRUE,
  return_plot = FALSE
)

## S3 method for class 'spca'
qqplot_spca(
  pca_fit,
  n_vars = NULL,
  n_obs = NULL,
  gamma = NULL,
  cor = TRUE,
  common_var = 1,
  n_plot = NULL,
  n_fitline = NULL,
  addtitle = TRUE,
  show_plot = TRUE,
  return_plot = FALSE
)

Arguments

Value

If return_plot = TRUE, a ggplot object; otherwise NULL invisibly.

See Also

Other pca: pca(), screeplot_spca(), spca_screeplot(), wachter_qqplot()

Plot PCA Eigenvalues in a Screeplot

Description

Plot the leading eigenvalues of a fitted PCA against component order.

Usage

screeplot_spca(
  pca_fit,
  n_plot = NULL,
  ylab = "eigenvalues",
  addtitle = TRUE,
  show_plot = TRUE,
  return_plot = FALSE
)

## S3 method for class 'spca_pca'
screeplot_spca(
  pca_fit,
  n_plot = NULL,
  ylab = "eigenvalues",
  addtitle = TRUE,
  show_plot = TRUE,
  return_plot = FALSE
)

## S3 method for class 'spca'
screeplot_spca(
  pca_fit,
  n_plot = NULL,
  ylab = "eigenvalues",
  addtitle = TRUE,
  show_plot = TRUE,
  return_plot = FALSE
)

Arguments

Value

If return_plot = TRUE, a ggplot object; otherwise NULL invisibly.

See Also

Other pca: pca(), qqplot_spca(), spca_screeplot(), wachter_qqplot()

Show Correlations from an SPCA Object

Description

Print and optionally return the mutual correlations among sparse principal components and their correlations with the corresponding principal components.

Usage

show_correlations(spca_obj, ...)

## S3 method for class 'spca'
show_correlations(
  spca_obj,
  type = "both",
  digits = 2,
  print_matrices = TRUE,
  return_matrices = FALSE,
  ...
)

Arguments

Value

If return_matrices = TRUE, a numeric matrix when one type of correlation is requested, or a named list of two numeric matrices when type = "both". Otherwise, returns NULL invisibly.

See Also

Other spca: aggregate_by_group(), change_loadings_sign_spca(), change_sign(), change_weights_sign_spca(), compare_spca(), is.spca(), new_spca(), plot.spca(), print.spca(), show_weights(), spca(), spca_object, summary.spca()

Examples

data(holzinger)
ho_cspca = spca(holzinger, n_comps = 3)
show_correlations(ho_cspca)
show_correlations(ho_cspca, type = "s", return_matrices = TRUE)

Show SPCA Weights or Contributions

Description

Show selected nonzero component weights or their unit-L1 contributions.

Usage

show_weights(spca_obj, ...)

## S3 method for class 'spca'
show_weights(
  spca_obj,
  cols = NULL,
  contribution = TRUE,
  print_list = TRUE,
  return_list = FALSE,
  ...
)

Arguments

Value

The selected weights or contributions when requested; otherwise NULL invisibly.

See Also

Other spca: aggregate_by_group(), change_loadings_sign_spca(), change_sign(), change_weights_sign_spca(), compare_spca(), is.spca(), new_spca(), plot.spca(), print.spca(), show_correlations(), spca(), spca_object, summary.spca()

Compute LS-SPCA Components

Description

Compute least squares sparse principal components (LS-SPCA) from a data matrix or from a covariance/correlation matrix.

Usage

spca(
  M,
  n_comps = NULL,
  alpha = 0.95,
  ncomp_by_cvexp = NULL,
  method = c("cspca", "uspca", "pspca"),
  var_selection = c("fwd", "bkw", "step"),
  objective = c("r2", "cvexp"),
  intensive = FALSE,
  fat_matrix = NULL,
  fixed_index_list = NULL,
  center_data = FALSE,
  scale_data = FALSE,
  pm_weights = FALSE,
  eps_pm_weights = 1e-04,
  maxiter_pm_weights = 1000,
  pm_varsel = FALSE,
  eps_pm_varsel = 1e-04,
  maxiter_pm_varsel = 500
)

Arguments

Details

Data matrices are routed to the tall or fat C++ backend. Square matrices are treated as covariance/correlation matrices and use the tall backend.

Variable selection is controlled by var_selection, objective, and intensive.

The fat backend currently supports regression-based forward variable selection only: var_selection = "f" and intensive = FALSE. Other combinations generate an error.

The returned object is documented in spca_object.

Value

An object of class spca.

See Also

Other spca: aggregate_by_group(), change_loadings_sign_spca(), change_sign(), change_weights_sign_spca(), compare_spca(), is.spca(), new_spca(), plot.spca(), print.spca(), show_correlations(), show_weights(), spca_object, summary.spca()

Examples

data(holzinger)
#default
ho_cspca = spca(holzinger, n_comps = 4)
#uncorrelated components and subsets determined using CVEXP as stopping rule
ho_uspca = spca(holzinger, n_comps = 4, method = "uspca", 
                objective = "cvexp")

Sparse Principal Component Analysis Object

Description

Objects of class spca are returned by the fitting functions spca(), pca(), and new_spca(). Objects returned by pca() also inherit from class spca_pca.

Components

An object of class spca is a list with the following elements:

weights

p \times r matrix of sparse weights.

contributions

p \times r matrix of weights scaled to unit L_1 norm within each sPC.

n_comps

Number of sPCs.

cardinality

Number of nonzero weights in each sPC.

vexp

Variance explained by each sPC.

vexp_pc

Variance explained by the corresponding PCs.

cvexp

Cumulative variance explained by the sPCs.

rvexp

Ratio of vexp to the variance explained by the corresponding PC.

rcvexp

Ratio of cvexp to the cumulative variance explained by the corresponding PCs.

cor_with_pc

Correlation between each sPC and the corresponding PC.

tot_var

Total variance of the data.

weights_list

List of nonzero weight vectors, one per sPC.

spc_cor

n_comps \times n_comps correlation matrix of the sPC scores.

indices

List of variable indices with nonzero weights, one per sPC.

scores

Optional matrix of sPC scores, returned only when a data matrix is supplied.

parameters

List of parameters used to compute an spca() fit.

call

Matched call used to compute an spca() fit.

eigenvalues

For pca() objects, the available PCA eigenvalues.

n_obs

For pca() objects, the number of observations when available.

method_name

For new_spca() objects, an optional method label.

For backward compatibility, methods also accept objects from earlier package versions containing loadings and loadings_list instead of weights and weights_list.

See Also

Other spca: aggregate_by_group(), change_loadings_sign_spca(), change_sign(), change_weights_sign_spca(), compare_spca(), is.spca(), new_spca(), plot.spca(), print.spca(), show_correlations(), show_weights(), spca(), summary.spca()

Plot Eigenvalues in a Scree Plot (Deprecated)

Description

spca_screeplot() is retained for backward compatibility. Use screeplot_spca() with objects returned by pca() in new code.

Usage

spca_screeplot(
  eigenvalues,
  n_plot = NULL,
  ylab = "eigenvalues",
  addtitle = TRUE,
  show_plot = TRUE,
  return_plot = FALSE
)

Arguments

Value

If return_plot = TRUE, a ggplot object; otherwise NULL invisibly.

See Also

Other pca: pca(), qqplot_spca(), screeplot_spca(), wachter_qqplot()

Summarize an spca Object

Description

Print and optionally return summary statistics for evaluating an spca object and comparing it with the corresponding PCA solution.

Usage

## S3 method for class 'spca'
summary(
  object,
  cols,
  contributions = TRUE,
  variance_metrics = c("both", "cumulative_relative", "relative", "none"),
  min_weight = FALSE,
  cor_with_pc = TRUE,
  return_table = FALSE,
  print_table = TRUE,
  thresh_card = 1e-08,
  ...
)

Arguments

Details

For each component, the following summaries can be computed:

Value

If return_table = TRUE, returns a numeric matrix with the selected summary statistics. Otherwise, returns NULL invisibly.

See Also

Examples in aggregate_by_group.

Other spca: aggregate_by_group(), change_loadings_sign_spca(), change_sign(), change_weights_sign_spca(), compare_spca(), is.spca(), new_spca(), plot.spca(), print.spca(), show_correlations(), show_weights(), spca(), spca_object

Examples

data(holzinger)
ho_cspca = spca(holzinger, n_comps = 2)
summary(ho_cspca)

Wachter QQ Plot for Eigenvalues (Deprecated)

Description

wachter_qqplot() is retained for backward compatibility. Use qqplot_spca() with objects returned by pca() in new code.

Usage

wachter_qqplot(
  eigenvalues,
  p = NULL,
  n,
  gamma,
  cor = TRUE,
  common_var = 1,
  n_plot = NULL,
  n_fitline = NULL,
  addtitle = TRUE,
  show_plot = TRUE,
  return_plot = FALSE
)

Arguments

Value

If return_plot = TRUE, a ggplot object; otherwise NULL invisibly.

See Also

Other pca: pca(), qqplot_spca(), screeplot_spca(), spca_screeplot()