pls: Partial Least Squares with selectable model family and...

In fastPLS: Fast Partial Least Squares for High-Dimensional Data

Partial Least Squares with selectable model family and backend

Description

Fits PLS-SVD, a SIMPLS-family estimator, OPLS, or kernel PLS models for regression or classification using a selected CPU, CUDA, or operation-split Apple Metal backend. The fitted model can include predictions for held-out samples, latent scores, fitted values, variance summaries, and optional classification heads.

Usage

pls(
  Xtrain,
  Ytrain,
  Xtest = NULL,
  Ytest = NULL,
  ncomp = 2,
  scaling = c("centering", "autoscaling", "none"),
  method = c("simpls", "plssvd", "opls", "kernelpls"),
  classifier = c("lda", "argmax"),
  fit = FALSE,
  bycol = FALSE,
  return_variance = TRUE,
  return_loadings = FALSE,
  proj = FALSE,
  perm.test = FALSE,
  times = 100,
  backend = NULL,
  n.cores = NULL,
  north = 1L,
  kernel = c("linear", "rbf", "poly"),
  gamma = NULL,
  degree = 3L,
  coef0 = 1,
  ...
)

Arguments

Xtrain	Numeric training predictor matrix or a float::float32 predictor matrix for the supported float32 route.
Ytrain	Training response. Use a numeric vector/matrix for regression or factor/character class labels for classification.
Xtest	Optional test predictor matrix.
Ytest	Optional test response for independent-test Q2Y, whose denominator uses the training-response mean. Classification labels may contain classes absent from the training data; such classes cannot be predicted and count as classification errors.
ncomp	Positive integer component count or vector of counts. Repeated values are removed. When a direct PLS-LDA fit reaches its numerical rank, all requested positions are retained and positions beyond that rank repeat the last estimable prediction and discriminant scores. The fitted object reports both requested and effective component counts.
scaling	One of centering, autoscaling, or none.
method	One of simpls, plssvd, opls, or kernelpls. simpls uses the fastPLS accelerated SIMPLS-family core. Bounded-block execution is approximate and is not classical de Jong SIMPLS.
classifier	Classification decision rule. The default lda fits a regularized linear discriminant analysis classifier on the PLS latent scores. argmax selects the class with the largest PLS-DA response score.
fit	Return fitted values, training scores, and R2Y when TRUE. The default FALSE keeps only the compact state required for prediction and avoids materializing training-only outputs.
bycol	For matrix-valued regression responses, calculate response-wise metrics in metrics. The default FALSE returns only aggregate metrics.
return_variance	Compute predictor-space latent-variable variance explained. Set to FALSE for timing/memory benchmarks that do not need plotting variance metadata.
return_loadings	Compute and store predictor loadings P. The default is FALSE because most prediction workflows only need the projection weights and response-side coefficients.
proj	Return projected Ttest when TRUE.
perm.test	Run a single-split permutation test when Xtest and Ytest are supplied. Because pls() has no grouping argument, the exchangeability unit is one training row. Training rows are permuted, the model is refitted with the same randomized-solver seed, and the permuted test-set Q2Y path is compared with the observed path.
times	Number of requested permutations. For each component, pls() returns (b + 1) / (B + 1), where b is the number of successful null fits with Q2Y at least as large as observed and B is the number of successful null fits. Failed fits are excluded from B and reported.
backend	Implementation backend: cpu for compiled CPU, cuda for CUDA-native fitting, or metal for operation-split float32 CPU/Metal fitting on Apple silicon. When omitted, options(backend = ...) defines the session default. Selecting unavailable CUDA or Metal support raises an error without a CPU fallback.
n.cores	Number of CPU cores requested for supported BLAS/OpenMP host operations. An explicit value takes precedence over options(n.cores = ...). CUDA and Metal device parallelism is managed by their native runtimes; n.cores applies only to their host-side stages.
north	Number of orthogonal components removed by OPLS. The predictive count ncomp must fit within the predictor rank remaining after filtering. Direct PLS-LDA fits retain larger requested positions by repeating the last estimable result; other OPLS routes reject an unavailable predictive direction. Orthogonal components are not counted as predictive components.
kernel	Kernel type for kernel PLS: linear, rbf, or poly.
gamma	Kernel scale. Defaults internally to 1 / ncol(Xtrain).
degree	Polynomial kernel degree.
coef0	Polynomial kernel offset.
...	Optional SVD tuning controls forwarded to the selected backend. Use the same compact names documented in fastsvd(), such as oversample, power, and seed.

Details

The CPU backend uses Apple Accelerate on macOS, prefers OpenBLAS when available on Linux and Windows, and otherwise uses the numerical libraries supplied by R. Use fastPLS_blas() to report the library chosen at compilation. options(n.cores = n) requests CPU threads when supported by that library; additional threads are not guaranteed to improve every fit.

Base R numeric matrices use float64. Supplying float::float32 predictors or numeric responses requests float32 execution without silent promotion. CUDA supports float32 and float64. The Apple Metal route requires float32 and divides work between CPU code and persistent Metal workspaces. Unsupported backend and precision combinations stop rather than silently falling back to CPU.

method = "simpls" selects the fastPLS SIMPLS-family estimator. Its component-wise route retains the classical sequential orthogonalization and deflation structure. An eligible route may instead consume a bounded block of candidates computed from one deflated state; this is an approximate SIMPLS-family estimator, not classical de Jong SIMPLS. Classification can use response-score argmax or LDA on latent scores. PLS-SVD classification cannot return more than one fewer component than the number of response classes. The requested model family is never silently replaced by another family.

All public PLS routes use randomized SVD. It is an approximate solver, and diagnostics records the effective controls and structural checks for the fitted route. Compare repeated seeds or an independent high-accuracy fit when results are close to a decision boundary or the data are strongly ill-conditioned. Explicit oversample, power, and seed values supplied through ... override the automatic controls.

LDA uses a regularized pooled within-class covariance calculation with Cholesky solves. Regularization increases through a fixed internal sequence only when factorization fails and is not user-tuned.

Value

A fastPLS object. The object is a list whose fields depend on the selected method, backend, classifier, and whether test data or optional summaries were requested. metrics is a list of complete evaluate() results, organized as metrics$fitted and metrics$test, with one element per requested component count. Common fields are:

• P: predictor loadings, with one column per latent component when return_loadings = TRUE; otherwise an empty matrix is returned.

• Q: response loadings or response-side latent coefficients.

• R: predictor weights/rotations used to project new samples into the PLS latent space.

• Ttrain: training latent scores when fit = TRUE. With fit = FALSE, classification routes retain only the compact state needed for prediction or LDA fitting and do not return the full training-score matrix. Compiled cross-validation continues to return its documented score outputs.

• C_latent, W_latent: low-rank latent prediction factors used by PLS-SVD-style compact prediction when a full coefficient array is avoided.

• B: regression coefficient matrix or coefficient array, when stored. For vector-valued ncomp, a three-dimensional array may contain the coefficient path for all requested component counts.

• mX, vX: training predictor centering and scaling values. vX is one when no scaling is applied.

• mY: response centering values for regression or dummy-coded PLS-DA.

• lev: factor levels used for classification.

• Yfit: fitted training responses or fitted class labels, returned when fit = TRUE.

• R2Y: training-set coefficient of determination path when fit = TRUE; otherwise NA placeholders may be returned for compatibility. Elements are named by component count, for example "ncomp=2". For PLS-DA this is a dummy-response quantity, not classification accuracy.

• requested_ncomp: component positions requested by the caller. For rank-limited PLS-LDA fits, every position is retained in fitted and predicted outputs.

• effective_ncomp: number of estimable response-associated directions used for each requested component prefix. Rank-limited PLS-LDA paths repeat the last estimable prediction and discriminant scores. If a regression response is constant, this is zero; fitted and new-data predictions then equal the training-response mean, coefficients are zero, and R2Y is NA.

• Ypred: predictions for Xtest, returned only when Xtest is supplied to pls(). For classification this contains predicted factor labels; for regression it contains numeric predictions.

• Ypred_index: integer class indices for classification predictions, when available.

• Ttest: test-set latent scores, returned when proj = TRUE.

• Q2Y: independent-test Q2 whose denominator centers each response on its corresponding training-response mean before aggregating sums of squares. For factor Ytest, this is dummy-response PLS-DA Q2 relative to training class proportions, not classification accuracy. It is returned when response scores are available. Elements are named by component count.

• accuracy: decoded-label accuracy for factor Ytest, returned when classification predictions are available. Elements are named by component count.

• metrics: complete evaluate() outputs. definitions records the exact R2Y and Q2Y denominator conventions. fitted evaluates Yfit against Ytrain; test evaluates Ypred against Ytest. For multivariate regression, response-wise metrics are included only when bycol = TRUE. metrics$permutation stores permutation metrics and p-values when perm.test = TRUE.

• pval: corrected Monte Carlo permutation-test p-values by component, returned when perm.test = TRUE.

• permutation: long-format permutation table, returned when perm.test = TRUE, with observed and permuted R2/Q2 values and the permutation correlation used by plot.permutation().

• permutation_unit, permutation_group_sizes_preserved, permutation_class_frequencies_preserved, permutation_folds, permutation_solver_seed, permutation_requested, permutation_completed, permutation_failed, and permutation_errors: the permutation contract and null-fit audit.

• variance, variance_explained, cumulative_variance_explained, variance_total, variance_basis: predictor-space variance summaries returned when return_variance = TRUE.

• x_variance, x_variance_explained, x_cumulative_variance_explained, x_variance_total: aliases of the predictor-space variance summaries.

• inner_model: fitted inner PLS model used by OPLS.

• W_orth, P_orth, north, opls_engine, xprod_mode, gpu_resident: OPLS-specific orthogonal-component and backend metadata.

• kernel, kernel_engine, kernel_linear_direct: kernelPLS-specific kernel settings and execution metadata.

• diagnostics: numerical solver diagnostics. For rSVD this records the structural-check status, finiteness, requested and effective component counts and randomized controls. A route that invokes the case-audited CPU decomposition also records its residual audit, strengthened retries, and any deterministic recovery; other routes state explicitly that a case audit is unavailable. Panel evidence is reported separately and is not interpreted as general-use certification. SIMPLS-family fits also record whether the active approximate route uses a component-wise oversampled sketch or an eligible CPU/CUDA/Metal candidate block, together with the active execution optimizations.

Function settings and backend bookkeeping, such as the component grid and resolved classifier backend, are retained internally for prediction and plotting but are not shown as public output fields.

Examples

X <- as.matrix(mtcars[, c("disp", "hp", "wt", "qsec")])
y <- mtcars$mpg
fit <- pls(X, y,
    ncomp = 2, method = "simpls", backend = "cpu",
    return_variance = FALSE
)
head(predict(fit, X)$Ypred)

fastPLS documentation built on Sept. 29, 2026, 1:06 a.m.