% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/stats_fit_opls.R
\name{opls}
\alias{opls}
\title{Fit an Orthogonal Partial Least Squares (O-PLS) model}
\usage{
opls(X, Y, scaling, validation_strategy)
}
\arguments{
\item{X}{Numeric matrix of predictors (rows = samples, columns = variables).}

\item{Y}{Numeric matrix or factor vector of responses.}

\item{scaling}{A scaling strategy object (e.g., \code{uv_scaling(center = TRUE)}),
specifying model-internal centering and/or scaling applied during fitting.
This does not modify the original spectral matrix.}

\item{validation_strategy}{A cross-validation strategy object defining how
resampling is performed (e.g., k-fold, Monte Carlo).}
}
\value{
An object of class \code{m8_model} containing the fitted O-PLS model,
cross-validation results, and performance statistics.
}
\description{
Fits a supervised Orthogonal Partial Least Squares (O-PLS) model
using a NIPALS-based algorithm with optional cross-validation and
automatic component selection.
}
\details{
O-PLS decomposes the predictor matrix into:
\itemize{
\item One predictive component capturing variation correlated with \code{Y}
\item Orthogonal components capturing structured variation in \code{X}
unrelated to \code{Y}
}

Predictive and orthogonal components are estimated sequentially.
Cross-validated performance metrics (e.g., Q², R², classification AUC)
are computed for each model configuration according to the supplied
\code{validation_strategy}.

The model extracts a single predictive component and iteratively
adds orthogonal components until the \code{stopRule} indicates
overfitting or \code{maxPCo} is reached.

Scaling specified via \code{scaling} is applied internally during model
fitting and does not alter the input matrix \code{X}. Spectral preprocessing
(e.g., alignment or baseline correction) should be performed prior to
model fitting.

The returned model object stores:
\itemize{
\item Predictive and orthogonal component models
\item Cross-validation results
\item Performance metrics (R², Q², AUC)
\item Model control parameters
\item Input data provenance metadata
\item Session information for reproducibility
}
}
\examples{
data(covid)

cv <- balanced_mc(k=5, split=2/3)
scaling <- uv_scaling(center=TRUE)
model <-opls(X=covid$X, Y=covid$an$type, scaling, cv)

show(model)
summary(model)

# scores
Tp <- scores(model)
To <- scores(model, orth=TRUE)

t2 <- hotellingsT2(cbind(Tp, To))
ell <-ellipse2d(t2)

plot(Tp, To, asp = 1,
  col = as.factor(covid$an$type),
  xlim = range(c(Tp, ell$x)),
  ylim = range(c(To, ell$y))
 )
lines(ell$x, ell$y, col = "grey", lty=2)

# loadings & vip's
Pp <- loadings(model)
Po <- loadings(model, orth=TRUE)
vips <- vip(model)

x=covid$ppm
y = Pp * apply(covid$X, 2, sd)

palette <-  colorRampPalette(c("blue", "cyan", "yellow", "red"))(100)
idx <- cut(vips, breaks = 100, labels = FALSE)
plot(x, y, type = "n", xlim = rev(range(x)), xlab='ppm', ylab='t_pred_sc')

for (i in seq_len(length(x) - 1)) {
  segments(x[i], y[i], x[i+1], y[i+1], col = palette[idx[i]], lwd = 2)
}

}
\seealso{
\code{\link{pls}}, \code{\link{uv_scaling}}

Other modelling: 
\code{\link{pca}()},
\code{\link{pls}()}
}
\concept{modelling}
