scPCA: Sparse Contrastive Principal Component Analysis
In scPCA: Sparse Contrastive Principal Component Analysis

Description Usage Arguments Value References Examples

Given target and background data frames or matrices, scPCA will perform the sparse contrastive principal component analysis (scPCA) of the target data for a given number of eigenvectors, a vector of real-valued contrast parameters, and a vector of sparsity inducing penalty terms.

If instead you wish to perform contrastive principal component analysis (cPCA), set the penalties argument to 0. So long as the n_centers parameter is larger than one, the automated hyperparameter tuning heuristic described in \insertCiteboileau2020;textualscPCA is used. Otherwise, the semi-automated approach of \insertCiteabid2018exploring;textualscPCA is used to select the appropriate hyperparameter.

scPCA(
  target,
  background,
  center = TRUE,
  scale = FALSE,
  n_eigen = 2,
  cv = NULL,
  alg = c("iterative", "var_proj", "rand_var_proj"),
  contrasts = exp(seq(log(0.1), log(1000), length.out = 40)),
  penalties = seq(0.05, 1, length.out = 20),
  clust_method = c("kmeans", "pam", "hclust"),
  n_centers = NULL,
  max_iter = 10,
  linkage_method = "complete",
  n_medoids = 8,
  parallel = FALSE,
  clusters = NULL,
  eigdecomp_tol = 1e-10,
  eigdecomp_iter = 1000
)

`target`	The target (experimental) data set, in a standard format such as a `data.frame` or `matrix`. `dgCMatrix` and `DelayedMatrix` objects are also supported.
`background`	The background data set, in a standard format such as a `data.frame` or `matrix`. The features must match the features of the target data set. `dgCMatrix` and `DelayedMatrix` objects are also supported.
`center`	A `logical` indicating whether the target and background data sets' features should be centered to mean zero.
`scale`	A `logical` indicating whether the target and background data sets' features should be scaled to unit variance.
`n_eigen`	A `numeric` indicating the number of eigenvectors (or (sparse) contrastive components) to be computed. Two eigenvectors are computed by default.
`cv`	A `numeric` indicating the number of cross-validation folds to use in choosing the optimal contrastive and penalization parameters from over the grids of `contrasts` and `penalties`. Cross-validation is expected to improve the robustness and generalization of the choice of these parameters. However, it increases the time the procedure costs. The default is therefore `NULL`, corresponding to no cross-validation.
`alg`	A `character` indicating the sparse PCA algorithm used to sparsify the contrastive loadings. Currently supports `iterative` for the \insertCitezou2006sparse;textualscPCA implementation, `var_proj` for the non-randomized \insertCiteerichson2018sparse;textualscPCA solution, and `rand_var_proj` for the randomized \insertCiteerichson2018sparse;textualscPCA implementation. Defaults to `iterative`.
`contrasts`	A `numeric` vector of the contrastive parameters. Each element must be a unique, non-negative real number. By default, 40 logarithmically spaced values between 0.1 and 1000 are used. If a single value is provided and `penalties` is set to 0, then `n_centers`, `clust_method`, `max_iter`, `linkage_method`, `n_medoids`, and `parallel` can be safely ignored.
`penalties`	A `numeric` vector of the L1 penalty terms on the loadings. The default is to use 20 equidistant values between 0.05 and 1. If `penalties` is set to 0, then cPCA is performed in place of scPCA. See `contrasts` and `n_centers` arguments for more infotmation.
`clust_method`	A `character` specifying the clustering method to use for choosing the optimal contrastive parameter. Currently, this is limited to either k-means, partitioning around medoids (PAM), and hierarchical clustering. The default is k-means clustering.
`n_centers`	A `numeric` giving the number of centers to use in the clustering algorithm. If set to 1, cPCA, as first proposed by \insertCiteerichson2018sparse;textualscPCA, is performed, regardless of what the `penalties` argument is set to.
`max_iter`	A `numeric` giving the maximum number of iterations to be used in k-means clustering. Defaults to 10.
`linkage_method`	A `character` specifying the agglomerative linkage method to be used if `clust_method = "hclust"`. The options are `ward.D2`, `single`, `complete`, `average`, `mcquitty`, `median`, and `centroid`. The default is `complete`.
`n_medoids`	A `numeric` indicating the number of medoids to consider if `n_centers` is set to 1 and `contrasts` is a vector of length 2 or more. The default is 8 medoids.
`parallel`	A `logical` indicating whether to invoke parallel processing via the BiocParallel infrastructure. The default is `FALSE` for sequential evaluation.
`clusters`	A `numeric` vector of cluster labels for observations in the `target` data. Defaults to `NULL`, but is otherwise used to identify the optimal set of hyperparameters when fitting the scPCA and the automated version of cPCA. If a vector is provided, the `n_centers`, `clust_method`, `max_iter`, `linkage_method`, and `n_medoids` arguments can be safely ignored.
`eigdecomp_tol`	A `numeric` providing the level of precision used by eigendecompositon calculations. Defaults to `1e-10`.
`eigdecomp_iter`	A `numeric` indicating the maximum number of interations performed by eigendecompositon calculations. Defaults to `1000`.

A list containing the following components:

rotation: The matrix of variable loadings if n_centers is larger than one. Otherwise, a list of rotation matrices is returned, one for each medoid. The number of medoids is specified by n_medoids.
x: The rotated data, centred and scaled if requested, multiplied by the rotation matrix if n_centers is larger than one. Otherwise, a list of rotated data matrices is returned, one for each medoid. The number of medoids is specified by n_medoids.
contrast: The optimal contrastive parameter.
penalty: The optimal L1 penalty term.
center: A logical indicating whether the target dataset was centered.
scale: A logical indicating whether the target dataset was scaled.

\insertAllCited

# perform cPCA on the simulated data set
scPCA(
  target = toy_df[, 1:30],
  background = background_df,
  contrasts = exp(seq(log(0.1), log(100), length.out = 5)),
  penalties = 0,
  n_centers = 4
)

# perform scPCA on the simulated data set
scPCA(
  target = toy_df[, 1:30],
  background = background_df,
  contrasts = exp(seq(log(0.1), log(100), length.out = 5)),
  penalties = seq(0.1, 1, length.out = 3),
  n_centers = 4
)

# perform cPCA on the simulated data set with known clusters
scPCA(
  target = toy_df[, 1:30],
  background = background_df,
  contrasts = exp(seq(log(0.1), log(100), length.out = 5)),
  penalties = 0,
  clusters = toy_df[, 31]
)

# cPCA as implemented in Abid et al.
scPCA(
  target = toy_df[, 1:30],
  background = background_df,
  contrasts = exp(seq(log(0.1), log(100), length.out = 10)),
  penalties = 0,
  n_centers = 1
)