Package {spca}

Least Squares Sparse Principal Components Analysis

Description

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

Details

LS-SPCA is different for other SPCA methods that compute sparse PCs with maximal variance. Details about LS-SPCA can be found in the articles cited below and in the extended vignette.

This release accompanies the related article and is intended to support full reproduction of the results reported therein.

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

Fitting functions

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

• pca() Computes PCA solutions from a data or covariance/correlation matrix. Returns an spca_object of class spca.

S3 methods for objects of class spca include: pca() returns PCA results as an spca object. methods

• print()

• plot()

• summary()

Utilities

• is.spca() Verifies if an object inherits from class spca.

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

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

• aggregate_by_group() Sums loadings or contributions wrt an index vector.

• show_contributions_spca() Prints the nonzero contributions separately for each sPC.

• change_loadings_sign_spca() Changes the sign of the loadings and all related elements in an 'spca object.

• spca_screeplot() and wachter_qqplot() Diagnostic plots usefull to determine the number of components to retain in PCA.

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 loadings. 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 loadings or contributions by group

Description

Compute group-level sums from a vector, matrix, data frame, or spca object according to a grouping variable.

Usage

aggregate_by_group(
  X,
  groups,
  only_nonzero = TRUE,
  contributions = TRUE,
  digits = ifelse(contributions, 1, 3),
  print_table = TRUE,
  return_table = FALSE
)

Arguments

Details

If contributions = TRUE but the input values do not sum to one in absolute value, contributions is set to FALSE and digits is set to 3. Aggregated sums are not expected to retain the unit-norm property of the original loadings or contributions.

Value

Invisibly returns the aggregated numeric vector or matrix by default. If return_table = TRUE, returns the same object visibly. Rows correspond to groups and columns correspond to components when X is a matrix, data frame, or spca object.

Examples

data(holzinger)
data(holzinger_scales)
ho_cspca = spca(holzinger, n_comps = 2)
aggregate_by_group(ho_cspca, groups = holzinger_scales)

Change the sign of selected loadings in an spca object

Description

Flip the sign of selected sparse principal components in an spca object.

Usage

change_loadings_sign_spca(spca_obj, index_to_change)

Arguments

Details

The function multiplies by -1 the selected columns of loadings and contributions. It also updates loadings_list, scores, and the corresponding rows and columns of spc_cor when these elements are present. This is useful because principal components and sparse principal components are defined only up to sign.

Value

The modified spca_obj, with the selected components sign-flipped.

See Also

Other spca: compare_spca(), is.spca(), new_spca(), plot.spca(), print.spca(), show_contributions_spca(), spca(), spca_object, summary.spca()

Compare two or more spca solutions

Description

Plot loadings 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_loadings = TRUE,
  plot_type = c("bars", "points"),
  methods_names = NULL,
  x_axis_var_names = TRUE,
  col_grouplines = "red",
  color_scale = c("ggplot", "cbb", "printsafe", "bw"),
  col_short_names = TRUE,
  print_tables = TRUE,
  print_loadings = TRUE,
  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 loadings or contributions plot.

See Also

Other spca: change_loadings_sign_spca(), is.spca(), new_spca(), plot.spca(), print.spca(), show_contributions_spca(), 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 loadings, contributions, explained-variance summaries, component counts, cardinalities, loading 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: change_loadings_sign_spca(), compare_spca(), new_spca(), plot.spca(), print.spca(), show_contributions_spca(), 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 loadings

Description

Build an object of class spca from a loadings 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: change_loadings_sign_spca(), compare_spca(), is.spca(), plot.spca(), print.spca(), show_contributions_spca(), 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)

Compute 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 loadings.

Value

An spca_object with an additional eigenvalues vector containing the eigenvalues up to the rank used by the selected backend.

See Also

Other pca: 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 loadings, 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_loadings = NULL,
  variable_groups = NULL,
  plot_title = NULL,
  return_plot = FALSE,
  show_plot = TRUE,
  controls = list(color_scale = c("ggplot", "cbb", "printsafe", "bw"), variable_names =
    NULL, 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_loadings 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 NULL). If NULL, row names of the loading 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: change_loadings_sign_spca(), compare_spca(), is.spca(), new_spca(), print.spca(), show_contributions_spca(), 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 loadings, 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: change_loadings_sign_spca(), compare_spca(), is.spca(), new_spca(), plot.spca(), show_contributions_spca(), spca(), spca_object, summary.spca()

Examples

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

Show nonzero contributions by component

Description

Convert the nonzero loadings stored in an spca object into percentage contributions for selected components.

Usage

show_contributions_spca(
  spca_obj,
  cols = NULL,
  print_list = TRUE,
  return_list = FALSE
)

Arguments

Value

If return_list = TRUE, returns the selected contributions. Otherwise, returns NULL invisibly.

See Also

Other spca: change_loadings_sign_spca(), compare_spca(), is.spca(), new_spca(), plot.spca(), print.spca(), spca(), spca_object, summary.spca()

Examples

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

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_loading = FALSE,
  eps_pm_loading = 1e-04,
  maxiter_pm_loading = 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: change_loadings_sign_spca(), compare_spca(), is.spca(), new_spca(), plot.spca(), print.spca(), show_contributions_spca(), 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 by new_spca()..

Components

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

loadings

p \times r matrix of sparse loadings.

contributions

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

n_comps

Number of sPCs.

cardinality

Number of nonzero loadings 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.

loadings_list

List of nonzero loading vectors, one per sPC.

spc_cor

n_comps \times n_comps correlation matrix of the sPC scores.

indices

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

scores

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

parameters

List of parameters used to compute the fit.

call

Matched call used to compute the fit.

See Also

Other spca: change_loadings_sign_spca(), compare_spca(), is.spca(), new_spca(), plot.spca(), print.spca(), show_contributions_spca(), spca(), summary.spca()

Plot eigenvalues in a scree plot

Description

Plot the first nplot eigenvalues against component order.

Usage

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

Arguments

Value

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

See Also

Other pca: pca(), wachter_qqplot()

Examples

data(holzinger)
ho_pca = pca(holzinger,  qq_plot = FALSE)
 spca_screeplot(ho_pca$eigenvalues)

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_load = FALSE,
  cor_with_pc = FALSE,
  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: change_loadings_sign_spca(), compare_spca(), is.spca(), new_spca(), plot.spca(), print.spca(), show_contributions_spca(), spca(), spca_object

Examples

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

Wachter QQ plot for eigenvalues

Description

Produce a QQ plot comparing observed eigenvalues with Marchenko–Pastur (Wachter) theoretical quantiles.

Usage

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

Arguments

Details

The QQ plot is based on the Marchenko–Pastur distribution of the eigenvalues of a random covariance matrix generated from variables with a common variance. If the data set or covariance matrix comes from variables with different variances, the QQ plot is not valid. A simple introduction to the QQ plot can be found at https://brainder.org/tag/wachter-test/; see the extended vignette for references.

Value

If return_plot = TRUE, returns a ggplot object. Otherwise, returns NULL invisibly.

See Also

Other pca: pca(), spca_screeplot()

Examples

data(holzinger)
ho_pca = pca(holzinger,  qq_plot = FALSE)
 wachter_qqplot(ho_pca$eigenvalues, p = ncol(holzinger), n = nrow(holzinger),
  cor = TRUE, n_fitline = -3)