coco_pipe.io.transform#

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 ~coco_pipe.io.DataContainer objects, preserving metadata (IDs, coordinates) throughout the transformation pipeline.

Attributes#

logger

Classes#

SklearnWrapper

Generic wrapper for ANY scikit-learn transformer (Scaler, PCA, etc.).

SpatialWhitener

M/EEG Spatial Whitening using Covariance Decorrelation.

Module Contents#

coco_pipe.io.transform.logger#
class coco_pipe.io.transform.SklearnWrapper(transformer)#

Bases: sklearn.base.BaseEstimator, 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 ~coco_pipe.io.DataContainer, ensuring that the resulting container has correctly updated data while checking for dimension compatibility.

Parameters:

transformer (BaseEstimator) – An instantiated scikit-learn transformer (e.g., StandardScaler(), PCA(n_components=10)).

Variables:

estimator (BaseEstimator) – The fitted scikit-learn estimator.

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
transformer#
estimator_ = None#
fit(container, y=None)#
Parameters:

container (coco_pipe.io.structures.DataContainer)

transform(container)#
Parameters:

container (coco_pipe.io.structures.DataContainer)

Return type:

coco_pipe.io.structures.DataContainer

fit_transform(container, y=None)#

Fit the wrapped estimator and transform the data.

Parameters:

  • container (DataContainer) – Input data to transform.

  • y (array-like, optional) – Target values.

Returns:

Transformed data with the same dimensions.

Return type:

DataContainer

inverse_transform(container)#
Parameters:

container (coco_pipe.io.structures.DataContainer)

Return type:

coco_pipe.io.structures.DataContainer

class coco_pipe.io.transform.SpatialWhitener(method='pca', n_components=None)#

Bases: sklearn.base.BaseEstimator, 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 ~coco_pipe.io.DataContainer. The operation is performed spatially: \(X_{white} = X \cdot W^T\)

Parameters:

  • method ({'pca', 'zca', 'shrinkage'}, default='pca') –

    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.

  • n_components (int or float, optional) – Number of components to keep (only for ‘pca’/’zca’ methods). If None, all matches are kept.

Variables:

  • whitener (np.ndarray) – The estimated whitening matrix (W). Shape (n_dims, n_channels).

  • mean (np.ndarray) – Per-channel mean vector.

  • inverse_whitener (np.ndarray) – The inverse matrix used to project back to sensor space.

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)
method = 'pca'#
n_components = None#
whitener_ = None#
mean_ = None#
inverse_whitener_ = None#
fit(container, y=None)#
Parameters:

container (coco_pipe.io.structures.DataContainer)

transform(container)#
Parameters:

container (coco_pipe.io.structures.DataContainer)

Return type:

coco_pipe.io.structures.DataContainer

fit_transform(container, y=None)#

Fit the whitener to the data and then transform it.

Parameters:

  • container (DataContainer) – Input data to transform. Must contain a ‘channel’ dimension.

  • y (array-like, optional) – Target values (ignored for unsupervised transformation).

Returns:

Transformed data with the same dimensions.

Return type:

DataContainer

inverse_transform(container)#
Parameters:

container (coco_pipe.io.structures.DataContainer)

Return type:

coco_pipe.io.structures.DataContainer