Skip to content

O2PLS

Bases: RegressorMixin, TransformerMixin, BaseEstimator

Two-block Orthogonal Projections to Latent Structures regression.

O2PLS decomposes two preprocessed blocks into joint X-Y covariation, X-specific orthogonal structure, Y-specific orthogonal structure, and residual variation. Unlike PLSRegression, this implementation uses the Trygg-Wold orthonormal joint-loading convention: x_joint_loadings_ equals x_joint_weights_ and y_joint_loadings_ equals y_joint_weights_ for the final joint part.

Parameters:

Name Type Description Default
n_components int

Number of final joint O2PLS components.

 1
n_x_orthogonal int

Number of X-specific orthogonal components to remove.

 0
n_y_orthogonal int

Number of Y-specific orthogonal components to remove. For univariate Y, v1 requires this to be zero because there is no multivariate Y-feature subspace for a stable Y-specific direction.

 0
scale ('none', 'center', 'pareto', 'standard')

Column preprocessing applied to both X and Y blocks. Note: unlike the boolean scale parameter of PLSRegression, this is a string mode; passing True/False raises an error.

 "none"
copy bool

Whether input arrays are copied during validation. Filtering still allocates working arrays.

 True

Attributes:

Name Type Description
x_joint_weights_, y_joint_weights_ ndarray

Final orthonormal joint weights fitted on the filtered blocks.
x_joint_loadings_, y_joint_loadings_ ndarray

Copies of the final joint weights under the O2PLS orthonormal-loading convention.
x_joint_scores_, y_joint_scores_ ndarray

Final joint scores on the filtered training blocks.
x_orthogonal_weights_, x_orthogonal_scores_, x_orthogonal_loadings_ ndarray

Sequential X-specific orthogonal components.
y_orthogonal_weights_, y_orthogonal_scores_, y_orthogonal_loadings_ ndarray

Sequential Y-specific orthogonal components.
b_t_ ndarray of shape (n_components_, n_components_)

Regression matrix mapping joint X scores to joint Y scores (used by predict).
b_u_ ndarray of shape (n_components_, n_components_)

Regression matrix mapping joint Y scores to joint X scores (used by predict_x).
coef_filtered_ ndarray of shape (n_features_in_, n_targets_)

Coefficient matrix mapping scaled, X-orthogonally-filtered X to scaled predicted Y. This orientation is intentionally (n_features, n_targets) and no raw-space coef_ alias is exposed in v1.
x_filtered_, y_filtered_ ndarray

Preprocessed training blocks after orthogonal filtering, shapes (n_samples, n_features) and (n_samples, n_targets_). Note: together with the residual blocks these training-set diagnostics make the fitted (and pickled) estimator scale with the training data size.
x_residuals_, y_residuals_ ndarray

Training residual blocks after removing joint and orthogonal structure, same shapes as x_filtered_/y_filtered_.
x_mean_, x_std_, y_mean_, y_std_ ndarray

Centering/scaling vectors for each block.
r2x_, r2y_, r2x_ortho_, r2y_ortho_ float

Training-set diagnostic sum-of-squares ratios on preprocessed blocks. These are not guaranteed additive variance partitions.
singular_values_initial_, singular_values_final_ ndarray

Singular values of the X'Y covariance block before and after orthogonal filtering.
n_components_, n_x_orthogonal_, n_y_orthogonal_ int

Numbers of joint / X-orthogonal / Y-orthogonal components actually fitted; may be lower than requested after truncation.
n_targets_ int

Number of target columns seen during fit.
n_features_out_ int

Number of joint-score columns returned by transform.
n_features_in_ int

Number of features seen during fit.
feature_names_in_ ndarray of shape (n_features_in_,)

Names of features seen during fit. Defined only when X has feature names that are all strings.
See Also

OPLS : Single-block variant removing only X-orthogonal structure. OPLSDA : Binary OPLS discriminant analysis. sklearn.cross_decomposition.PLSCanonical : Symmetric two-block decomposition without an integral orthogonal-signal-correction filter.

Notes

Requested orthogonal components may be truncated with a ConvergenceWarning when the preliminary joint subspace leaves no numerically resolvable block-specific residual variation. This is most common when n_components approaches the rank or feature dimension of one block.

References

.. [1] Trygg, J. & Wold, S. (2003). O2-PLS, a two-block (X-Y) latent variable regression (LVR) method with an integral OSC filter. Journal of Chemometrics, 17(1), 53-64. https://doi.org/10.1002/cem.775 .. [2] Trygg, J. & Wold, S. (2002). Orthogonal projections to latent structures (O-PLS). Journal of Chemometrics, 16(3), 119-128. https://doi.org/10.1002/cem.695

Examples:

>>> import numpy as np
>>> from scikit_opls import O2PLS
>>> rng = np.random.default_rng(0)
>>> T = rng.normal(size=(30, 2))
>>> X = T @ rng.normal(size=(2, 6)) + 0.1 * rng.normal(size=(30, 6))
>>> Y = T @ rng.normal(size=(2, 4)) + 0.1 * rng.normal(size=(30, 4))
>>> model = O2PLS(n_components=2, n_x_orthogonal=1).fit(X, Y)
>>> model.transform(X).shape
(30, 2)
>>> model.predict(X).shape
(30, 4)

fit 

fit(X: ArrayLike, y: ArrayLike) -> O2PLS

Fit the O2PLS model.

Parameters:

Name Type Description Default
X array-like of shape (n_samples, n_features)

Training vectors, where n_samples is the number of samples and n_features is the number of predictors.

 required
y array-like of shape (n_samples, n_targets)

Target vectors, where n_samples is the number of samples and n_targets is the number of response variables.

 required

Returns:

Name Type Description
self object

Fitted estimator.

predict 

predict(X: ArrayLike) -> NDArray[np.float64]

Predict Y from X, reconstructing only the joint Y structure.

Parameters:

Name Type Description Default
X array-like of shape (n_samples, n_features)

Samples to predict.

 required

Returns:

Name Type Description
y_pred ndarray of shape (n_samples, n_targets)

Predicted values reconstructed from the joint X structure.

predict_x 

predict_x(Y: ArrayLike) -> NDArray[np.float64]

Predict X from Y, reconstructing only the joint X structure.

Parameters:

Name Type Description Default
Y array-like of shape (n_samples, n_targets)

Target samples.

 required

Returns:

Name Type Description
x_pred ndarray of shape (n_samples, n_features)

Predicted X values reconstructed from the joint Y structure.

transform 

transform(X: ArrayLike) -> NDArray[np.float64]

Return X-side joint scores after replaying the fitted X-orthogonal filter.

Parameters:

Name Type Description Default
X array-like of shape (n_samples, n_features)

Samples to transform.

 required

Returns:

Name Type Description
X_scores ndarray of shape (n_samples, n_components)

Joint X scores on the filtered blocks.

transform_y 

transform_y(Y: ArrayLike) -> NDArray[np.float64]

Return Y-side joint scores after replaying the fitted Y-orthogonal filter.

Parameters:

Name Type Description Default
Y array-like of shape (n_samples, n_targets)

Targets to transform.

 required

Returns:

Name Type Description
Y_scores ndarray of shape (n_samples, n_components)

Joint Y scores on the filtered blocks.

transform_pair 

transform_pair(
    X: ArrayLike, Y: ArrayLike
) -> tuple[NDArray[np.float64], NDArray[np.float64]]

Return (transform(X), transform_y(Y)).

Parameters:

Name Type Description Default
X array-like of shape (n_samples, n_features)

Samples to transform.

 required
Y array-like of shape (n_samples, n_targets)

Targets to transform.

 required

Returns:

Name Type Description
X_scores ndarray of shape (n_samples, n_components)

Joint X scores on the filtered blocks.
Y_scores ndarray of shape (n_samples, n_components)

Joint Y scores on the filtered blocks.

transform_orthogonal_x 

transform_orthogonal_x(X: ArrayLike) -> NDArray[np.float64]

Return sequential X-specific orthogonal scores.

Parameters:

Name Type Description Default
X array-like of shape (n_samples, n_features)

Samples to transform.

 required

Returns:

Name Type Description
X_orth_scores ndarray of shape (n_samples, n_x_orthogonal)

Orthogonal X scores.

transform_orthogonal_y 

transform_orthogonal_y(Y: ArrayLike) -> NDArray[np.float64]

Return sequential Y-specific orthogonal scores.

Parameters:

Name Type Description Default
Y array-like of shape (n_samples, n_targets)

Targets to transform.

 required

Returns:

Name Type Description
Y_orth_scores ndarray of shape (n_samples, n_y_orthogonal)

Orthogonal Y scores.

filter_transform_x 

filter_transform_x(X: ArrayLike) -> NDArray[np.float64]

Return preprocessed X after the fitted X-orthogonal filter.

Parameters:

Name Type Description Default
X array-like of shape (n_samples, n_features)

Samples to filter.

 required

Returns:

Name Type Description
X_filtered ndarray of shape (n_samples, n_features)

Filtered X block.

filter_transform_y 

filter_transform_y(Y: ArrayLike) -> NDArray[np.float64]

Return preprocessed Y after the fitted Y-orthogonal filter.

Parameters:

Name Type Description Default
Y array-like of shape (n_samples, n_targets)

Targets to filter.

 required

Returns:

Name Type Description
Y_filtered ndarray of shape (n_samples, n_targets)

Filtered Y block.

get_feature_names_out 

get_feature_names_out(
    input_features=None,
) -> NDArray[np.object_]

Output names for the joint-score columns.

These are the columns returned by transform.

Parameters:

Name Type Description Default
input_features array-like of str or None

Input features.

 None

Returns:

Name Type Description
feature_names_out ndarray of str objects

Transformed feature names.