di_pls — Domain-Invariant PLS (di-PLS)

Group: Calibration transfer · Registry tolerance: 1e-06

Description

Domain-invariant PLS

Registry note — Python diPLSlib.models.DIPLS (B-Analytics; Nikzad-Langerodi 2018 authors). pls4all di_pls_fit defaults to the diPLSlib algorithm (centered NIPALS, convex-relaxation penalty, target-mean rescale) — bit-for-bit parity with DIPLS(centering=True, rescale='Target'). Set cfg.di_pls_legacy = 1 to fall back to the pre-0.97.4 SIMPLS direction projection.

Parameters

Name	Type	Default	Notes
X_source	—	required	current public binding signature
y_source	—	required	current public binding signature
X_target	—	required	current public binding signature
n_components	int	2	current public binding signature
di_lambda	float	1.0	current public binding signature

Explanations

Bibliographic source

Nikzad-Langerodi, R., Zellinger, W., Saminger-Platz, S. & Moser, B. A. (2018). Domain-invariant partial-least-squares regression. Analytical Chemistry 90(11), 6693–6701. Verified primary link: https://doi.org/10.1021/acs.analchem.8b00498.

Mathematical principle

Calibration transfer methods reconcile spectra acquired on different instruments or under different environmental conditions. di-PLS does this by augmenting the PLS objective with a domain-discrepancy penalty: \(\mathcal{L}(\mathbf{w}) = -\operatorname{Cov}(\mathbf{X}_s\mathbf{w}, \mathbf{y}_s)^2 + \lambda \,\mathrm{MMD}^2(\mathbf{X}_s\mathbf{w}, \mathbf{X}_t\mathbf{w})\), where \((\mathbf{X}_s, \mathbf{y}_s)\) is a labelled source domain, \(\mathbf{X}_t\) is an unlabelled target domain and MMD is the maximum mean discrepancy.

Minimising \(\mathcal{L}\) produces latent directions \(\mathbf{w}\) that simultaneously predict \(y\) in the source and have matched distributions across domains. The model is therefore robust to drift between calibration and prediction sets without requiring labels on the target domain.

Computational cost is dominated by the MMD term, which is \(O((n_s + n_t)^2)\) in a naive implementation; pls4all uses a linear-kernel MMD which reduces this to \(O((n_s + n_t) p)\).

\(\lambda\) controls the bias–transferability trade-off: \(\lambda = 0\) recovers vanilla PLS on the source, large \(\lambda\) shrinks toward a domain-aligned but potentially under-predictive model.

Appropriate uses

Adapting a linear calibration across labelled source and target domains with different predictor distributions.

Limits and validation

Domain-alignment penalties can remove predictive variation; target information and tuning must remain inside validation folds.

Implementation

n4m_domain_adaptation_di_pls_fit — requires X_target at fit time. Reference: Python diPLSlib.models.DIPLS (Nikzad-Langerodi authors). The pls4all variant matches diPLSlib’s rescale='Target' source-centred default.

Sources and provenance

Current implementation: cpp/src/core/extra_pls.cpp.

API and bindings

C ABI (ABI 2): n4m_domain_adaptation_di_pls_fit. Use the linked public header for the exact signature, configuration, and result handles.

Python (verified public re-export):

from n4m.domain_adaptation.invariant import di_pls

Source signature: di_pls(X_source, y_source, *, X_target, n_components: int = 2, di_lambda: float = 1.0) (n4m/_impl/native.py).

The scikit-learn-compatible n4m.domain_adaptation.invariant.DIPLS estimator accepts fit(X_source, y_source, X_target=X_target) and predicts fresh spectra from native input-space coefficients. The unlabeled target cohort contributes to training and must be chosen within each validation fold; it is not stored in the fitted estimator. Cross-language retraining therefore still requires the original target cohort.

R (source-verified): di_pls(formula, data, ncomp = 2L, X_target, di_lambda = 1.0, na.action = stats::na.omit).

The source signature has additional required inputs, so no example call is fabricated.

MATLAB / Octave (source-verified): di_pls(X_source, Y_source, n_components, X_target, di_lambda).

The source signature has additional required inputs, so no example call is fabricated.

Registry parity references 📐

• 📐 ref.python_diplslib (python · python) — diPLSlib 2.5.0 · strict (rmse_rel ≤ 1e-06) — Python diPLSlib.models.DIPLS (B-Analytics; Nikzad-Langerodi 2018 authors). Same di-PLS penalty applied during deflation; centering / target rescaling differ slightly, so tolerance is widened.

Benchmarks

Archived measurement identity. Backend labels in this table are the raw IDs recorded when the benchmark ran (including historical pls4all.* IDs). They preserve measurement provenance and do not describe a current public Python, R, or MATLAB binding; use the source-verified API and bindings section above for current entry points.

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 = archived binding-harness result 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-06).

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

1 thread

Backend	Parity	200×50 (ms)
C++ native · libn4m
pls4all.cpp.blas+omp	✓ ref 8e-15	2.58 ms🏆
Python · archived pls4all benchmark
pls4all.python	✓ bind	2.74 ms
pls4all.sklearn	✓ 4e-15	2.82 ms
R · archived pls4all benchmark
pls4all.R	✓ 6e-15	9.69 ms
pls4all.R.formula	✓ 6e-15	12.4 ms
pls4all.R.mdatools	✓ 6e-15	12.8 ms
pls4all.R.pls	✓ 6e-15	12.4 ms
Python · external
📐ref.python_diplslib	source	3.78 ms

3 threads

Backend	Parity	200×50 (ms)
C++ native · libn4m
pls4all.cpp.blas+omp	✓ ref 8e-15	2.80 ms
Python · archived pls4all benchmark
pls4all.python	✓ bind	2.70 ms🏆
pls4all.sklearn	✓ 4e-15	2.98 ms
R · archived pls4all benchmark
pls4all.R	✓ 6e-15	9.91 ms
pls4all.R.formula	✓ 6e-15	12.2 ms
pls4all.R.mdatools	✓ 6e-15	12.9 ms
pls4all.R.pls	✓ 6e-15	11.2 ms
Python · external
📐ref.python_diplslib	source	3.79 ms

10 threads

Backend	Parity	200×50 (ms)
C++ native · libn4m
pls4all.cpp.blas+omp	✓ ref 8e-15	2.74 ms🏆
Python · archived pls4all benchmark
pls4all.python	✓ bind	2.82 ms
pls4all.sklearn	✓ 4e-15	2.95 ms
R · archived pls4all benchmark
pls4all.R	✓ 6e-15	11.1 ms
pls4all.R.formula	✓ 6e-15	14.0 ms
pls4all.R.mdatools	✓ 6e-15	13.0 ms
pls4all.R.pls	✓ 6e-15	12.4 ms
Python · external
📐ref.python_diplslib	source	3.92 ms

---

See also: benchmark overview · methods index · interactive dashboard