| Type: | Package |
| Title: | Generalized Contrastive Principal Component Analysis |
| Version: | 0.0.1 |
| Description: | Implements dense and sparse generalized contrastive principal component analysis (gcPCA) with S3 fit objects and methods for prediction, summaries, and plotting. The gcPCA is a hyperparameter-free method for comparing high-dimensional datasets collected under different experimental conditions to reveal low-dimensional patterns enriched in one condition compared to the other. Method details are described in de Oliveira, Garg, Hjerling-Leffler, Batista-Brito, and Sjulson (2025) <doi:10.1371/journal.pcbi.1012747>. |
| License: | MIT + file LICENSE |
| Encoding: | UTF-8 |
| RoxygenNote: | 7.3.3 |
| URL: | https://github.com/SjulsonLab/generalized_contrastive_PCA |
| BugReports: | https://github.com/SjulsonLab/generalized_contrastive_PCA/issues |
| Imports: | graphics, stats |
| Suggests: | testthat (≥ 3.0.0) |
| Config/testthat/edition: | 3 |
| NeedsCompilation: | no |
| Packaged: | 2026-03-28 01:20:40 UTC; fermi |
| Author: | Eliezyer de Oliveira [aut, cre] |
| Maintainer: | Eliezyer de Oliveira <eliezyer.deoliveira@gmail.com> |
| Repository: | CRAN |
| Date/Publication: | 2026-04-01 08:30:08 UTC |
gcpca package
Description
Dense and sparse generalized contrastive principal component analysis.
Author(s)
Maintainer: Eliezyer de Oliveira eliezyer.deoliveira@gmail.com
See Also
Extract gcPCA loadings
Description
Extract gcPCA loadings
Usage
## S3 method for class 'gcPCA'
coef(object, ...)
## S3 method for class 'sparse_gcPCA'
coef(object, ...)
Arguments
object |
A fitted |
... |
Unused. |
Value
For dense models, a loadings matrix. For sparse models, a named list of loading matrices (one per lasso penalty).
Return fitted training scores
Description
Return fitted training scores
Usage
## S3 method for class 'gcPCA'
fitted(object, ...)
Arguments
object |
A fitted |
... |
Passed to |
Value
A list with Ra_scores and Rb_scores.
Fit a generalized contrastive PCA model
Description
gcPCA() fits dense generalized contrastive principal components from two
data matrices (Ra and Rb) measured on the same feature set.
Usage
gcPCA(
Ra,
Rb,
method = "v4",
Ncalc = NULL,
Nshuffle = 0,
normalize_flag = TRUE,
alpha = 1,
alpha_null = 0.975,
cond_number = 10^13
)
Arguments
Ra |
Matrix for condition A ( |
Rb |
Matrix for condition B ( |
method |
Character scalar selecting optimization variant. |
Ncalc |
Optional number of gcPCs for orthogonal variants ( |
Nshuffle |
Number of shuffles used to estimate a null distribution. |
normalize_flag |
Logical; if |
alpha |
Contrastive coefficient used by method |
alpha_null |
Quantile for null thresholding (reserved in current code). |
cond_number |
Maximum allowed denominator condition number. |
Value
An object of class "gcPCA" with loadings, scores, objective values,
and fit metadata.
Examples
set.seed(1)
Ra <- matrix(rnorm(40 * 5), ncol = 5)
Rb <- matrix(rnorm(35 * 5), ncol = 5)
fit <- gcPCA(Ra, Rb, method = "v4", Ncalc = 3)
pred <- predict(fit, Ra = Ra)
str(pred$Ra_scores)
Get gcPCA loadings
Description
Convenience wrapper around coef() for "gcPCA" and "sparse_gcPCA"
objects.
Usage
loadings(object, ...)
Arguments
object |
A fitted model object. |
... |
Extra arguments passed to |
Value
A loading matrix or a named list of loading matrices.
Plot gcPCA scores
Description
Plot gcPCA scores
Usage
## S3 method for class 'gcPCA'
plot(x, which = c(1, 2), ...)
Arguments
x |
A fitted |
which |
Integer vector of length 2 indicating components to plot. |
... |
Extra graphical parameters passed to |
Value
x, invisibly.
Project data with a fitted gcPCA model
Description
Project data with a fitted gcPCA model
Usage
## S3 method for class 'gcPCA'
predict(object, Ra = NULL, Rb = NULL, ...)
## S3 method for class 'sparse_gcPCA'
predict(object, Ra = NULL, Rb = NULL, ...)
Arguments
object |
A fitted |
Ra |
Optional matrix for condition A. |
Rb |
Optional matrix for condition B. |
... |
Unused. |
Value
For dense models, a list of score matrices. For sparse models, a list of score-matrix lists, one per penalty value.
Print a gcPCA model
Description
Print a gcPCA model
Usage
## S3 method for class 'gcPCA'
print(x, ...)
Arguments
x |
A fitted |
... |
Unused. |
Value
x, invisibly.
Print a gcPCA summary
Description
Print a gcPCA summary
Usage
## S3 method for class 'summary.gcPCA'
print(x, ...)
Arguments
x |
A |
... |
Unused. |
Value
x, invisibly.
Get gcPCA scores
Description
Convenience wrapper around predict() for "gcPCA" and "sparse_gcPCA"
objects.
Usage
scores(object, newdata = NULL, ...)
Arguments
object |
A fitted model object. |
newdata |
Optional matrix (treated as |
... |
Extra arguments passed to |
Value
A list of projected scores.
Fit a sparse generalized contrastive PCA model
Description
sparse_gcPCA() fits sparse gcPCA loadings over a path of lasso penalties.
Usage
sparse_gcPCA(
Ra,
Rb,
method = "v4",
Ncalc = NULL,
normalize_flag = TRUE,
Nsparse = NULL,
Nshuffle = 0,
lasso_penalty = exp(seq(log(0.01), log(1), length.out = 10)),
ridge_penalty = 0,
alpha = 1,
alpha_null = 0.975,
tol = 1e-05,
max_steps = 1000,
cond_number = 1e+13
)
Arguments
Ra |
Matrix for condition A ( |
Rb |
Matrix for condition B ( |
method |
Character scalar selecting optimization variant. |
Ncalc |
Optional number of gcPCs for orthogonal variants ( |
normalize_flag |
Logical; if |
Nsparse |
Number of sparse gcPCs to estimate. |
Nshuffle |
Number of shuffles passed to the dense gcPCA stage. |
lasso_penalty |
Numeric vector of lasso penalties. |
ridge_penalty |
Numeric ridge penalty. |
alpha |
Contrastive coefficient used by method |
alpha_null |
Quantile for null thresholding (reserved in current code). |
tol |
Convergence tolerance for sparse optimization. |
max_steps |
Maximum number of sparse optimization iterations. |
cond_number |
Maximum allowed denominator condition number. |
Value
An object of class c("sparse_gcPCA", "gcPCA") containing sparse
loadings and training projections across penalties.
Examples
set.seed(1)
Ra <- matrix(rnorm(50 * 6), ncol = 6)
Rb <- matrix(rnorm(45 * 6), ncol = 6)
fit <- sparse_gcPCA(Ra, Rb, method = "v4", Nsparse = 2,
lasso_penalty = c(0.05, 0.1))
pred <- predict(fit, Ra = Ra)
str(pred$Ra_scores)
Summarize a gcPCA model
Description
Summarize a gcPCA model
Usage
## S3 method for class 'gcPCA'
summary(object, ...)
Arguments
object |
A fitted |
... |
Unused. |
Value
A "summary.gcPCA" list with eigenvalues, standard deviations,
explained variance summaries, and tuning settings.