Source code for pyts.multivariate.transformation._multivariate
"""Utility class for multivariate time series transformation."""
# Author: Johann Faouzi <johann.faouzi@gmail.com>
# License: BSD-3-Clause
from typing import Any, Self
import numpy as np
import numpy.typing as npt
from scipy.sparse import csr_matrix, hstack
from sklearn.base import BaseEstimator, clone
from sklearn.utils.validation import check_is_fitted
from pyts._base import MultivariateTransformerMixin, _SupportsFitTransform
from pyts.multivariate.utils import check_3d_array
from pyts.multivariate.utils._utils import _check_n_features
[docs]
class MultivariateTransformer(BaseEstimator, MultivariateTransformerMixin):
r"""Transformer for multivariate time series.
It provides a convenient class to transform multivariate time series with
transformers that can only deal with univariate time series.
Parameters
----------
estimator : estimator object or list thereof
Transformer. If one estimator is provided, it is cloned and each clone
transforms one feature. If a list of estimators is provided, each
estimator transforms one feature.
flatten : bool (default = True)
Affect shape of transform output. If True, ``transform``
returns an array with shape (n_samples, \*). If False, the output of
``transform`` from each estimator must have the same shape and
``transform`` returns an array with shape (n_samples, n_features, \*).
Ignored if the transformers return sparse matrices.
Attributes
----------
estimators_ : list of estimator objects
The collection of fitted transformers.
n_features_in_ : int
Number of features seen during ``fit``. ``transform`` requires the
same number of features.
Examples
--------
>>> from pyts.datasets import load_basic_motions
>>> from pyts.multivariate.transformation import MultivariateTransformer
>>> from pyts.image import GramianAngularField
>>> X, _, _, _ = load_basic_motions(return_X_y=True)
>>> transformer = MultivariateTransformer(GramianAngularField(),
... flatten=False)
>>> X_new = transformer.fit_transform(X)
>>> X_new.shape
(40, 6, 100, 100)
"""
[docs]
def __init__(
self,
estimator: _SupportsFitTransform | list[_SupportsFitTransform],
flatten: bool = True,
) -> None:
self.estimator = estimator
self.flatten = flatten
[docs]
def fit(self, X: npt.ArrayLike, y: npt.ArrayLike | None = None) -> Self:
"""Pass.
Parameters
----------
X : array-like, shape = (n_samples, n_features, n_timestamps)
Multivariate time series.
y : None or array-like, shape = (n_samples,) (default = None)
Class labels.
Returns
-------
self : object
"""
X = check_3d_array(X)
_, n_features, _ = X.shape
self._check_params(n_features)
for i, transformer in enumerate(self.estimators_):
transformer.fit(X[:, i, :], y)
self.n_features_in_ = n_features
return self
[docs]
def fit_transform( # pyrefly: ignore[bad-override]
self, X: npt.ArrayLike, y: npt.ArrayLike | None = None
) -> npt.NDArray[Any] | csr_matrix:
r"""Fit to data, then transform it.
Unlike most transformers, ``transform`` may return a sparse matrix
(when the wrapped per-feature transformers do), so this method is
overridden instead of relying on
``MultivariateTransformerMixin.fit_transform``, whose declared
return type is a plain array.
Parameters
----------
X : array-like, shape = (n_samples, n_features, n_timestamps)
Multivariate time series.
y : None or array-like, shape = (n_samples,) (default = None)
Class labels.
Returns
-------
X_new : array, shape = (n_samples, \*) or (n_samples, n_features, \*)
Transformed time series. May be a sparse matrix instead when
the wrapped per-feature transformers return one.
"""
return self.fit(X, y).transform(X)
[docs]
def transform(self, X: npt.ArrayLike) -> npt.NDArray[Any] | csr_matrix:
r"""Apply transform to each feature.
Parameters
----------
X : array-like, shape = (n_samples, n_features, n_timestamps)
Multivariate time series.
Returns
-------
X_new : array, shape = (n_samples, \*) or (n_samples, n_features, \*)
Transformed time series.
"""
X = check_3d_array(X)
n_samples, _, _ = X.shape
check_is_fitted(self, 'estimators_')
_check_n_features(X, self.n_features_in_)
X_transformed = [
transformer.transform(X[:, i, :])
for i, transformer in enumerate(self.estimators_)
]
all_sparse = np.all(
[
isinstance(X_transformed_i, csr_matrix)
for X_transformed_i in X_transformed
]
)
if all_sparse:
# ``hstack`` does not guarantee the ``csr_matrix`` format (its
# default output format depends on its inputs), so normalize
# explicitly to match the declared return type and the
# convention used by ``WEASELMUSE.transform``.
X_new = csr_matrix(hstack(X_transformed))
else:
X_new = [
self._convert_to_array(X_transformed_i)
for X_transformed_i in X_transformed
]
ndims = [X_new_i.ndim for X_new_i in X_new]
shapes = [X_new_i.shape for X_new_i in X_new]
one_dim = np.unique(ndims).size == 1
if one_dim:
one_shape = np.unique(shapes, axis=0).shape[0] == 1
else:
one_shape = False
if (not one_shape) or self.flatten:
X_new = [X_new_i.reshape(n_samples, -1) for X_new_i in X_new]
X_new = np.concatenate(X_new, axis=1)
else:
X_new = np.asarray(X_new)
axes = [1, 0] + [i for i in range(2, X_new.ndim)]
X_new = np.transpose(X_new, axes=axes)
return X_new
def _check_params(self, n_features: int) -> None:
"""Check parameters."""
if isinstance(self.estimator, BaseEstimator) and hasattr(
self.estimator, 'transform'
):
self.estimators_ = [clone(self.estimator) for _ in range(n_features)]
elif isinstance(self.estimator, list):
if len(self.estimator) != n_features:
raise ValueError(
"If 'estimator' is a list, its length must "
"be equal to the number of features "
f"({len(self.estimator)} != {n_features})"
)
# Clone each estimator so that the same instance listed several
# times is fitted independently on each feature, and so that the
# estimators passed by the user are left unfitted.
estimators = []
for i, estimator in enumerate(self.estimator):
if not (
isinstance(estimator, BaseEstimator)
and hasattr(estimator, 'transform')
):
raise ValueError(f"Estimator {i} must be a transformer.")
estimators.append(clone(estimator))
self.estimators_ = estimators
else:
raise TypeError(
"'estimator' must be a transformer that inherits from "
"sklearn.base.BaseEstimator or a list thereof."
)
@staticmethod
def _convert_to_array(
X: npt.NDArray[Any] | csr_matrix,
) -> npt.NDArray[Any]:
"""Convert the input data to an array if necessary."""
if isinstance(X, csr_matrix):
return X.toarray()
elif isinstance(X, np.ndarray):
return X
else:
raise ValueError(f'Unexpected type for X: {type(X).__name__}.')