cedalion.sigdecomp.multimodal.mspoc

Implements the mSPoC algorithm for multimodal data.

Functions

`get_orthonormal_matrix`(W)	Generate an orthonormal basis for an N-dimensional space where the columns of W are some of the basis vectors.
`temporal_embedding`(X, time_shifts, time)	Construct a time-embedded version of a matrix X.

Classes

mSPoC([N_components, time_shifts, ...])

Implements the multimodal Source Power Co-modulation (mSPoC) algorithm based on Dähne et al. [DBM+13].

class cedalion.sigdecomp.multimodal.mspoc.mSPoC( N_components: int = None, time_shifts=None, N_restarts: int = 2, max_iter: int = 200, tol: float = 1e-05, scale: bool = True, shift_source: bool = True, )[source]

Bases: object

Implements the multimodal Source Power Co-modulation (mSPoC) algorithm based on Dähne et al. [DBM+13].

Given two vector-valued time series X(t), and Y(t), mSPoC finds component pairs Sx = Wx.T @ X, and Sy = Wy.T @ Y, such that the covariance between the temporally-embedded bandpower of Sx and the time course of Sy is maximized. The solution to that optimization problem is captured by the spatial (Wx, Wy), and temporal (Wt) filters.

X(t) must be of shape Ntx x Nx, where Nx is the number of channels and Nt the number of time points, and it is band-pass filtered in the frequency band of interest. Bandpower of Sx is then approximated by its variance within epochs. The latter are defined by the time points of Y(t), which must have a greater sampling rate. Y(t) is of shape Nty x Ny, and Nty < Ntx. Both signals are mean-free and temporally aligned.

Parameters:

N_components (int) – Number of component pairs the algorithm will find.
time_shifts (list) – List of time shifts to consider in the temporal embedding.
N_restarts (int) – Number of times the algorithm is repeated.
max_iter (int) – Maximum number of iterations.
tol (float) – Tolerance value used for convergence criterion when comparing correlations of consecutive runs.
scale (bool) – Whether to scale the data during normalization to unit variance. Defaults to True.
shift_source (bool) – Whether to shift the reconstructed sources by the optimal time lag found during training. Defaults to True.

fit( X: DataArray, Y: DataArray, featureX_name: str = 'channel', featureY_name: str = 'channel', )[source]

Train mSPoC model on the X, Y dataset

Implement the pseudo-code of Algorithm 1 of Dähne et al. [DBM+13] for a single component pair. After training, the filter attributes Wx, Wy, and Wt are updated.

Parameters:

X (DataArray) – Input data for modality X. Expected to have dimensions (sample_name, featureX_name).
Y (DataArray) – Input data for modality Y. Expected to have dimensions (sample_name, featureY_name).
featureX_name (str) – Name of the feature dimension for X.
featureY_name (str) – Name of the feature dimension for Y.

transform( X: DataArray, Y: DataArray, ) → tuple[DataArray, DataArray][source]

Get reconstructed sources of the X and Y dataset.

The X component is constructed by computing the bandpower of the X projection along Wx, and then applying a liner temporal filter using Wt. The Y component is constructed as the linear projection of Y along Wy.

Parameters:

X (DataArray) – Input data for modality X.
Y (DataArray) – Input data for modality Y.

Returns:

A tuple (Sx, Sy) where:: Sx (DataArray): Reconstructed source of modality X. Sy (DataArray): Reconstructed source of modality Y.

Return type:

tuple

one_unit_algorithm(Y, Cxx, Cxxe, tCxxe, time)[source]: Run the one-unit algorithm of mSPoC to compute one single set of filters.

deflate_data(x, w)[source]: Deflate data by removing from x the contribution of the projection on w.

get_bandpower(W, C)[source]

Compute bandpower with temporal embedding.

It estimates the bandpower of a signal by computing the variance within epochs.

static apply_cca(a, b)[source]: Initialize and fit 1-component CCA to the a, b pair.

static split_epochs(x, Ne, e_len)[source]: Split a signal x into Ne epochs of length e_len.

validate_inputs_fit( X: DataArray, Y: DataArray, ) → tuple[DataArray, DataArray][source]

Validates input data of fit function and returns it with the correct dimensions and labels.

This method ensures that the input data to the fit function, X and Y, i.e. those used for training, have the expected dimension labels and sizes and returns them with the dimensions ordered as (sample_name, feature_name). It also initializes the number of samples, and features.

Parameters:

X (DataArray) – Input data for modality X.
Y (DataArray) – Input data for modality Y.

Returns:

A tuple (X, Y) where:: X (DataArray): Input data for modality X ordered as (sample_name, featureX_name). Y (DataArray): Input data for modality Y ordered as (sample_name, featureY_name).

Return type:

tuple

validate_inputs_transform( X: DataArray, Y: DataArray, ) → tuple[DataArray, DataArray][source]

Validates that the to-be-transformed data have the expected dimension labels and sizes.

This method ensures that X and Y have the same dimension labels and number of features than the ones used during training.

Parameters:

X (DataArray) – Input data for modality X.
Y (DataArray) – Input data for modality Y.

Returns:

A tuple (X, Y) where:: X (DataArray): Input data for modality X ordered as (sample_name, featureX_name). Y (DataArray): Input data for modality Y ordered as (sample_name, featureY_name).

Return type:

tuple

convert_filters_to_DataArray( Wx: ndarray, Wy: ndarray, Wt: ndarray, X: DataArray, Y: DataArray, ) → list[DataArray, DataArray, DataArray][source]

Convert filters Wx, Wy, Wt in numpy array format to DataArray with right dimensions and coordinates.

Parameters:

Wx (ndarray) – Filter matrix for modality X with shape (Nx, N_components).
Wy (ndarray) – Filter matrix for modality Y with shape (Ny, N_components).
Wt (ndarray) – Filter matrix for time embedding with shape (N_shifts, N_components).
X_features (DataArray) – DataArray containing the features of modality X.
Y_features (DataArray) – DataArray containing the features of modality Y.

Returns:

A tuple containing the DataArray versions of Wx, Wy, and Wt.

Return type:

tuple[DataArray, DataArray, DataArray]

estimate_optimal_shift()[source]: Find optimal time shifts for X by looking for the largest Wt component.

shift_by_optimal( X: DataArray, ) → DataArray[source]: Shift X by optimal time shift using zero padding.

cedalion.sigdecomp.multimodal.mspoc.temporal_embedding( X: ndarray, time_shifts: ndarray, time: ndarray, ) → ndarray[source]

Construct a time-embedded version of a matrix X.

Parameters:

X (ndarray) – Matrix to embed in time.
time_shifts (ndarray) – Array of time shifts to consider.
time (ndarray) – Array of time points.

Returns:

Time-embedded version of X.

Return type:

ndarray

cedalion.sigdecomp.multimodal.mspoc.get_orthonormal_matrix(W: ndarray) → ndarray[source]

Generate an orthonormal basis for an N-dimensional space where the columns of W are some of the basis vectors.

Parameters:: W (np.ndarray) – A N x Nc array representing the given vectors.
Returns:: An N x N - Nc orthonormal basis matrix, where the columns of W are not present.
Return type:: basis (np.ndarray)