% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ComDim_PCA.R
\name{ComDim_PCA}
\alias{ComDim_PCA}
\title{ComDim_PCA}
\usage{
ComDim_PCA(
  MB = MB,
  ndim = NULL,
  normalise = FALSE,
  threshold = 1e-10,
  loquace = FALSE,
  CompMethod = "Normal",
  Partitions = 1
)
}
\arguments{
\item{MB}{A MultiBlock object.}

\item{ndim}{Number of Common Dimensions.}

\item{normalise}{To apply normalisation. FALSE == no (default), TRUE == yes.}

\item{threshold}{The threshold limit to stop the iterations. If the "difference of fit" < threshold (1e-10 as default).}

\item{loquace}{To display the calculation times. TRUE == yes, FALSE == no (default).}

\item{CompMethod}{To speed-up the analysis for really big MultiBlocks. 'Normal' (default), 'Kernel', 'PCT', 'Tall' or 'Wide'.}

\item{Partitions}{To speed-up the analysis for really big MultiBlocks. This parameter is used if CompMethod is 'Tall' or 'Wide'.}
}
\value{
A \code{ComDim} object. Slots for supervised analysis
  (\code{R2Y}, \code{Q2}, \code{DQ2}, \code{VIP}, \code{VIP.block},
  \code{PLS.model}, \code{cv}, \code{Prediction}) are empty. The
  populated slots are:
\describe{
  \item{\code{Method}}{\code{"PCA"}.}
  \item{\code{ndim}}{Number of Common Dimensions extracted.}
  \item{\code{Q.scores}}{Global scores matrix (\eqn{n \times ndim}).
    Column names are \code{CC1}, \code{CC2}, etc.; row names are sample
    names.  Each column \eqn{\mathbf{q}_a} is a unit-norm consensus score,
    the dominant left singular vector of the salience-weighted concatenated
    blocks
    \eqn{\mathbf{W} = [\sqrt{\lambda_1}\mathbf{X}_1 \mid \cdots \mid
    \sqrt{\lambda_B}\mathbf{X}_B]}.}
  \item{\code{T.scores}}{Named list of block-specific local scores matrices
    (\eqn{n \times ndim} each).  For block \eqn{b} and component \eqn{a}:
    local loading \eqn{\mathbf{p}_{ba} = \mathbf{X}_b'\mathbf{q}_a} and
    local score
    \eqn{\mathbf{t}_{ba} =
    \mathbf{X}_b\,\mathbf{p}_{ba}(\mathbf{p}_{ba}'\mathbf{p}_{ba})^{-1}}.}
  \item{\code{P.loadings}}{Global loadings matrix (\eqn{p_{tot} \times
    ndim}).  Column \eqn{a} is
    \eqn{\mathbf{P}_a = \mathbf{X}'\mathbf{q}_a},
    where \eqn{\mathbf{X}} is the mean-centred (and optionally normalised)
    concatenated blocks.}
  \item{\code{Saliences}}{Block salience (weight) matrix (\eqn{ntable
    \times ndim}, row names = block names).  Entry \eqn{(b,a)} is
    \eqn{\lambda_{ba} =
    \mathbf{q}_a'\mathbf{X}_b\mathbf{X}_b'\mathbf{q}_a},
    the variance of block \eqn{b} captured by global score \eqn{a}.}
  \item{\code{R2X}}{Proportion of multi-block inertia captured by each
    component (named vector, length \eqn{ndim}).  Let
    \eqn{d_a} be the leading singular value of \eqn{\mathbf{W}} for
    component \eqn{a} (stored as \eqn{Singular_a = d_a^2}); then
    \deqn{R2X_a = Singular_a^2 \big/ \sum_k Singular_k^2 = d_a^4 \big/
    \sum_k d_k^4.}}
  \item{\code{Singular}}{Squared leading singular values of
    \eqn{\mathbf{W}}, one per component:
    \eqn{Singular_a = d_a^2}.}
  \item{\code{Mean}}{List with \code{MeanMB}: named list of column-mean
    vectors per block, used for mean-centring.}
  \item{\code{Norm}}{List with \code{NormMB}: Frobenius norms used for
    block normalisation (all ones when \code{normalise = FALSE}).}
  \item{\code{variable.block}}{Character vector (length \eqn{p_{tot}})
    indicating the block name of each row in \code{P.loadings}.}
  \item{\code{runtime}}{Total computation time in seconds.}
}
}
\description{
Finding common dimensions in multi-block datasets.
}
\examples{
# Example 1: two data blocks.
b1 <- matrix(rnorm(500), 10, 50) # 10 samples, 50 variables
b2 <- matrix(rnorm(800), 10, 80) # 10 samples, 80 variables
mb <- MultiBlock(Data = list(b1 = b1, b2 = b2))
results <- ComDim_PCA(mb, 2)

# Example 2: two data blocks, each with different replicate number
b1 <- matrix(rnorm(500), 10, 50)
batch_b1 <- rep(1, 10)
b2 <- matrix(rnorm(2400), 30, 80)
batch_b2 <- c(rep(1, 10), rep(2, 10), rep(3, 10))
mb <- MultiBlock(
  Samples = list(
    b1 = paste0("samples_", 1:10),
    b2 = rep(paste0("samples_", 1:10), 3)
  ),
  Data = list(b1 = b1, b2 = b2),
  Batch = list(b1 = batch_b1, b2 = batch_b2),
  ignore.size = TRUE
)
rw <- SplitRW(mb)
results <- ComDim_PCA(rw, 2)
}
\references{
Jouan-Rimbaud Bouveresse D, Rutledge DN (2024).
  A synthetic review of some recent extensions of ComDim.
  \emph{Journal of Chemometrics}, 38(5), e3454.
  \doi{10.1002/cem.3454}

  Original MATLAB implementation: \url{https://github.com/DNRutledge/ComDim/}
}
