coco_pipe.io.transform ====================== .. py:module:: coco_pipe.io.transform .. autoapi-nested-parse:: coco_pipe/io/transform.py ------------------------- Stateful transformers compatible with DataContainer. Wraps scikit-learn transformers and implements M/EEG-specific whitening. This module provides classes that adhere to the Scikit-Learn Transformer API but operate natively on `DataContainer` objects, preserving metadata (IDs, coordinates) throughout the transformation pipeline. Attributes ---------- .. autoapisummary:: coco_pipe.io.transform.logger Classes ------- .. autoapisummary:: coco_pipe.io.transform.SklearnWrapper coco_pipe.io.transform.SpatialWhitener Functions --------- .. autoapisummary:: coco_pipe.io.transform._rebuild_container coco_pipe.io.transform._check_container Module Contents --------------- .. py:data:: logger .. py:function:: _rebuild_container(old_container: coco_pipe.io.structures.DataContainer, new_X: numpy.ndarray) -> coco_pipe.io.structures.DataContainer Helper to reconstruct DataContainer with new data and propagated metadata. .. py:function:: _check_container(container: coco_pipe.io.structures.DataContainer) Helper to validate input. .. py:class:: SklearnWrapper(transformer: sklearn.base.BaseEstimator) Bases: :py:obj:`sklearn.base.BaseEstimator`, :py:obj:`sklearn.base.TransformerMixin` Generic wrapper for ANY scikit-learn transformer (Scaler, PCA, etc.). This wrapper applies a standard scikit-learn transformer to the `.X` data matrix of a `DataContainer`, ensuring that the resulting container has correctly updated data while checking for dimension compatibility. :param transformer: An instantiated scikit-learn transformer (e.g., `StandardScaler()`, `PCA(n_components=10)`). :type transformer: BaseEstimator .. attribute:: estimator_ The fitted scikit-learn estimator. :type: BaseEstimator .. rubric:: Examples >>> from sklearn.preprocessing import RobustScaler >>> from coco_pipe.io import DataContainer, SklearnWrapper >>> import numpy as np >>> # Create formatted data (100 obs, 10 features) >>> X = np.random.randn(100, 10) >>> container = DataContainer(X, dims=('obs', 'feature')) >>> # Wrap a Scaler >>> scaler = SklearnWrapper(RobustScaler()) >>> scaled_container = scaler.fit_transform(container) >>> # Metadata is preserved >>> scaled_container.dims == container.dims True .. py:attribute:: transformer .. py:attribute:: estimator_ :value: None .. py:method:: fit(container: coco_pipe.io.structures.DataContainer, y=None) .. py:method:: transform(container: coco_pipe.io.structures.DataContainer) -> coco_pipe.io.structures.DataContainer .. py:method:: fit_transform(container: coco_pipe.io.structures.DataContainer, y=None) Fit to data, then transform it. Fits transformer to `X` and `y` with optional parameters `fit_params` and returns a transformed version of `X`. :param X: Input samples. :type X: array-like of shape (n_samples, n_features) :param y: Target values (None for unsupervised transformations). :type y: array-like of shape (n_samples,) or (n_samples, n_outputs), default=None :param \*\*fit_params: Additional fit parameters. :type \*\*fit_params: dict :returns: **X_new** -- Transformed array. :rtype: ndarray array of shape (n_samples, n_features_new) .. py:method:: inverse_transform(container: coco_pipe.io.structures.DataContainer) -> coco_pipe.io.structures.DataContainer .. py:class:: SpatialWhitener(method: str = 'pca', n_components: Optional[Union[int, float]] = None) Bases: :py:obj:`sklearn.base.BaseEstimator`, :py:obj:`sklearn.base.TransformerMixin` M/EEG Spatial Whitening using Covariance Decorrelation. This transformer removes spatial correlations between channels, effectively transforming the noise covariance matrix towards the identity matrix. It supports standard PCA, ZCA (Zero-phase Component Analysis which preserves topography), and robust shrinkage covariance estimation (OAS). It requires a dimension named 'channel' in the input `DataContainer`. The operation is performed spatially: :math:`X_{white} = X \cdot W^T` :param method: Shape of the transformation: - 'pca': Principal Component Analysis. Rotates data to principal axes and scales to unit variance. - 'zca': Zero-phase Component Analysis. Rotates, scales, and rotates back. Preserves spatial topography (sensors stay in place). - 'shrinkage': Uses Oracle Approximating Shrinkage (OAS) for robust covariance estimation in high dimensions. :type method: {'pca', 'zca', 'shrinkage'}, default='pca' :param n_components: Number of components to keep (only for 'pca'/'zca' methods). If None, all matches are kept. :type n_components: int or float, optional .. attribute:: whitener_ The estimated whitening matrix (W). Shape (n_components, n_channels). :type: np.ndarray .. attribute:: mean_ Per-channel mean vector. :type: np.ndarray .. attribute:: inverse_whitener_ The inverse matrix used to project back to sensor space. :type: np.ndarray .. rubric:: Examples >>> # Whitening EEG epochs (100 epochs, 64 channels, 500 times) >>> container = DataContainer( ... np.random.randn(100, 64, 500), dims=('obs', 'channel', 'time') ... ) >>> # Use Shrinkage for robust covariance >>> whitener = SpatialWhitener(method='shrinkage') >>> white_data = whitener.fit_transform(container) >>> # Project back to sensor space for plotting >>> sensor_data = whitener.inverse_transform(white_data) .. py:attribute:: method :value: 'pca' .. py:attribute:: n_components :value: None .. py:attribute:: whitener_ :value: None .. py:attribute:: mean_ :value: None .. py:attribute:: inverse_whitener_ :value: None .. py:method:: fit(container: coco_pipe.io.structures.DataContainer, y=None) .. py:method:: _fit_pca(X_flat: numpy.ndarray) .. py:method:: _fit_shrinkage(X_flat: numpy.ndarray) .. py:method:: transform(container: coco_pipe.io.structures.DataContainer) -> coco_pipe.io.structures.DataContainer .. py:method:: fit_transform(container: coco_pipe.io.structures.DataContainer, y=None) Fit to data, then transform it. Fits transformer to `X` and `y` with optional parameters `fit_params` and returns a transformed version of `X`. :param X: Input samples. :type X: array-like of shape (n_samples, n_features) :param y: Target values (None for unsupervised transformations). :type y: array-like of shape (n_samples,) or (n_samples, n_outputs), default=None :param \*\*fit_params: Additional fit parameters. :type \*\*fit_params: dict :returns: **X_new** -- Transformed array. :rtype: ndarray array of shape (n_samples, n_features_new) .. py:method:: inverse_transform(container: coco_pipe.io.structures.DataContainer) -> coco_pipe.io.structures.DataContainer .. py:method:: _apply_linear_op(container: coco_pipe.io.structures.DataContainer, W: numpy.ndarray, mean: Optional[numpy.ndarray]) -> numpy.ndarray