% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ortho_projection.R
\name{ortho_projection}
\alias{ortho_projection}
\alias{predict.ortho_projection}
\alias{plot.ortho_projection}
\title{Orthogonal projections}
\usage{
ortho_projection(
  Xr, Xu = NULL, Yr = NULL,
  ncomp = ncomp_by_var(0.01),
  method = c("pca", "pca_nipals", "pls", "mpls", "simpls"),
  center = TRUE,
  scale = FALSE,
  tol = 1e-6,
  max_iter = 1000L,
  pc_selection = deprecated(),
  ...
)

\method{predict}{ortho_projection}(object, newdata, ...)

\method{plot}{ortho_projection}(x, col = "#3B82F6", ...)

\method{predict}{ortho_projection}(object, newdata, ...)
}
\arguments{
\item{Xr}{A numeric matrix of reference observations (rows) and variables
(columns).}

\item{Xu}{An optional matrix of additional observations to project.}

\item{Yr}{An optional response matrix. Required for PLS methods
(\code{"pls"}, \code{"mpls"}, \code{"simpls"}) and when using
\code{\link{ncomp_by_opc}()}.}

\item{ncomp}{Component selection method. Either:
\itemize{
\item A positive integer (equivalent to \code{ncomp_fixed(n)})
\item An \code{ncomp_selection} object: \code{\link{ncomp_by_var}()},
\code{\link{ncomp_by_cumvar}()}, \code{\link{ncomp_by_opc}()}, or
\code{\link{ncomp_fixed}()}
}
Default is \code{ncomp_by_var(0.01)}.}

\item{method}{A character string specifying the projection method:
\itemize{
\item \code{"pca"}: PCA via singular value decomposition (default)
\item \code{"pca_nipals"}: PCA via NIPALS algorithm
\item \code{"pls"}: PLS via NIPALS algorithm
\item \code{"mpls"}: Modified PLS via NIPALS (Shenk and Westerhaus, 1991)
\item \code{"simpls"}: PLS via SIMPLS algorithm (de Jong, 1993)
}}

\item{center}{A logical indicating whether to center the data. Default is
\code{TRUE}. PLS methods always center internally regardless of this
setting.}

\item{scale}{A logical indicating whether to scale the data to unit
variance. Default is \code{FALSE}.}

\item{tol}{Convergence tolerance for the NIPALS algorithm. Default is
\code{1e-6}. Ignored when \code{method = "simpls"}.}

\item{max_iter}{Maximum number of iterations for NIPALS. Default is
\code{1000}. Ignored when \code{method = "simpls"}.}

\item{pc_selection}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{ncomp} instead.}

\item{...}{Additional arguments (currently unused).}

\item{object}{Object of class \code{"ortho_projection"}.}

\item{newdata}{Matrix of new observations to project.}

\item{x}{An object of class \code{ortho_projection} (as returned by
\code{\link{ortho_projection}}).}

\item{col}{Color for the plot elements. Default is \code{"#3B82F6"}.}
}
\value{
An object of class \code{"ortho_projection"} containing:
\itemize{
\item \code{scores}: Matrix of projected scores for \code{Xr} (and \code{Xu}).
\item \code{X_loadings}: Matrix of X loadings.
\item \code{Y_loadings}: Matrix of Y loadings (PLS only).
\item \code{weights}: Matrix of PLS weights (PLS only).
\item \code{projection_mat}: Projection matrix for new data (PLS only).
\item \code{variance}: List with original and explained variance.
\item \code{scores_sd}: Standard deviation of scores.
\item \code{ncomp}: Number of components retained.
\item \code{center}: Centering vector used.
\item \code{scale}: Scaling vector used.
\item \code{method}: Projection method used.
\item \code{ncomp_method}: The value passed to the \code{ncomp} argument.
\item \code{opc_evaluation}: opc optimization results (if applicable).
}
}
\description{
\loadmathjax
Performs orthogonal projections of high-dimensional data matrices using
principal component analysis (PCA) or partial least squares (PLS).
}
\details{
\subsection{PCA methods}{

When \code{method = "pca"}, singular value decomposition factorizes the
data matrix \mjeqn{X}{X} as:

\mjdeqn{X = UDV^{T}}{X = UDV^T}

where \mjeqn{U}{U} and \mjeqn{V}{V} are orthogonal matrices (left and right
singular vectors), and \mjeqn{D}{D} is a diagonal matrix of singular values.
The score matrix is \mjeqn{UD}{UD} and the loadings are \mjeqn{V}{V}.

When \code{method = "pca_nipals"}, the non-linear iterative partial least
squares (NIPALS) algorithm is used instead.
}

\subsection{PLS methods}{

Three PLS variants are available:

\itemize{
\item \code{"pls"}: Standard PLS using the NIPALS algorithm with
covariance-based weights.
\item \code{"mpls"}: Modified PLS using the NIPALS algorithm with
correlation-based weights, giving equal influence to all predictors
regardless of variance (Shenk and Westerhaus, 1991).
\item \code{"simpls"}: SIMPLS algorithm (de Jong, 1993), which deflates
the cross-product matrix rather than X itself. Computationally faster
than NIPALS, especially for wide matrices.
}
}

\subsection{Component selection}{

When \code{\link{ncomp_by_opc}()} is used, component selection minimizes
RMSD (for continuous \code{Yr}) or maximizes kappa (for categorical
\code{Yr}) between observations and their nearest neighbors. See
\code{\link{diss_evaluate}}.
}
}
\examples{
\donttest{
library(prospectr)
data(NIRsoil)

# Preprocess
sg_det <- savitzkyGolay(
  detrend(NIRsoil$spc, wav = as.numeric(colnames(NIRsoil$spc))),
  m = 1, p = 1, w = 7
)

# Split data
train_x <- sg_det[NIRsoil$train == 1 & !is.na(NIRsoil$CEC), ]
train_y <- NIRsoil$CEC[NIRsoil$train == 1 & !is.na(NIRsoil$CEC)]
test_x <- sg_det[NIRsoil$train == 0 & !is.na(NIRsoil$CEC), ]

# PCA with fixed components
proj <- ortho_projection(train_x, ncomp = 5)

plot(proj)

# PCA with variance-based selection
proj <- ortho_projection(train_x, ncomp = ncomp_by_var(0.01))

# PCA with OPC optimization
proj <- ortho_projection(train_x, Xu = test_x, Yr = train_y,
                         ncomp = ncomp_by_opc(40))

#' plot(proj)

# PLS projection (NIPALS)
proj <- ortho_projection(train_x, Xu = test_x, Yr = train_y,
                         method = "pls", ncomp = ncomp_by_opc(40))

# Modified PLS
proj <- ortho_projection(train_x, Yr = train_y,
                         method = "mpls", ncomp = 10)

# SIMPLS (faster for wide matrices)
proj <- ortho_projection(train_x, Yr = train_y,
                         method = "simpls", ncomp = 10)
}
}
\references{
de Jong, S. 1993. SIMPLS: An alternative approach to partial least squares
regression. Chemometrics and Intelligent Laboratory Systems 18:251-263.

Martens, H. 1991. Multivariate calibration. John Wiley & Sons.

Ramirez-Lopez, L., Behrens, T., Schmidt, K., Stevens, A., Dematte, J.A.M.,
Scholten, T. 2013a. The spectrum-based learner: A new local approach for
modeling soil vis-NIR spectra of complex data sets. Geoderma 195-196:268-279.

Ramirez-Lopez, L., Behrens, T., Schmidt, K., Viscarra Rossel, R., Dematte,
J.A.M., Scholten, T. 2013b. Distance and similarity-search metrics for use
with soil vis-NIR spectra. Geoderma 199:43-53.

Shenk, J.S., Westerhaus, M.O. 1991. Populations structuring of near
infrared spectra and modified partial least squares regression. Crop
Science 31:1548-1555.
}
\seealso{
\code{\link{ncomp_by_var}}, \code{\link{ncomp_by_opc}},
\code{\link{diss_evaluate}}, \code{\link{mbl}}
}
\author{
\href{https://orcid.org/0000-0002-5369-5120}{Leonardo Ramirez-Lopez}
}
