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 :class:sklearn.cross_decomposition.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.	`"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.
`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_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.

Notes

Requested orthogonal components may be truncated with a :class:sklearn.exceptions.ConvergenceWarning when the enlarged preliminary subspace leaves no numerically resolvable block-specific residual variation. This is most common when n_components + max(n_x_orthogonal, n_y_orthogonal) approaches the rank or feature dimension of one block.

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 :meth:transform joint-score columns.

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.

score ¶

score(
    X: ArrayLike, y: ArrayLike, sample_weight=None
) -> float

Coefficient of determination R² of predict(X) against y.

Parameters:

Name	Type	Description	Default
`X`	`array-like of shape (n_samples, n_features)`	Test samples.	required
`y`	`array-like of shape (n_samples, n_targets)`	True values for X.	required
`sample_weight`	`array-like of shape (n_samples,)`	Sample weights.	`None`

Returns:

Name	Type	Description
`score`	`float`	R² of `self.predict(X)` wrt. `y`.