% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ComDim_PLS.R
\name{ComDim_PLS}
\alias{ComDim_PLS}
\title{ComDim_PLS}
\usage{
ComDim_PLS(
  MB = MB,
  y = y,
  ndim = NULL,
  method = c("PLS-DA", "PLS-R"),
  decisionRule = c("fixed", "max")[2],
  normalise = FALSE,
  scale.y = FALSE,
  threshold = 1e-10,
  loquace = FALSE,
  CompMethod = "Normal",
  Partitions = 1,
  cv.k = 7
)
}
\arguments{
\item{MB}{A MultiBlock object.}

\item{y}{The Y-block to use in the PLS model as dependent data. A class vector or a dummy matrix.}

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

\item{method}{PLS-DA or PLS-R.}

\item{decisionRule}{Only used if method is set to PLS-DA. If 'fixed', samples are assigned to the class with Y-hat above 1/nclasses. If 'max', samples are assigned to the class with the highest Y-hat.}

\item{normalise}{To apply block normalisation. FALSE == no (default), TRUE == yes.
When TRUE each block is mean-centred and then divided by its Frobenius norm so
that all blocks have unit total inertia entering the ComDim loop.
Has no effect on the Y-block; use \code{scale.y} for that.}

\item{scale.y}{Logical (default FALSE). When TRUE and \code{method = 'PLS-R'},
each column of Y is mean-centred and scaled to unit variance before the PLS
fit. The stored B, B0, and Ypred are back-transformed to the original Y scale,
so downstream outputs (R2Y, Q2, predictions) are always in the original units.
Ignored when \code{method = 'PLS-DA'} (dummy Y should not be scaled).}

\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 multi-blocks. 'Normal' (default), 'Kernel', 'PCT', 'Tall' or 'Wide'.}

\item{Partitions}{To speed up the analysis for really big multi-blocks. This parameter is used if CompMethod is 'Tall' or 'Wide'.}

\item{cv.k}{Number of folds for k-fold cross-validation (default 7). Set to 0 to skip CV. When cv.k >= 2, Q2 and DQ2 in the output reflect cross-validated predictive ability; otherwise they reflect training-set fit (R2).}
}
\value{
A \code{ComDim} object. All slots are populated. Key slots:
\describe{
  \item{\code{Method}}{\code{"PLS-DA"} or \code{"PLS-R"}.}
  \item{\code{ndim}}{Number of Common Dimensions extracted.}
  \item{\code{Q.scores}}{Global consensus PLS scores (\eqn{n \times ndim}).
    Each column \eqn{\mathbf{q}_a} (unit-norm) is the dominant left
    singular vector from the NIPALS PLS applied to the salience-weighted
    concatenated blocks.}
  \item{\code{T.scores}}{Named list of block-specific local scores
    (\eqn{n \times ndim} each).  Local loading
    \eqn{\mathbf{p}_{ba} = \mathbf{X}_b'\mathbf{q}_a}; 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 (\eqn{p_{tot} \times ndim}):
    \eqn{\mathbf{P} = \mathbf{X}'\mathbf{Q}}, where \eqn{\mathbf{X}} is
    the mean-centred (and optionally normalised) concatenated blocks.}
  \item{\code{Saliences}}{Block salience matrix (\eqn{ntable \times ndim}):
    \eqn{\lambda_{ba} =
    \mathbf{q}_a'\mathbf{X}_b\mathbf{X}_b'\mathbf{q}_a}.}
  \item{\code{R2X}}{Proportion of X variance captured by each component
    (named vector, length \eqn{ndim}).  Let \eqn{\mathbf{t}_a} be the
    NIPALS PLS X-score vector for component \eqn{a} on the salience-
    weighted blocks; then
    \deqn{R2X_a = \|\mathbf{t}_a\|^4 \big/ \sum_k \|\mathbf{t}_k\|^4.}}
  \item{\code{R2Y}}{Cumulative Y-variance explained (named vector, length
    \eqn{ndim}).  \eqn{R2Y_a} is the \eqn{R^2} from an OLS regression of
    \eqn{\mathbf{Y}} on the first \eqn{a} global scores with an intercept:
    \deqn{R2Y_a = 1 - RSS_a / TSS_Y,}
    where \eqn{RSS_a} is the residual SS when predicting \eqn{\mathbf{Y}}
    from \eqn{[1, \mathbf{q}_1, \ldots, \mathbf{q}_a]}.
    \strong{Note:} \eqn{R2Y_a} is cumulative — it reflects the total
    Y-variance explained by the first \eqn{a} components together,
    not the marginal contribution of component \eqn{a} alone.}
  \item{\code{Q2}}{Predictive Q2 per response column (PLS-R) or per class
    (PLS-DA), named accordingly:
    \deqn{Q2 = 1 - PRESS / TSS_Y,}
    where \eqn{PRESS = \sum_i (\hat{y}_i - y_i)^2} and
    \eqn{TSS_Y = \sum_i (y_i - \bar{y})^2}.
    When \code{cv.k >= 2}, \eqn{\hat{y}_i} are out-of-sample
    cross-validated predictions; otherwise training-set predictions are
    used (i.e. Q2 = R2Y for the full model).}
  \item{\code{DQ2}}{(PLS-DA only) Discriminant Q2 per class.  Only
    penalising residuals contribute to the sum:
    \deqn{DQ2 = 1 - PRESSD / TSS_Y,}
    where \eqn{PRESSD} sums \eqn{\hat{y}_i^2} for class-0 samples with
    \eqn{\hat{y}_i > 0}, and \eqn{(\hat{y}_i - 1)^2} for class-1 samples
    with \eqn{\hat{y}_i < 1}.  Same cross-validation logic as \code{Q2}.}
  \item{\code{Singular}}{Squared L2 norm of the NIPALS PLS score vector
    per component (\eqn{\|\mathbf{t}_a\|^2}), used to derive
    \code{R2X}.}
  \item{\code{VIP}}{Global VIP scores (named numeric vector, length
    \eqn{p_{tot}}) using the Wold formula:
    \deqn{VIP_j = \sqrt{p_{tot}
      \cdot \frac{\sum_a s_a \tilde{w}_{j,a}^2}{\sum_a s_a}},}
    where \eqn{s_a = \|\mathbf{t}_a\|^2 \|\mathbf{q}_a\|^2},
    \eqn{\tilde{w}_{j,a} = w_{j,a} / \|\mathbf{w}_a\|} is the
    L2-normalised \eqn{j}-th element of the \eqn{a}-th NIPALS weight
    vector, and \eqn{p_{tot}} is the total number of variables.}
  \item{\code{VIP.block}}{Named list (one \code{data.frame} per block)
    with columns \code{p} (per-block predictive VIP computed with block
    size \eqn{p_b} instead of \eqn{p_{tot}}) and \code{tot} (= \code{p}
    for PLS; included for consistency with OPLS output).  Row names are
    variable names.}
  \item{\code{PLS.model}}{List with: \code{W} (NIPALS X weight matrix,
    \eqn{p_{tot} \times ndim}); \code{B} (regression coefficients,
    \eqn{p_{tot} \times ncol(Y)},
    \eqn{\mathbf{B} =
    \mathbf{W}(\mathbf{P}'\mathbf{W})^{-1}\mathbf{Q}'},
    in original Y units); \code{B0} (intercept vector, length
    \eqn{ncol(Y)},
    \eqn{\mathbf{B}_0 = \bar{\mathbf{y}} - \bar{\mathbf{x}}\mathbf{B}});
    \code{Y} (original response matrix as supplied).
    Training-set Y predictions:
    \eqn{\hat{\mathbf{Y}} = \mathbf{X}\mathbf{B} + \mathbf{B}_0}.}
  \item{\code{cv}}{Cross-validation results when \code{cv.k >= 2} (empty
    list otherwise): \code{k} (number of folds), \code{fold}
    (sample-to-fold vector), \code{Ypred} (\eqn{n \times ncol(Y)} matrix
    of out-of-sample predictions), \code{Q2} (CV Q2 per class/response),
    \code{DQ2} (mean CV DQ2 across classes, PLS-DA only),
    \code{DQ2.perclass} (CV DQ2 per class, PLS-DA only).}
  \item{\code{Prediction}}{Training-set predictions: \code{Y.pred}
    (\eqn{n \times ncol(Y)}); for PLS-DA also \code{decisionRule},
    \code{trueClass} (character vector), \code{predClass} (data.frame),
    \code{Sensitivity} and \code{Specificity} (named per class),
    \code{confusionMatrix} (named list of 2x2 matrices, one per class).}
  \item{\code{Mean}}{List with \code{MeanMB} (column means per block),
    \code{MeanY} (column means of Y before any scaling), and
    \code{ScaleY} (column SDs of Y; all ones when \code{scale.y = FALSE}).}
  \item{\code{Norm}}{List with \code{NormMB}: Frobenius norms for block
    normalisation.}
  \item{\code{variable.block}}{Character vector (length \eqn{p_{tot}})
    mapping each row of \code{P.loadings} and each element of \code{VIP}
    to its block.}
  \item{\code{runtime}}{Total computation time in seconds.}
}
}
\description{
Finding common dimensions in multi-block datasets using PLS.
}
\examples{
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)
y <- scale(1:10, center = TRUE)
results.plsr <- ComDim_PLS(rw, y, 2, method = "PLS-R")
groups <- c(rep("A", 5), rep("B", 5))
results.plsda <- ComDim_PLS(rw, y = groups, 2, method = "PLS-DA")
}
\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}
}
