Skip to content

OPLS

Bases: RegressorMixin, TransformerMixin, BaseEstimator

Orthogonal Projections to Latent Structures regression.

Parameters:

Name Type Description Default
n_components int

Number of predictive PLS components fitted on the orthogonally filtered X block.

 1
n_orthogonal int

Number of X-orthogonal components removed before fitting the predictive PLS model. To choose this by cross-validated Q2, wrap OPLS in GridSearchCV over n_orthogonal.

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

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

 "none"
copy bool

Whether the input arrays are copied during validation. Note that copy=False is passed to sklearn input validation; OPLS filtering still allocates working arrays.

 True

Attributes:

Name Type Description
n_orthogonal_ int

Number of orthogonal components actually used.
x_ortho_weights_, x_ortho_loadings_, x_ortho_scores_ ndarray

Orthogonal weight/loading/score matrices.
x_weights_, x_loadings_, x_scores_, y_loadings_ ndarray

Predictive model parameters taken from the underlying PLS engine (in the preprocessed, orthogonal-filtered space).
coef_filtered_ ndarray

Coefficient matrix taken from the underlying PLS engine. Note: these coefficients act on the preprocessed, orthogonal-filtered space, and cannot be directly multiplied with raw input X. Use predict(X) for raw-input predictions.
coef_raw_ ndarray of shape (1, n_features)

Linear coefficients on the original raw input feature space, collapsing the scaling, orthogonal filter and predictive PLS into one linear map. predict(X) == (X @ coef_raw_.T + intercept_raw_).ravel() up to floating-point tolerance. (No sklearn coef_ alias is exposed.)
intercept_ float or ndarray

Intercept of the underlying PLS model for predictions from the preprocessed, orthogonal-filtered X block to the original y scale.
intercept_raw_ float or ndarray

Intercept paired with coef_raw_ for prediction from raw input X.
pls_ PLSRegression

The fitted predictive engine.
x_mean_, x_std_ ndarray

Centering/scaling vectors applied to X.
r2x_, r2x_ortho_, r2y_, rmse_ float

Training-set fit summaries. rmse_ is the uncorrected training root mean squared error (no degrees-of-freedom correction). r2x_ is computed from the predictive PLS scores/loadings on the filtered X block, relative to the preprocessed original X. r2x_ortho_ is computed from the removed orthogonal scores/loadings. These are diagnostic summaries, not a guaranteed exact additive partition; do not assume r2x_ + r2x_ortho_ equals total explained X variance. For cross-validated Q2 use cross_val_score.
r2x_components_ ndarray of shape (n_components,)

Per-component explained X sum-of-squares ratio of the predictive components, relative to the preprocessed X.
r2x_ortho_components_ ndarray of shape (n_orthogonal_,)

Per-component explained X sum-of-squares ratio of the removed orthogonal components.
r2y_components_ ndarray of shape (n_components,)

Per-component y sum-of-squares ratio explained through t_i @ q_i.T.
q_residuals_train_ ndarray of shape (n_samples,)

Training Q residuals in the full (predictive + orthogonal) reconstruction space; equals q_residuals(X_train, space="full").
q_residuals_predictive_train_ ndarray of shape (n_samples,)

Training Q residuals in the predictive-only reconstruction space.
x_residual_ss_ float

Sum of q_residuals_train_.
y_residual_ss_ float

Training residual sum of squares of y against the fitted predictions.
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.
vip_, ortho_vip_ ndarray of shape (n_features,)

Lazy predictive / orthogonal Variable Importance in Projection scores, computed on first access (sklearn feature_importances_ convention). For non-empty blocks with positive explained variance, each satisfies sum(vip**2) == n_features. Empty or degenerate blocks return zeros. For n_components > 1, predictive VIP aggregates across predictive PLS components. Use with SelectFromModel via importance_getter="vip_".
See Also

OPLSDA : Binary OPLS discriminant analysis built on this regressor. O2PLS : Two-block variant that also models Y-specific orthogonal structure. sklearn.cross_decomposition.PLSRegression : Predictive engine fitted after orthogonal filtering; OPLS(n_orthogonal=0) reduces to it exactly.

Notes

Classic OPLS uses n_components=1; n_orthogonal=0 reduces to ordinary PLSRegression, and n_components>1 is orthogonal-filtered multi-component PLS (interpret score plots / S-plots component-wise).

Constant and near-constant columns are retained rather than removed, preserving alignment with the input feature matrix, feature names, VIP arrays and coef_filtered_. To drop them, prepend VarianceThreshold in a Pipeline.

References

.. [1] 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 .. [2] Wold, S., Antti, H., Lindgren, F. & Ohman, J. (1998). Orthogonal signal correction of near-infrared spectra. Chemometrics and Intelligent Laboratory Systems, 44(1-2), 175-185. https://doi.org/10.1016/S0169-7439(98)00109-9 .. [3] Galindo-Prieto, B., Eriksson, L. & Trygg, J. (2014). Variable influence on projection (VIP) for OPLS models. Journal of Chemometrics, 28(8), 623-632. https://doi.org/10.1002/cem.2627

Examples:

>>> import numpy as np
>>> from scikit_opls import OPLS
>>> rng = np.random.default_rng(0)
>>> X = rng.normal(size=(20, 5))
>>> y = X[:, 0] - X[:, 1] + rng.normal(scale=0.1, size=20)
>>> model = OPLS(n_components=1, n_orthogonal=1).fit(X, y)
>>> model.transform(X).shape
(20, 1)
>>> model.predict(X).shape
(20,)

vip_ property 

vip_: NDArray[float64]

Predictive VIP per feature; ndarray (n_features,).

Standard PLS Variable Importance in Projection computed from the predictive model fitted on the orthogonally filtered X, normalised so sum(vip_**2) == n_features. Computed lazily on first access from the fitted weights. Defined in the style of Galindo-Prieto et al. (2014); not intended to reproduce ropls VIP values exactly.

ortho_vip_ property 

ortho_vip_: NDArray[float64]

Orthogonal VIP per feature; ndarray (n_features,).

Computed lazily on first access from the fitted weights.

fit 

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

Fit the OPLS model.

Parameters:

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

Training predictors.

 required
y array-like of shape (n_samples,)

Target values. Required: OPLS is a supervised transformer.

 required

Returns:

Name Type Description
self OPLS

The fitted estimator.

predict 

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

Predict y for new samples.

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,)

Predicted target values.

transform 

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

Project samples onto the predictive components.

Parameters:

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

Samples to project (orthogonal-filtered first, as at fit time).

 required

Returns:

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

Predictive scores.

transform_orthogonal 

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

Project samples onto the orthogonal components.

This is a non-standard method (outside the set_output contract).

Parameters:

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

Samples to project.

 required

Returns:

Name Type Description
x_ortho_scores ndarray of shape (n_samples, n_orthogonal_)

Orthogonal scores.

filter_transform 

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

Return X after preprocessing and orthogonal filtering.

This is the matrix actually passed to the predictive PLS engine, so self.pls_.predict(self.filter_transform(X)) matches self.predict(X) (up to output shape). The result is in the preprocessed, orthogonal-filtered space, not on the raw input scale. With n_orthogonal=0 it is just the preprocessed X.

Parameters:

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

Samples to preprocess and filter.

 required

Returns:

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

Preprocessed X with the fitted orthogonal variation removed.

get_feature_names_out 

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

Output feature names for the predictive scores.

transform reduces X to n_components predictive scores, so the output columns are components, not input features. They are named opls_pred0, opls_pred1, … (the ClassNamePrefixFeaturesOutMixin convention), independent of the input feature names. transform_orthogonal is outside the set_output contract and has no names here.

Parameters:

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

Input feature names; only validated for length against n_features_in_ (the output names do not depend on them).

 None

Returns:

Name Type Description
feature_names_out ndarray of str of shape (n_components,)

Names of the predictive-score columns.

score_distance 

score_distance(
    X: ArrayLike, *, kind: str = "predictive"
) -> NDArray[np.float64]

Return Hotelling-like score distances for samples.

Parameters:

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

Samples in the same raw feature space used for fitting. Pass raw X. Do not manually center or scale before calling diagnostics. The estimator applies its fitted preprocessing internally.

 required
kind ('predictive', 'orthogonal', 'all')

Which latent score space to use.

 "predictive"

Returns:

Name Type Description
distance ndarray of shape (n_samples,)

Squared Mahalanobis-like distance in the selected fitted score space.

q_residuals 

q_residuals(
    X: ArrayLike, *, space: str = "full"
) -> NDArray[np.float64]

Return Q residuals, i.e. squared X residual norm per sample.

Parameters:

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

Samples in raw feature space. Pass raw X. Do not manually center or scale before calling diagnostics. The estimator applies its fitted preprocessing internally.

 required
space ('full', 'predictive')

Which model reconstruction space to use:

  • "full" reconstructs scaled X from predictive + orthogonal structure.
  • "predictive" reconstructs scaled X from predictive PLS structure only, treating orthogonal variation as part of the residual.
 "full"

Returns:

Name Type Description
q ndarray of shape (n_samples,)

Squared residual norm per sample.