coco_pipe.dim_reduction.reducers.spatiotemporal

Spatiotemporal dimensionality reduction reducers.

This module provides reducers for structured signals where time, trials, or snapshots are part of the data layout. These reducers follow the shared BaseReducer contract while declaring nonstandard input layouts through the capabilities mapping.

Classes

DMDReducer

Dynamic Mode Decomposition wrapper based on pydmd.DMD.

TRCAReducer

Task-Related Component Analysis wrapper based on meegkit.trca.TRCA.

References

[1]

Schmid, P. J. (2010). “Dynamic mode decomposition of numerical and experimental data”. Journal of Fluid Mechanics, 656, 5-28.

[2]

PyDMD documentation: https://github.com/mathLab/PyDMD

[3]

Nakanishi, M., Wang, Y., Chen, X., Wang, Y.-T., Gao, X., and Jung, T.-P. (2018). “Enhancing detection of SSVEPs for a high-speed brain speller using task-related component analysis”. IEEE Transactions on Biomedical Engineering, 65(1), 104-112.

[4]

MEEGkit documentation: https://github.com/nbara/python-meegkit

Author: Hamza Abdelhedi (hamza.abdelhedi@umontreal.ca)

Classes

DMDReducer	Dynamic Mode Decomposition reducer.
TRCAReducer	Task-Related Component Analysis reducer.

Module Contents

class coco_pipe.dim_reduction.reducers.spatiotemporal.DMDReducer(n_components: int = 0, force_transpose: bool = False, **kwargs)

Bases: coco_pipe.dim_reduction.reducers.base.BaseReducer

Dynamic Mode Decomposition reducer.

DMD decomposes a snapshot matrix into dynamic modes that capture coherent spatial patterns and their temporal evolution. It is useful for spatiotemporal systems such as fluid flows, simulation outputs, and structured neural trajectories when data are arranged as (n_features, n_snapshots).

Parameters:

• n_components (int, default=0) – Number of modes to keep. This is forwarded to PyDMD as svd_rank. A value of 0 keeps all modes.

• force_transpose (bool, default=False) – If True, transpose incoming arrays from (n_snapshots, n_features) to (n_features, n_snapshots) before fitting and transforming.

• **kwargs (dict) – Additional keyword arguments forwarded to pydmd.DMD after signature filtering. Common options include tlsq_rank, exact, and opt.

model

Fitted DMD estimator after fit.

Type:

pydmd.DMD or None

Notes

Unlike most reducers in this package, DMD expects columns to represent time snapshots. This is declared through capabilities[“input_layout”] = “features_snapshots”.

See also

TRCAReducer

Trial-structured spatiotemporal reducer for labeled repeated signals.

PHATEReducer

Nonlinear embedding often useful for smooth trajectories.

UMAPReducer

Nonlinear neighborhood-preserving reducer for tabular inputs.

PCAReducer

Linear baseline for sample-feature matrices.

Examples

>>> import numpy as np
>>> from coco_pipe.dim_reduction import DMDReducer
>>> x = np.linspace(0, 2 * np.pi, 20)
>>> t = np.linspace(0, 4 * np.pi, 40)
>>> X = np.sin(x)[:, None] * np.cos(t)[None, :]
>>> reducer = DMDReducer(n_components=2)
>>> _ = reducer.fit(X)
>>> reducer.eigs_.shape
(2,)
>>> reducer.transform(X).shape
(40, 2)

property capabilities: dict

Return capability metadata for DMD.

Returns:

Capability mapping describing DMD as a linear reducer operating on (n_features, n_snapshots) inputs.

Return type:

dict

force_transpose = False

fit(X: coco_pipe.dim_reduction.reducers.base.ArrayLike, y: coco_pipe.dim_reduction.reducers.base.ArrayLike | None = None) → DMDReducer

Fit DMD on the input snapshot matrix.

Parameters:

• X (ArrayLike of shape (n_features, n_snapshots)) – Training data. If force_transpose=True, input may instead be provided as (n_snapshots, n_features).

• y (ArrayLike, optional) – Ignored. Present for API compatibility.

Returns:

Fitted reducer instance.

Return type:

DMDReducer

Examples

>>> import numpy as np
>>> from coco_pipe.dim_reduction import DMDReducer
>>> X = np.random.rand(5, 20)
>>> reducer = DMDReducer(n_components=2)
>>> _ = reducer.fit(X)
>>> reducer.model is not None
True

transform(X: coco_pipe.dim_reduction.reducers.base.ArrayLike) → numpy.ndarray

Project snapshots onto the fitted DMD modes.

Parameters:

X (ArrayLike of shape (n_features, n_snapshots)) – Data to project. If force_transpose=True, input may instead be provided as (n_snapshots, n_features).

Returns:

Time-evolution amplitudes projected onto the fitted modes.

Return type:

np.ndarray of shape (n_snapshots, n_components)

property svd_rank: int

Return the SVD rank used for the DMD decomposition.

Returns:

SVD rank.

Return type:

int

property n_modes_: int | None

Return the number of fitted DMD modes.

Returns:

Mode count or None if not fitted.

Return type:

int or None

property eigs_: numpy.ndarray

Return the DMD eigenvalues.

Returns:

Eigenvalues associated with the fitted modes.

Return type:

np.ndarray

Raises:

RuntimeError – If the reducer has not been fitted.

property modes_: numpy.ndarray

Return the DMD spatial modes.

Returns:

Spatial mode matrix exposed by the fitted DMD model.

Return type:

np.ndarray

Raises:

RuntimeError – If the reducer has not been fitted.

get_components() → numpy.ndarray

Return DMD modes in component-major layout.

Returns:

Mode matrix transposed to (n_components, n_features).

Return type:

np.ndarray

property reconstructed_data_: numpy.ndarray

Return the reconstructed snapshot matrix from the fitted DMD model.

Returns:

Reconstructed data exposed by the fitted DMD backend.

Return type:

np.ndarray

Raises:

RuntimeError – If the reducer has not been fitted.

class coco_pipe.dim_reduction.reducers.spatiotemporal.TRCAReducer(n_components: int = 1, sfreq: float = 250.0, filterbank: list | None = None, **kwargs)

Bases: coco_pipe.dim_reduction.reducers.base.BaseReducer

Task-Related Component Analysis reducer.

TRCA learns spatial filters that maximize reproducibility across repeated labeled trials. It is primarily useful for trial-based biosignal data such as SSVEP or ERP analyses, but the reducer contract is expressed in terms of generic (n_trials, n_channels, n_times) arrays rather than any specific domain object.

Parameters:

• n_components (int, default=1) – Number of output components to keep after projection. The underlying TRCA backend may produce more (band, class) filters; this wrapper truncates the projected output to the requested count.

• sfreq (float, default=250.0) – Sampling frequency in Hertz.

• filterbank (list, optional) – Filterbank definition passed to meegkit.trca.TRCA. If omitted, a single broad band [(8, 30), (7, 35)] is used.

• **kwargs (dict) – Additional keyword arguments forwarded to meegkit.trca.TRCA after signature filtering.

model

Fitted TRCA estimator after fit.

Type:

meegkit.trca.TRCA or None

Notes

TRCA requires class labels during fitting. The y argument is not optional in practice even though it remains optional in the shared reducer interface.

See also

DMDReducer

Snapshot-based spatiotemporal decomposition.

PCAReducer

Linear reducer for standard sample-feature matrices.

UMAPReducer

Nonlinear reducer for standard sample-feature matrices.

PHATEReducer

Nonlinear reducer often used for continuous trajectories.

Examples

>>> import numpy as np
>>> from coco_pipe.dim_reduction import TRCAReducer
>>> X = np.random.rand(8, 4, 50)
>>> y = np.array([0, 0, 0, 0, 1, 1, 1, 1])
>>> reducer = TRCAReducer(n_components=1, sfreq=100.0)
>>> _ = reducer.fit(X, y=y)
>>> reducer.transform(X).shape
(8, 1, 50)
>>> reducer.get_diagnostics()["coef_"].shape[0] >= 1
True

property capabilities: dict

Return capability metadata for TRCA.

Returns:

Capability mapping describing TRCA as a linear reducer operating on (n_trials, n_channels, n_times) inputs.

Return type:

dict

sfreq = 250.0

filterbank = [[(8, 30), (7, 35)]]

property n_bands: int

Return the number of filter bands.

Returns:

Band count.

Return type:

int

property n_classes: int | None

Return the number of classes identified by TRCA.

Returns:

Class count or None if not fitted.

Return type:

int or None

fit(X: coco_pipe.dim_reduction.reducers.base.ArrayLike, y: coco_pipe.dim_reduction.reducers.base.ArrayLike | None = None) → TRCAReducer

Fit TRCA on labeled trial data.

Parameters:

• X (ArrayLike of shape (n_trials, n_channels, n_times)) – Training data.

• y (ArrayLike of shape (n_trials,)) – Class labels aligned with trials. This argument is required.

Returns:

Fitted reducer instance.

Return type:

TRCAReducer

Raises:

ValueError – If the input is not 3-dimensional, if y is missing, or if label length does not match the number of trials.

Examples

>>> import numpy as np
>>> from coco_pipe.dim_reduction import TRCAReducer
>>> X = np.random.rand(6, 3, 40)
>>> y = np.array([0, 0, 0, 1, 1, 1])
>>> reducer = TRCAReducer(n_components=1, sfreq=100.0)
>>> _ = reducer.fit(X, y=y)
>>> reducer.model is not None
True

transform(X: coco_pipe.dim_reduction.reducers.base.ArrayLike) → numpy.ndarray

Project trial data using the fitted TRCA spatial filters.

Parameters:

X (ArrayLike of shape (n_trials, n_channels, n_times)) – New data to project.

Returns:

Projected trial signals, truncated to n_components.

Return type:

np.ndarray of shape (n_trials, n_components, n_times)

Raises:

ValueError – If the input is not 3-dimensional.

get_components() → numpy.ndarray

Return the learned TRCA spatial filters.

Returns:

Spatial filter tensor with shape determined by the TRCA backend.

Return type:

np.ndarray