% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ComDim_Exploratory.R
\name{ComDim_Exploratory}
\alias{ComDim_Exploratory}
\title{ComDim_Exploratory - Extending matrix decomposition methods to multi-block data.}
\usage{
ComDim_Exploratory(
  MB = MB,
  ndim = NULL,
  FUN = FUN,
  normalise = FALSE,
  threshold = 1e-10,
  loquace = FALSE,
  method = "FUN",
  ...
)
}
\arguments{
\item{MB}{A MultiBlock object.}

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

\item{FUN}{The function used as the core of the ComDim analysis. It must accept a matrix
\code{W} (salience-weighted concatenated blocks) and \code{ndim} as its first two
arguments, and return a matrix of scores with one column per component.}

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

\item{threshold}{The threshold limit to stop the iterations. Iterations stop when the
change in the global score vector is below this value (1e-10 as default).}

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

\item{method}{A string label identifying the decomposition method used (default: 'FUN').}

\item{...}{Additional arguments passed to \code{FUN}.}
}
\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}}{The label supplied via the \code{method} argument.}
  \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
    derived from the dominant left direction of FUN applied to 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 variance captured by each
    component (named vector, length \eqn{ndim}).  Let \eqn{\mathbf{s}_a}
    be the score vector returned by FUN for component \eqn{a} (before
    unit-normalisation to obtain \eqn{\mathbf{q}_a}), so that
    \eqn{sv_a = \|\mathbf{s}_a\|}; then
    \deqn{R2X_a = sv_a^4 \big/ \sum_k sv_k^4 =
    Singular_a^2 \big/ \sum_k Singular_k^2.}}
  \item{\code{Singular}}{Squared L2 norms of the FUN score vectors:
    \eqn{Singular_a = sv_a^2 = \|\mathbf{s}_a\|^2}, used to derive
    \code{R2X}.}
  \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{
Extends any matrix decomposition method used for exploratory purposes to the multi-block
field. The user provides a function (\code{FUN}) to compute the scores from the
salience-weighted concatenated blocks; these scores are then used to derive the global
scores, local scores, and loadings following the traditional ComDim-PCA framework.
}
\examples{
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))

if (requireNamespace("ica", quietly = TRUE)) {
  fun.ICA <- function(W, ndim, ...) {
    # W is the concatenated MB.
    # ndim is the number of components.
    result <- ica::ica(W, ndim)
    # The function must return the source estimates (analogous to PCA scores).
    return(result$S)
  }
  resultsICA <- ComDim_Exploratory(mb,
    ndim = 2,
    FUN = fun.ICA,
    method = "ICA"
  )
}
}
\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}
}
