% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/AllGenerics.R, R/getRPCA.R
\name{getRPCA}
\alias{getRPCA}
\alias{addRPCA}
\alias{getJointRPCA}
\alias{addJointRPCA}
\alias{getRPCA,SingleCellExperiment-method}
\alias{getRPCA,SummarizedExperiment-method}
\alias{addRPCA,SummarizedExperiment-method}
\alias{getJointRPCA,MultiAssayExperiment-method}
\alias{getJointRPCA,SingleCellExperiment-method}
\alias{addJointRPCA,SingleCellExperiment-method}
\alias{addJointRPCA,MultiAssayExperiment-method}
\title{Run (joint) robust principal component analysis (RPCA)}
\usage{
getRPCA(x, ...)

addRPCA(x, ...)

getJointRPCA(x, ...)

addJointRPCA(x, ...)

\S4method{getRPCA}{SingleCellExperiment}(x, ...)

\S4method{getRPCA}{SummarizedExperiment}(x, assay.type = "counts", ...)

\S4method{addRPCA}{SummarizedExperiment}(x, name = "RPCA", ...)

\S4method{getJointRPCA}{MultiAssayExperiment}(x, experiments, assay.types, ...)

\S4method{getJointRPCA}{SingleCellExperiment}(x, experiments, assay.types, ...)

\S4method{addJointRPCA}{SingleCellExperiment}(x, name = "JointRPCA", ...)

\S4method{addJointRPCA}{MultiAssayExperiment}(x, name = "JointRPCA", ...)
}
\arguments{
\item{x}{a \code{\link[SummarizedExperiment]{SummarizedExperiment}} object.}

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

\item{assay.type}{\code{Character scalar}. Specifies the name of assay
used in calculation. (Default: \code{"counts"})}

\item{name}{\code{Character scalar}. Name of results stored in \code{x}.
(Default: \code{"RPCA"} or \code{"JointRPCA"} depending on the method)}

\item{experiments}{\code{Character vector} or \code{integer scalar}. Names
or indices of experiments selected from \code{x}.}

\item{assay.types}{\code{Character vector}. Names assays selected from
\code{experiments}.}
}
\value{
\code{matrix}, \code{TreeSummarizedExperiment} or \code{MultiAssayExperiment}
object.
}
\description{
These functions implement robust principal component analysis (RPCA)
for single tables and joint RPCA for multiple tables.
\code{*RPCA} functions run RPCA for single table. \code{*JointRPCA} runs the
analysis jointly for multiple tables. \code{get*} functions return the
results of the analysis while \code{add*} adds them to the input 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.

\strong{Single-table RPCA}

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

\strong{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:
\enumerate{
\item Extract the selected experiments and assays.
\item Estimate a joint low-rank representation using a joint OptSpace
algorithm that learns shared sample factors while allowing
table-specific feature loadings.
\item Apply double centering (row and column centering).
\item Perform PCA on the centered matrix. to obtain the final
sample coordinates.
\item 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.
}
\examples{
data("ibdmdb")
mae <- ibdmdb

# Apply data transformations. With impute=FALSE, missing values are preserved
# and not imputed.
mae[[1]] <- transformAssay(
    mae[[1]], assay.type = "mgx", method = "rclr", impute = FALSE)
mae[[2]] <- transformAssay(
    mae[[2]], assay.type = "mtx", method = "rclr", impute = FALSE)

# Run joint-RPCA
res <- getJointRPCA(
    mae,
    experiments = c(1, 2),
    assay.types = c("rclr", "rclr")
)

# Run RPCA for single experiment
res <- getRPCA(mae[[1]], assay.type = "rclr")

}
\references{
Martino, C. and Shenhav, L. et al. (2020)
Context-aware dimensionality reduction deconvolutes gut microbial community
dynamics.
\emph{Nat. Biotechnol.} doi:10.1038/s41587-020-0660-7
}
\seealso{
\code{\link[scater:runPCA]{scater::runPCA}}
}
\author{
The RPCA method is reported in Martino et al. (2020) and the
R/Bioconductor implementation utilizes the robust Aitchison
distance from \code{\link[vegan:decostand]{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, Tuomas Borman, and Leo Lahti.
}
