o2pls — O2-PLS (two-way orthogonal)

Group: Multi-block / cross-modal · Registry tolerance: 1e-10

Description

O2PLS — bi-directional OPLS (Trygg & Wold 2003)

From the pls4all.sklearn.O2PLSRegression docstring:

O2-PLS (bi-directional OPLS, Trygg & Wold 2003).

Registry note — R OmicsPLS::o2m 2.1.0 (Bouhaddani 2018) joint-SVD O2PLS. pls4all defaults to the OmicsPLS::o2m algorithm and matches R bit-for-bit (~1e-13 max_abs). The pre-0.97 peel-then-PLS path (Trygg & Wold 2003 §3.2 power-iteration recipe) is reachable via the legacy=True adapter kwarg / cfg.solver = NIPALS.

Parameters

Name

Type

Default

Notes

n_predictive

int

2

Number of joint (predictive) components shared by X and Y in O2-PLS.

n_x_orthogonal

int

1

Number of X-orthogonal components (Y-irrelevant structure in X).

n_y_orthogonal

int

1

Number of Y-orthogonal components (X-irrelevant structure in Y).

n_targets

int

4

registry benchmark cell value

Explanations

Bibliographic source

Trygg, J. & Wold, S. (2003). O2-PLS, a two-block (X–Y) latent variable regression method with an integral OSC filter. Journal of Chemometrics 17(1), 53–64.

Mathematical principle

O2-PLS extends OPLS symmetrically to both \(\mathbf{X}\) and \(\mathbf{Y}\): it decomposes each block into a joint predictive component plus block-orthogonal components. Unlike OPLS, which is asymmetric (\(\mathbf{Y}\) drives the decomposition of \(\mathbf{X}\)), O2-PLS treats both matrices as observation blocks of equal status.

Required hyperparameters: \(n_{\mathrm{pred}}\) (joint components), \(n_{\mathrm{X,ortho}}\) (X-unique orthogonal), \(n_{\mathrm{Y,ortho}}\) (Y-unique orthogonal). Choosing all three by cross-validation is a 3-D grid which can be expensive; a common compromise fixes the orthogonal counts at 1 and tunes only \(n_{\mathrm{pred}}\).

O2-PLS is dominant in metabolomics ↔ transcriptomics integration where the analyst wants to disentangle platform-specific orthogonal variation from biology that is consistent across platforms.

Implementation

n4m_o2pls_fit. Reference: CRAN OmicsPLS 2.1.0.

MATLAB header (bindings/matlab/+pls4all/O2plsRegression.m):

pls4all.O2plsRegression  O2-PLS (bi-directional OPLS).

Usage

Every pls4all binding tab dispatches into the same C kernel; the external libraries listed at the bottom of the page are the parity references registered in benchmarks.parity_timing.registry. Switch tabs to read the same fit in your language. The R package now ships drop-in-compatible facades for the CRAN pls package (plsr, pcr, mvr) and for the mdatools::pls(x, y, ...) matrix idiom — those tabs appear only on the methods that have a meaningful equivalence.

pls4all bindings

/* C ABI — libn4m */
n4m_context_t* ctx = n4m_context_create();
n4m_config_t*  cfg = n4m_config_create();
n4m_method_result_t* res = NULL;
n4m_o2pls_fit(ctx, cfg, &x_view, &y_view, /* hyperparams */, &res);
/* … read coefficients / mask / scores via */
/* n4m_method_result_get_double_matrix / vector / scalar … */
n4m_method_result_destroy(res);
n4m_config_destroy(cfg);
n4m_context_destroy(ctx);

import pls4all
from pls4all._methods import o2pls_fit
with pls4all.Context() as ctx, pls4all.Config() as cfg:
    res = o2pls_fit(ctx, cfg, X, y)
# then: res.matrix("predictions"), res.matrix("coefficients"),
# res.vector("mask"), res.scalar("intercept"), …

from pls4all.sklearn import O2PLSRegression
mdl = O2PLSRegression(n_predictive=2, n_x_orthogonal=1, n_y_orthogonal=1)
mdl.fit(X, y)
y_hat = mdl.predict(X_test)

library(pls4all)
# Unified low-level dispatcher (May 2026 R cleanup):
res <- pls4all_method("o2pls", X, y,
                      n_components = 2L, params = list(n_targets = 4L, n_predictive = 2L, n_x_orthogonal = 1L, n_y_orthogonal = 1L))
# res is a named list with MethodResult arrays/scalars.
# selected_indices / top_k_intervals are 1-based.

res = pls4all.o2pls(X, y, 2);
% see header of bindings/matlab/+pls4all/o2pls.m for full
% parameter surface:
%   res = o2pls(X, Y, n_predictive, n_x_orthogonal, n_y_orthogonal)
yhat = predict(res, Xtest);

mdl  = pls4all.fit("o2pls", X, y, "NumComponents", 2);
yhat = predict(mdl, Xtest);

Registry parity references 📐

  • 📐 ref.r_omicspls (R · r) — OmicsPLS 2.1.0 · strict (rmse_rel ≤ 1e-10) — R OmicsPLS::o2m (Bouhaddani 2018), joint-SVD O2PLS. pls4all’s default O2PLS path now matches this algorithm bit-for-bit (max_abs ~1e-13 on the parity sizes); the legacy peel-then-PLS implementation is opt-in.

Benchmarks

Adaptive wall-clock per cell measured against full_matrix.csv. Only backends that implement this method are listed; libraries without the method are omitted.

Verdict  ·  ✓ ref / ≈ ref / ~ shape mark a reference-gate pass at strict / relaxed / qualitative tolerance  ·  ✓ bind = pls4all binding agrees with the C++ baseline  ·  ⇄ cross-check = documented by-design selector/RNG/model, noncanonical API/facade convention, or secondary oracle  ·  ✗ divergent  ·  ⚠ error  ·  — not run. The fastest backend per column is marked 🏆.

Reference gate: strict — numeric equivalence (rmse_rel_tol ≤ 1e-10).

Rows tagged with 📐 are the canonical parity references for this method (declared in parity_timing.registry). C++ and external rows show reference parity; pls4all language bindings show binding parity against the C++ backend. Hover the icon for role and tolerance band.

BackendParity200×30 (ms)
C++ native · libn4m
pls4all.cpp.blas+omp✓ ref 4e-101.21 ms
Python · pls4all
pls4all.python✓ bind1.19 ms🏆
pls4all.sklearn✓ 9e-161.37 ms
R · pls4all
pls4all.R✓ bind2.69 ms
pls4all.R.formula✓ bind3.44 ms
pls4all.R.mdatools✓ bind3.42 ms
pls4all.R.pls✓ bind3.58 ms
R · external
📐ref.r_omicsplssource7.21 ms
BackendParity200×30 (ms)
C++ native · libn4m
pls4all.cpp.blas+omp✓ ref 4e-101.22 ms🏆
Python · pls4all
pls4all.python✓ bind1.24 ms
pls4all.sklearn✓ 9e-161.44 ms
R · pls4all
pls4all.R✓ bind2.78 ms
pls4all.R.formula✓ bind3.52 ms
pls4all.R.mdatools✓ bind3.53 ms
pls4all.R.pls✓ bind3.68 ms
R · external
📐ref.r_omicsplssource7.41 ms
BackendParity200×30 (ms)
C++ native · libn4m
pls4all.cpp.blas+omp✓ ref 4e-101.24 ms🏆
Python · pls4all
pls4all.python✓ bind2.09 ms
pls4all.sklearn✓ 9e-161.45 ms
R · pls4all
pls4all.R✓ bind3.09 ms
pls4all.R.formula✓ bind3.52 ms
pls4all.R.mdatools✓ bind3.49 ms
pls4all.R.pls✓ bind3.25 ms
R · external
📐ref.r_omicsplssource7.31 ms

See also: benchmark overview · methods index · interactive dashboard