pls_cox — PLS-Cox (survival regression)

Group: Classification & GLM · Registry tolerance: 1e-06

Description

PLS-Cox (§5) — Cox PH on PLS scores

From the pls4all.sklearn.PLSCoxRegressor docstring:

PLS + Cox proportional-hazards regression on PLS scores.

Registry note — Bastien 2008 deviance-residual PLS-Cox (NumPy port): scale X, deviance residuals from a null Cox PH, NIPALS PLS, Breslow Cox NR on the scores. pls4all’s default wrapper calls the same routine, so the gate is bit-for-bit. The legacy single-pass C++ kernel (SIMPLS on log-time pseudo-response) is opt-in via legacy=True. R plsRcox::coxsplsDR is the published counterpart; see _PlsCoxRReference for the archived adapter.

Parameters

Name

Type

Default

Notes

n_components

int

2

Number of latent components extracted (k).

n_classes

int

2

registry benchmark cell value

Explanations

Bibliographic source

Bastien, P., Bertrand, F., Meyer, N. & Maumy-Bertrand, M. (2015). Deviance residuals-based sparse PLS and sparse kernel PLS regression for censored data. Bioinformatics 31(3), 397–404.

Mathematical principle

Cox proportional-hazards regression with PLS-based dimensionality reduction. The Cox model \(\lambda(t \mid \mathbf{x}) = \lambda_0(t)\exp(\mathbf{x}^{\top}\boldsymbol{\beta})\) is degenerate in \(p \gg n\) because the partial likelihood loses identifiability. PLS-Cox replaces the \(p\)-dimensional \(\boldsymbol{\beta}\) with a \(k\)-dimensional latent representation by extracting PLS scores from the deviance residuals of a null Cox model.

Required inputs are survival times and event indicators (0 = censored, 1 = event observed). The output is a fitted Cox model on the latent scores; risk scores for new samples are computed by first projecting them into the latent space and then evaluating \(\mathbf{t}^{\top}\boldsymbol{\beta}\).

This is the canonical method in high-dimensional biomarker survival studies (RNA-seq, MALDI-TOF) where a direct Cox model is infeasible.

Implementation

n4m_pls_cox_fit. Reference: R plsRcox 1.8.2.

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

pls4all.pls_cox  PLS-Cox proportional hazards (Breslow baseline hazard).
 survival_times: numeric vector of length size(X, 1).
 event_indicators: 0/1 integer vector of length size(X, 1).

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_pls_cox_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 pls_cox_fit
with pls4all.Context() as ctx, pls4all.Config() as cfg:
    res = pls_cox_fit(ctx, cfg, X, y, n_components=4, sample_weights=sample_w, y_labels=y_labels)
# then: res.matrix("predictions"), res.matrix("coefficients"),
# res.vector("mask"), res.scalar("intercept"), …

from pls4all.sklearn import PLSCoxRegressor
mdl = PLSCoxRegressor(n_components=2)
mdl.fit(X, y, sample_weight=sample_w)
y_hat = mdl.predict(X_test)

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

res = pls4all.pls_cox(X, y, 4);
% see header of bindings/matlab/+pls4all/pls_cox.m for full
% parameter surface:
%   res = pls_cox(X, n_components, survival_times, event_indicators)
yhat = predict(res, Xtest);

No idiomatic classdef wrapper — invoke pls4all.fit("pls_cox", X, y, …) directly from the unified MEX factory.

Registry parity references 📐

  • 📐 ref.python_numpy (python · python) — numpy in-tree · strict (rmse_rel ≤ 1e-06) — In-tree NumPy port of Bastien 2008 PLS-Cox (deviance residuals + NIPALS PLS + Breslow Cox PH). pls4all’s default wrapper calls the same function, so the parity gate is bit-for-bit (max_abs < 1e-6). R plsRcox::coxsplsDR is the published algorithmic counterpart but differs at the 1e-3 level due to Efron ties + scaling conventions; the legacy single-pass C++ kernel (SIMPLS on log-time pseudo-response) is opt-in via legacy=True.

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

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✓ ref1.79 ms
Python · pls4all
pls4all.python✓ bind1.75 ms🏆
pls4all.sklearn⇄ +2e+002.13 ms
R · pls4all
pls4all.R⇄ +2e+004.52 ms
pls4all.R.formula⇄ +2e+005.52 ms
pls4all.R.mdatools⇄ +2e+005.51 ms
pls4all.R.pls⇄ +2e+005.43 ms
Python · external
📐ref.python_numpysource2.03 ms
BackendParity200×30 (ms)
C++ native · libn4m
pls4all.cpp.blas+omp✓ ref1.92 ms
Python · pls4all
pls4all.python✓ bind1.97 ms
pls4all.sklearn⇄ +2e+001.45 ms🏆
R · pls4all
pls4all.R⇄ +2e+004.59 ms
pls4all.R.formula⇄ +2e+0020.3 ms
pls4all.R.mdatools⇄ +2e+0014.8 ms
pls4all.R.pls⇄ +2e+0014.0 ms
Python · external
📐ref.python_numpysource6.01 ms
BackendParity200×30 (ms)
C++ native · libn4m
pls4all.cpp.blas+omp✓ ref6.51 ms
Python · pls4all
pls4all.python✓ bind4.69 ms
pls4all.sklearn⇄ +2e+003.91 ms
R · pls4all
pls4all.R⇄ +2e+009.54 ms
pls4all.R.formula⇄ +2e+0017.4 ms
pls4all.R.mdatools⇄ +2e+0012.8 ms
pls4all.R.pls⇄ +2e+0017.2 ms
Python · external
📐ref.python_numpysource2.02 ms🏆

See also: benchmark overview · methods index · interactive dashboard