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 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.

Functions¶

`_rebuild_container`(→ coco_pipe.io.structures.DataContainer)	Helper to reconstruct DataContainer with new data and propagated metadata.
`_check_container`(container)	Helper to validate input.

Module Contents¶

coco_pipe.io.transform.logger¶

coco_pipe.io.transform._rebuild_container(old_container: coco_pipe.io.structures.DataContainer, new_X: numpy.ndarray) → coco_pipe.io.structures.DataContainer[source]¶: Helper to reconstruct DataContainer with new data and propagated metadata.

coco_pipe.io.transform._check_container(container: coco_pipe.io.structures.DataContainer)[source]¶: Helper to validate input.

class coco_pipe.io.transform.SklearnWrapper(transformer: sklearn.base.BaseEstimator)[source]¶

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

estimator_¶

The fitted scikit-learn estimator.

Type:: BaseEstimator

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: coco_pipe.io.structures.DataContainer, y=None)[source]¶

transform(container: coco_pipe.io.structures.DataContainer) → coco_pipe.io.structures.DataContainer[source]¶

fit_transform(container: coco_pipe.io.structures.DataContainer, y=None)[source]¶

Fit to data, then transform it.

Fits transformer to X and y with optional parameters fit_params and returns a transformed version of X.

Parameters:

X (array-like of shape (n_samples, n_features)) – Input samples.
y (array-like of shape (n_samples,) or (n_samples, n_outputs), default=None) – Target values (None for unsupervised transformations).
**fit_params (dict) – Additional fit parameters.

Returns:

X_new – Transformed array.

Return type:

ndarray array of shape (n_samples, n_features_new)

inverse_transform(container: coco_pipe.io.structures.DataContainer) → coco_pipe.io.structures.DataContainer[source]¶

class coco_pipe.io.transform.SpatialWhitener(method: str = 'pca', n_components: int | float | None = None)[source]¶

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 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.

whitener_¶

The estimated whitening matrix (W). Shape (n_components, n_channels).

Type:: np.ndarray

mean_¶

Per-channel mean vector.

Type:: np.ndarray

inverse_whitener_¶

The inverse matrix used to project back to sensor space.

Type:: np.ndarray

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: coco_pipe.io.structures.DataContainer, y=None)[source]¶

_fit_pca(X_flat: numpy.ndarray)[source]¶

_fit_shrinkage(X_flat: numpy.ndarray)[source]¶

transform(container: coco_pipe.io.structures.DataContainer) → coco_pipe.io.structures.DataContainer[source]¶

fit_transform(container: coco_pipe.io.structures.DataContainer, y=None)[source]¶

Fit to data, then transform it.

Fits transformer to X and y with optional parameters fit_params and returns a transformed version of X.

Parameters:

X (array-like of shape (n_samples, n_features)) – Input samples.
y (array-like of shape (n_samples,) or (n_samples, n_outputs), default=None) – Target values (None for unsupervised transformations).
**fit_params (dict) – Additional fit parameters.

Returns:

X_new – Transformed array.

Return type:

ndarray array of shape (n_samples, n_features_new)

inverse_transform(container: coco_pipe.io.structures.DataContainer) → coco_pipe.io.structures.DataContainer[source]¶

_apply_linear_op(container: coco_pipe.io.structures.DataContainer, W: numpy.ndarray, mean: numpy.ndarray | None) → numpy.ndarray[source]¶