PLSRegression

class chemotools.regression.PLSRegression(n_components: int = 2, *, scale: bool = True, algorithm: int = 1, copy: bool = True, dtype: type = <class 'numpy.float64'>)

Bases: DocLinkMixin, PLS

PLS regression via Improved Kernel PLS with automatic explained variance.

This estimator wraps the fast, exact Improved Kernel PLS algorithms [1] from the ikpls package [2] in a scikit-learn-conformant regressor + transformer, and automatically calculates explained variance ratios for both X-space and Y-space after fitting, making it easy to use with diagnostic plots and following the same API as PCA.

Compared to sklearn.cross_decomposition.PLSRegression (NIPALS) [3] and [4], the Improved Kernel PLS algorithms are faster [5] while still being numerically stable [6]. Predictions and regression coefficients agree with NIPALS; individual weight/score/loading vectors are identical up to a per-component sign, which is arbitrary in PLS.

Additional capabilities inherited from ikpls:

• predict_all_components() returns predictions for every number of components 1..n_components in a single call (shape (n_components, n_samples, n_targets)), making component selection via (cross-)validation cheap.

• Fine-grained preprocessing on the backend: the ikpls model supports independent center_X / center_Y / scale_X / scale_Y and a configurable ddof. This wrapper exposes only a single scale flag (X and Y are always mean-centered) and fixes ddof = 1, to mirror the previous scikit-learn-backed PLSRegression. A maintainer can enable the independent flags or a different ddof on the inner model, but they change the fitted model and the explained-variance computation.

• Sample weights: the backend’s fit accepts sample_weight (when given, the inner X / Y means and standard deviations become their weighted variants). This wrapper does not expose sample_weight; whether to enable it is left to the maintainer.

Parameters:

• n_components (int, default=2) – Number of components to keep. Should be in [1, min(n_samples, n_features)].

• scale (bool, default=True) – Whether to scale X and Y to unit standard deviation before fitting. X and Y are always mean-centered, matching the previous scikit-learn-backed PLSRegression. Internally this maps onto the ikpls backend as center_X = center_Y = True and scale_X = scale_Y = scale.

• algorithm (int, default=1) – Improved Kernel PLS algorithm to use, either 1 or 2. Algorithm 1 uses X directly, while algorithm 2 builds X.T @ X and is typically faster for tall matrices (many more samples than features). Both algorithms give the same results.

• copy (bool, default=True) – Whether to copy X and Y in fit before applying centering and potentially scaling.

• dtype (type, default=numpy.float64) – Floating point dtype used for the computations.

Variables:

• explained_x_variance_ratio (ndarray of shape (n_components,)) – Fraction of the total preprocessed training X sum of squares explained by each component (not cumulative). See Notes for the calculation and numerical caveats.

• explained_y_variance_ratio (ndarray of shape (n_components,)) – Fraction of the total preprocessed training Y sum of squares explained by each component (not cumulative). For multiple targets, sums of squares are aggregated across all targets. These ratios describe training-data variance, not predictive performance on unseen data. See Notes for the calculation and numerical caveats.

• x_scores (ndarray of shape (n_samples, n_components)) – The training X-scores T (the projection of the preprocessed training X onto x_rotations_), equal to transform(X) on the training data. (There is no y_scores_ attribute; the Y-scores are available on demand via transform(X, y) – see transform() for the caveat on how they relate to scikit-learn.)

• y_weights_, (All other fitted attributes (x_weights_,)

• y_rotations_, (x_loadings_, y_loadings_, x_rotations_,)

• are (coef_, intercept_, n_features_in_, feature_names_in_))

• the (inherited unchanged from the ikpls backend (ikpls.sklearn.PLS); see)

• (https (ikpls documentation)

• definitions.

References

[1]

Dayal, B. S., & MacGregor, J. F. (1997). Improved PLS algorithms. Journal of Chemometrics, 11(1), 73-85. https://doi.org/10.1002/(SICI)1099-128X(199701)11:1%3C73::AID-CEM435%3E3.0.CO;2-%23

[2]

Engstrøm, O.-C. G., Dreier, E. S., Jespersen, B. M., & Pedersen, K. S. (2024). IKPLS: Improved Kernel Partial Least Squares and Fast Cross-Validation Algorithms for Python with CPU and GPU Implementations Using NumPy and JAX. Journal of Open Source Software, 9(99), 6533. https://doi.org/10.21105/joss.06533

[3]

sklearn.cross_decomposition.PLSRegression https://scikit-learn.org/stable/modules/generated/sklearn.cross_decomposition.PLSRegression.html

[4] (1,2)

Wegelin, J. A. (2000). A Survey of Partial Least Squares (PLS) Methods, with Emphasis on the Two-Block Case. Technical Report No. 371, Department of Statistics, University of Washington, Seattle, WA

[5]

Alin, A. (2009). Comparison of PLS algorithms when number of objects is much larger than number of variables. Statistical Papers, 50, 711-720. https://doi.org/10.1007/s00362-009-0251-7

[6]

Andersson, M. (2009). A comparison of nine PLS1 algorithms. Journal of Chemometrics, 23(10), 518-529. https://doi.org/10.1002/cem.1248

[7] (1,2)

Abdi, H. (2003). Partial Least Squares (PLS) Regression. In Lewis-Beck M., Bryman A., Futing T. (Eds.), Encyclopedia of Social Sciences Research Methods. Thousand Oaks (CA): Sage.

Examples

Basic usage with automatic variance calculation

>>> from chemotools.regression import PLSRegression
>>> import numpy as np
>>>
>>> # Generate sample data
>>> X = np.random.randn(100, 50)
>>> y = X[:, 0] + 2*X[:, 1] + np.random.randn(100)*0.1
>>>
>>> # Fit model
>>> pls = PLSRegression(n_components=5)
>>> pls.fit(X, y)
>>>
>>> # Variance ratios are automatically available!
>>> print(
...     f"LV1 explains {pls.explained_y_variance_ratio_[0]*100:.1f}%"
... )
>>> print(f"Total Y variance: {pls.explained_y_variance_ratio_.sum()*100:.1f}%")
>>>
>>> # Predictions for ALL component counts 1..5 in a single call
>>> all_predictions = pls.predict_all_components(X)
>>>
>>> # Use with plotting
>>> from chemotools.plotting import ExplainedVariancePlot
>>> plot = ExplainedVariancePlot(pls.explained_y_variance_ratio_)
>>> plot.show()

Notes

Variance Calculation:

Component sums of squares are computed directly from squared X-score and loading norms [7]. Both X and Y contributions use X-scores, consistent with regression-mode PLS.

Let t_a, p_a, and q_a be column a of x_scores_, x_loadings_, and y_loadings_, respectively. Let X_c and Y_c denote the training blocks after applying the fitted means and, when scale=True, the fitted standard deviations (ddof=1). Then:

explained_x_variance_ratio_[a] = sum(t_a**2) * sum(p_a**2) / sum(X_c**2)
explained_y_variance_ratio_[a] = sum(t_a**2) * sum(q_a**2) / sum(Y_c**2)

Each sum is over all elements of its vector or matrix. Thus the denominators are the total sums of squares of the preprocessed blocks, not the residual sums of squares after earlier components.

• For orthogonal fitted X-scores, these contributions equal the reduction in residual sum of squares from sequential PLS deflation, up to numerical precision [4] [7]. No explicit deflation is performed here.

• X ratios sum to approximately 1 when the fitted components reconstruct the preprocessed X block. Y ratios do not need to sum to 1: variation in Y that the X-scores cannot explain remains in the residual.

• The same calculation is used for both algorithms. Ratios are non-negative for finite fitted scores and loadings and positive total variance. There is no explicit rank thresholding, clipping, or renormalization; components near or beyond numerical rank depend on the backend’s numerical behavior.

• A block with zero total variance has undefined ratios (NaN).

Differences from the previous scikit-learn (NIPALS) backend:

• The NIPALS-specific max_iter and tol parameters do not exist: Improved Kernel PLS is an exact, non-iterative solver.

• The single scale parameter is retained with the same meaning (X and Y are always mean-centered, and scale toggles unit-variance scaling of both). The ikpls backend’s independent center_X / center_Y / scale_X / scale_Y are not exposed here.

• Score/weight/loading vectors may differ from NIPALS by a per-component sign; predictions, coefficients, and explained variances are unaffected.

See also

sklearn.cross_decomposition.PLSRegression

scikit-learn’s NIPALS-based PLS.

chemotools.plotting.ExplainedVariancePlot

Visualization for explained variance.

Attributes

center_X
center_Y
ddof
scale_X
scale_Y
y_rotations_	The rotations mapping Y directly to its scores.

property center_X: bool

property center_Y: bool

property scale_X: bool

property scale_Y: bool

property ddof: int

fit(X: ndarray, y: ndarray) → PLSRegression

Fit model to data and compute explained variance ratios.

This method extends ikpls.sklearn.PLS.fit by storing the training X-scores and calculating explained variance ratios. See the Notes section of PLSRegression for calculation details.

Parameters:

• X (array-like of shape (n_samples, n_features)) – Training vectors. Accepts numpy arrays, pandas DataFrames.

• y (array-like of shape (n_samples,) or (n_samples, n_targets)) – Target vectors. Accepts 1D (univariate) or 2D (multivariate) targets.

Returns:

self – Fitted estimator with populated variance attributes: explained_x_variance_ratio_ and explained_y_variance_ratio_.

Return type:

PLSRegression

fit_transform(X: ndarray, y: ndarray) → Tuple[ndarray, ndarray]

Learn and apply the dimension reduction on the training data.

Fits and returns the (x_scores, y_scores) tuple, matching sklearn.cross_decomposition.PLSRegression.fit_transform. Unlike the ikpls backend’s fit_transform, this wrapper does not accept sample_weight (it is intentionally not exposed; see the class docstring).

Parameters:

• X (array-like of shape (n_samples, n_features)) – Training vectors.

• y (array-like of shape (n_samples,) or (n_samples, n_targets)) – Target vectors.

Returns:

(x_scores, y_scores) – The training X-scores and Y-scores.

Return type:

tuple of ndarray

transform(X, y=None)

Project X (and optionally Y) onto the latent components.

Returns the X-scores; when y is given, also returns the Y-scores as an (x_scores, y_scores) tuple, matching sklearn.cross_decomposition.PLSRegression.transform.

Note on the Y-scores: the returned Y-scores are the projection of the preprocessed Y onto y_rotations_ – the same quantity scikit-learn’s transform(X, y) returns, but not the classic NIPALS u vectors (which scikit-learn stores in its y_scores_ attribute). In regression-mode PLS, Y is deflated by the X-scores, so u depends on X and is not recoverable as any linear projection of Y; the rotation projection and u coincide only under canonical deflation (PLSCanonical). This class therefore does not expose a y_scores_ attribute.

Parameters:

• X (array-like of shape (n_samples, n_features)) – Predictor variables to project.

• y (array-like of shape (n_samples,) or (n_samples, n_targets), optional) – Response variables to project. If given, Y-scores are also returned.

Returns:

• x_scores (ndarray of shape (n_samples, n_components)) – Returned when y is None.

• (x_scores, y_scores) (tuple of ndarray) – Returned when y is given.

set_fit_request() → PLSRegression

No-op.

Calling this method has no effect.

Returns:

self – The updated object.

Return type:

object

set_score_request(*, sample_weight: bool | None | str = '$UNCHANGED$') → PLSRegression

Configure whether metadata should be requested to be passed to the score method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

• True: metadata is requested, and passed to score if provided. The request is ignored if metadata is not provided.

• False: metadata is not requested and the meta-estimator will not pass it to score.

• None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.

• str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters:

sample_weight (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for sample_weight parameter in score.

Returns:

self – The updated object.

Return type:

object