weighted_pls — Sample-weighted PLS

Group: Robust / weighted · Registry tolerance: 1e-08

Description

Sample-weighted PLS (sqrt(w)-prescaled NIPALS)

Registry note — sklearn PLSRegression on the sqrt(w)-prescaled centered data is mathematically equivalent to weighted PLS. Both sides default to NIPALS, matching to ~1e-12. SIMPLS is still available as an opt-in via cfg.solver = pls4all.Solver.SIMPLS.

Parameters

Name	Type	Default	Notes
X	—	required	current public binding signature
y	—	required	current public binding signature
sample_weights	—	None	current public binding signature
n_components	int	2	current public binding signature
center_x	bool | None	None	current public binding signature
scale_x	bool | None	None	current public binding signature
center_y	bool | None	None	current public binding signature
scale_y	bool | None	None	current public binding signature

Explanations

Bibliographic source

Martens, H. & Næs, T. (1989). Multivariate Calibration. Wiley. §4.5 ‘Weighted regression for non-i.i.d. errors’. Verified primary catalogue: https://search.worldcat.org/title/Multivariate-calibration/oclc/19847282.

Mathematical principle

Weighted PLS applies nonnegative row weights when estimating centres and the latent regression. This changes each observation’s contribution while retaining one global linear coefficient matrix.

Appropriate uses

Calibration with known nonnegative sample reliabilities, frequency weights, or deliberate regime reweighting.

Limits and validation

Weights change the estimand and require substantive justification; zero or extreme weights reduce effective sample size.

Implementation

The fit returns a replayable \(p\times q\) global coefficient matrix together with X and Y means, and the C API packs coefficients, means, and predictions for ordinary out-of-sample use. The historical statement that no global coefficient export is available is incorrect.

Sources and provenance

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

API and bindings

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

Python (verified public re-export):

from n4m.estimators.regression.robust import weighted_pls
result = weighted_pls(X, y)

Source signature: weighted_pls(X, y, *, sample_weights = None, n_components: int = 2, center_x: bool | None = None, scale_x: bool | None = None, center_y: bool | None = None, scale_y: bool | None = None) (n4m/_impl/native.py).

R (source-verified): weighted_pls(formula, data, ncomp = 2L, weights, na.action = stats::na.omit).

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

MATLAB / Octave (source-verified): weighted_pls(X, Y, n_components, sample_weights).

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

Registry parity references 📐

• 📐 ref.python_scikit_learn (python · python) — scikit-learn 1.4.2 · strict (rmse_rel ≤ 1e-08) — Weighted PLS computed via sklearn PLSRegression on the sqrt(w)-prescaled centered (X, Y). sklearn is the external PLS engine; the row-scaling is a standard preconditioning step that is mathematically equivalent to weighted PLS.

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-08).

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 4e-15	1.93 ms
Python · archived pls4all benchmark
pls4all.python	✓ bind	1.77 ms🏆
pls4all.sklearn	✓ 3e-13	1.92 ms
R · archived pls4all benchmark
pls4all.R	✓ 3e-13	4.57 ms
pls4all.R.formula	✓ 3e-13	5.88 ms
pls4all.R.mdatools	✓ 3e-13	5.95 ms
pls4all.R.pls	✓ 3e-13	5.23 ms
Python · external
📐ref.python_scikit_learn	source	2.12 ms

3 threads

Backend	Parity	200×50 (ms)
C++ native · libn4m
pls4all.cpp.blas+omp	✓ ref 4e-15	1.81 ms🏆
Python · archived pls4all benchmark
pls4all.python	✓ bind	1.87 ms
pls4all.sklearn	✓ 3e-13	1.84 ms
R · archived pls4all benchmark
pls4all.R	✓ 3e-13	5.06 ms
pls4all.R.formula	✓ 3e-13	5.37 ms
pls4all.R.mdatools	✓ 3e-13	5.52 ms
pls4all.R.pls	✓ 3e-13	6.02 ms
Python · external
📐ref.python_scikit_learn	source	2.23 ms

10 threads

Backend	Parity	200×50 (ms)
C++ native · libn4m
pls4all.cpp.blas+omp	✓ ref 4e-15	1.82 ms🏆
Python · archived pls4all benchmark
pls4all.python	✓ bind	1.91 ms
pls4all.sklearn	✓ 3e-13	1.91 ms
R · archived pls4all benchmark
pls4all.R	✓ 3e-13	4.82 ms
pls4all.R.formula	✓ 3e-13	5.68 ms
pls4all.R.mdatools	✓ 3e-13	5.35 ms
pls4all.R.pls	✓ 3e-13	6.10 ms
Python · external
📐ref.python_scikit_learn	source	2.18 ms

---

See also: benchmark overview · methods index · interactive dashboard