Run (joint) robust principal component analysis (RPCA)

These functions implement robust principal component analysis (RPCA) for single tables and joint RPCA for multiple tables. *RPCA functions run RPCA for single table. *JointRPCA runs the analysis jointly for multiple tables. get* functions return the results of the analysis while add* adds them to the input object.

getRPCA(x, ...)

addRPCA(x, ...)

getJointRPCA(x, ...)

addJointRPCA(x, ...)

# S4 method for class 'SingleCellExperiment'
getRPCA(x, ...)

# S4 method for class 'SummarizedExperiment'
getRPCA(x, assay.type = "counts", ...)

# S4 method for class 'SummarizedExperiment'
addRPCA(x, name = "RPCA", ...)

# S4 method for class 'MultiAssayExperiment'
getJointRPCA(x, experiments, assay.types, ...)

# S4 method for class 'SingleCellExperiment'
getJointRPCA(x, experiments, assay.types, ...)

# S4 method for class 'SingleCellExperiment'
addJointRPCA(x, name = "JointRPCA", ...)

# S4 method for class 'MultiAssayExperiment'
addJointRPCA(x, name = "JointRPCA", ...)

Arguments

x

a SummarizedExperiment object.

...

additional arguments:

ncomponents:Integer scalar. The number of components to estimate. (Default: 3)
max.iterations:Integer scalar. The number of iterations run in OptSpace algorithm. (Default: 3)
tolerance:Numeric scalar. Accepted error between lower rank representation obtained by OptSpace algorithm and original table. (Default: 3)

assay.type

Character scalar. Specifies the name of assay used in calculation. (Default: "counts")

name

Character scalar. Name of results stored in x. (Default: "RPCA" or "JointRPCA" depending on the method)

experiments

Character vector or integer scalar. Names or indices of experiments selected from x.

assay.types

Character vector. Names assays selected from experiments.

Value

matrix, TreeSummarizedExperiment or MultiAssayExperiment object.

Details

These functions perform robust principal component analysis (RPCA) using a low-rank matrix approximation followed by principal component analysis. Missing values are handled using matrix completion based on the OptSpace algorithm.

Before running RPCA or Joint-RPCA, untransformed assays can be filtered separately with filterRPCAInput(). When filtering is used, it must be performed before the robust centered log-ratio transformation. Filtering thresholds should be selected separately for each experiment according to its sequencing depth and prevalence.

Single-table RPCA

For a single assay, the workflow is:

Extract the selected assay matrix
Estimate a low-rank approximation of the matrix using the OptSpace algorithm, which reconstructs missing values and reduces noise.
Apply double centering (row and column centering).
Apply PCA (via singular value decomposition) to the centered matrix.
Return the sample coordinates in PCA space together with additional information such as loadings, explained variance, and pairwise distances.

Joint RPCA

When multiple assays are provided, joint RPCA estimates a shared low-rank representation across all tables. Each table may contain different features, but they must share the same samples.

The workflow is:

Extract the selected experiments and assays.
Estimate a joint low-rank representation using a joint OptSpace algorithm that learns shared sample factors while allowing table-specific feature loadings.
Apply double centering (row and column centering).
Perform PCA on the centered matrix. to obtain the final sample coordinates.
Return the sample coordinates in PCA space together with additional information such as loadings, explained variance, and pairwise distances.

To assess generalization, the joint RPCA procedure optionally splits the samples into training and test sets. The low-rank model is learned using the training data and the test samples are projected into the resulting PCA space. Reconstruction error for the test set is returned as a measure of model fit.

The returned object contains the PCA sample scores as the main result, with additional information (e.g., rotation matrix, explained variance, reconstructed matrix, and reconstruction error) stored in attributes.

References

Martino, C. et al. (2019). A Novel Sparse Compositional Technique Reveals Microbial Perturbations. mSystems, 4(1), e00016-19. doi:10.1128/mSystems.00016-19

Martino, C. and Shenhav, L. et al. (2020). Context-aware dimensionality reduction deconvolutes gut microbial community dynamics. Nature Biotechnology. doi:10.1038/s41587-020-0660-7

Cordazzo Vargas, B. et al. (2026). Joint-RPCA: Domain-Aware Multi-Omics Integration for Systems Microbiology. Molecular Systems Biology. doi:10.1038/s44320-026-00236-3

Author

The RPCA method is reported in Martino et al. (2019) and the R/Bioconductor implementation utilizes the robust Aitchison distance from vegan::decostand.

The Joint-RPCA method was adapted from the original Python-based implementation in biocore/Gemelli by Bianca Cordazzo Vargas, Liat Shenhav, and Cameron Martino. The R/Bioconductor implementation was subsequently prepared by Aituar Bektanov, Sabuj Bhowmick, Tuomas Borman, and Leo Lahti.

Examples

data("ibdmdb")
mae <- ibdmdb

# Filter each untransformed assay before applying rclr.
# See filterRPCAInput() for data-specific filtering thresholds.
mae[["MGX"]] <- filterRPCAInput(
    mae[["MGX"]],
    assay.type = "mgx"
)
mae[["MTX"]] <- filterRPCAInput(
    mae[["MTX"]],
    assay.type = "mtx"
)

# Apply the robust centered log-ratio transformation.
# Specify that the 0-values are not imputed as Joint-RPCA
# itself does the matrix completion.
mae[["MGX"]] <- transformAssay(
    mae[["MGX"]],
    assay.type = "mgx",
    method = "rclr",
    impute = FALSE
)
mae[["MTX"]] <- transformAssay(
    mae[["MTX"]],
    assay.type = "mtx",
    method = "rclr",
    impute = FALSE
)

# Run Joint-RPCA.
joint_rpca <- getJointRPCA(
    mae,
    experiments = c("MGX", "MTX"),
    assay.types = c("rclr", "rclr")
)

# Inspect sample scores and variation across components.
head(joint_rpca)
#>                  PC1          PC2          PC3
#> CSM5MCZD -0.12153327  0.046793403  0.046527887
#> CSM67UBZ -0.17323402 -0.091922507  0.106287209
#> CSM67UCK -0.01746996  0.066441216 -0.007040505
#> CSM67UDF -0.16482651 -0.004155285 -0.068194972
#> CSM67UDY -0.11492127 -0.035342705 -0.058941026
#> CSM7KOJO  0.13289309 -0.205676050  0.136539736
round(attr(joint_rpca, "percentVar"), 2)
#>   PC1   PC2   PC3 
#> 53.17 30.85 15.98 

# Run RPCA for one experiment.
single_rpca <- getRPCA(
    mae[["MGX"]],
    assay.type = "rclr"
)