cedalion.sigdecomp.unimodal package

Submodules

cedalion.sigdecomp.unimodal.ica_ebm module

Independent Component Analysis by Entropy Bound Minimization (ICA-EBM).

This code is based on Li and Adali [LA10b] and converted matlab versions provided by the MLSP Lab at the University of Maryland, which is available here: https://mlsp.umbc.edu/resources.html.

cedalion.sigdecomp.unimodal.ica_ebm.ICA_EBM(X: ndarray) → ndarray[source]

Calculates the blind source separation demixing matrix corresponding to X.

ICA-EBM: ICA by Entropy Bound Minimization (real-valued version) Four nonlinearities x^4, |x|/(1+|x|), x|x|/(10+|x|), and x/(1+x^2) are used for entropy bound calculation

Parameters:

X (np.ndarray, (Channels, Time Points)) – the [N x T] input multivariate time series with dimensionality N observations/channels and T time points

Returns:

the [N x N] demixing matrix with weights

for N channels/sources. To obtain the independent components, the demixed signals can be calculated as S = W @ X.

Return type:

W (np.ndarray, (Channels, Channels))

Initial Contributors:

References

This code is based on the matlab version by Xi-Lin Li (Li and Adali [LA10b]) Xi-Lin Li and Tulay Adali, “Independent component analysis by entropy bound minimization,” IEEE Trans. Signal Processing, vol. 58, no. 10, pp. 5151-5164, Oct. 2010. The original matlab version is available at https://mlsp.umbc.edu/resources.html under the name “Real-valued ICA by entropy rate bound minimization (ICA-ERBM)”

cedalion.sigdecomp.unimodal.ica_ebm.simplified_ppval(pp: dict, xs: float) → float[source]
Helper function for ICA EBM: simplified version of ppval.

This function evaluates a piecewise polynomial at a specific point.

Parameters:

  • pp (dict) – a dictionary containing the piecewise polynomial representation of a function

  • xs (float) – the evaluation point

Returns:

the value of the function at xs

Return type:

v (float)

cedalion.sigdecomp.unimodal.ica_ebm.inv_sqrtmH(B: ndarray) → ndarray[source]

Helper function for ICA EBM: computes the inverse square root of a matrix.

Parameters:

B (np.ndarray) – a square matrix

Returns:

the inverse square root of B

Return type:

A (np.ndarray)

cedalion.sigdecomp.unimodal.ica_ebm.pre_processing(X: ndarray) → tuple[ndarray, ndarray][source]

Helper function for ICA EBM: pre-processing (DC removal & spatial pre-whitening).

Parameters:

X (np.ndarray, (Channels, Time Points)) – the data matrix [N x T]

Returns:

the pre-processed data matrix [N x T] P (np.ndarray, (Channels, Channels)): the pre-whitening matrix [N x N]

Return type:

X (np.ndarray, (Channels, Time Points))

cedalion.sigdecomp.unimodal.ica_ebm.symdecor(M: ndarray) → ndarray[source]

Helper function for ICA EBM: fast symmetric orthogonalization.

Parameters:

M (np.ndarray, (Channels, Channels)) – the matrix to be orthogonalized [N x N]

Returns:

the orthogonalized matrix [N x N]

Return type:

W (np.ndarray, (Channels, Channels))

cedalion.sigdecomp.unimodal.ica_erbm module

Independent Component Analysis by Entropy Bound Rate Minimization (ICA-ERBM).

This code is based on Li and Adali [LA10a] and Fu et al. [FPA+14]. It was converted from matlab versions provided by the MLSP Lab at the University of Maryland, which is available here: https://mlsp.umbc.edu/resources.html.

cedalion.sigdecomp.unimodal.ica_erbm.ICA_ERBM(X: ndarray, p: int = None) → ndarray[source]

ICA-ERBM: ICA by Entropy Rate Bound Minimization (real-valued version).

Parameters:

  • X (np.ndarray, (Channels, Time Points)) – the [N x T] input multivariate time series with dimensionality N observations/channels and T time points

  • p (int) – the filter length for the invertible filter source model, does not need to be specified. Default is p = (11, T/50).

Returns:

the [N x N] demixing matrix with weights

for N channels/sources. To obtain the independent components, the demixed signals can be calculated as S = W @ X.

Return type:

W (np.ndarray, (Channels, Channels))

Initial Contributors:

References

This code is based on the matlab version of bss by Xi-Lin Li (Li and Adali [LA10a]) Xi-Lin Li, Tulay Adali, “Blind spatiotemporal separation of second and/or higher-order correlated sources by entropy rate minimization,” IEEE International Conference on Acoustics, Speech and Signal Processing 2010. The original matlab version is available at https://mlsp.umbc.edu/resources.html under the name “Real-valued ICA by entropy bound minimization (ICA-EBM)”

cedalion.sigdecomp.unimodal.ica_erbm.lfc(x: ndarray, p: int, choice, a0) → tuple[ndarray, ndarray][source]

Compute the linear filtering coefficients (LFC).

This helper function for ERBM ICA: computes the LFC with length p for entropy rate estimation, and the estimated entropy rate.

Parameters:

  • x (np.ndarray, (Time Points, 1)) – the source estimate [T x 1]

  • p (int) – the filter length for the source model

  • choice – can be ‘sub’, ‘super’ or ‘unknown’; any other input is handled as ‘unknown’

  • a0 (np.ndarray or empty list) – is the intial guess [p x 1] or an empty list []

Returns:

the filter coefficients [p x 1] min_cost (np.ndarray, (1, 1)): the entropy rate estimation [1 x 1]

Return type:

a (np.ndarray, (p, 1))

cedalion.sigdecomp.unimodal.ica_erbm.simplified_ppval(pp: dict, xs: float) → float[source]

Helper function for ERBM ICA: simplified version of ppval.

This function evaluates a piecewise polynomial at a specific point.

Parameters:

  • pp (dict) – a dictionary containing the piecewise polynomial representation of a function

  • xs (float) – the evaluation point

Returns:

the value of the function at xs

Return type:

v (float)

cedalion.sigdecomp.unimodal.ica_erbm.cnstd_and_gain(a: ndarray) → tuple[ndarray, ndarray][source]

Constraint direction for calculating projected gradient and gain of filter a.

Helper function for ERBM ICA.

Parameters:

a (np.ndarray, (p, 1)) – the filter coefficients [p x 1]

Returns:

the constraint direction [p x 1] G (np.ndarray, (1,)): the gain of the filter a

Return type:

b (np.ndarray, (p, 1))

cedalion.sigdecomp.unimodal.ica_erbm.calculate_cos_sin_mtx(p: int) → None[source]

Calculate the cos and sin matrix for integral calculation in ERBM ICA.

Parameters:

p (int) – the filter length for the invertible filter source model

Returns:

None

cedalion.sigdecomp.unimodal.ica_erbm.pre_processing(X: ndarray) → tuple[ndarray, ndarray][source]

Preprocessing (removal of mean, patial pre-whitening, temporal pre-filtering).

Parameters:

X (np.ndarray, (Channels, Time Points)) – the [N x T] input multivariate time series with dimensionality N observations/channels and T time points

Returns:

the pre-processed input multivariate

time series.

P (np.ndarray, (Channels, Channels)): the pre-whitening matrix

Return type:

X (np.ndarray, (Channels, Time Points))

cedalion.sigdecomp.unimodal.ica_erbm.inv_sqrtmH(B: ndarray) → ndarray[source]

Helper function for ERBM ICA: computes the inverse square root of a matrix.

Parameters:

B (np.ndarray) – a square matrix

Returns:

the inverse square root of B

Return type:

A (np.ndarray)

cedalion.sigdecomp.unimodal.spoc module

Source Power Co-modulation (SPoC) algorithm.

class cedalion.sigdecomp.unimodal.spoc.SPoC(n_comp: int | None = None)[source]

Bases: object

Source Power Co-modulation (SPoC_lambda) algorithm based on Dähne et al. [DMH+14].

Given a vector-valued time signal x(t) and a scalar target function z(t), SPoC finds spatial filters W that maximize the covariance between the bandpower of the projected x signal, P(W.T @ x), and z. Such a covariance defines the objective function of the problem, whose solution can be formulated as the one for a generalized eigenvalue problem. The reconstructed sources s are given by the backward model s = W.T @ x.

Assumptions:

x(t) is of shape Nx x Nt, 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. z(e) is a standardize vector (zero mean and unit variance) of shape 1 x Ne, where Ne < Nt is the number of “epochs”. The latter represent labels for intervals of the original time series. Bandpower of the projected signal W.T @ x is then approximated by its variance within epochs.

Parameters:

  • n_comp (int) – Number of components the algorithm will find in decreasing

  • highest (order of scores/eigenvalue. n_comp=1 returns the component of the)

  • None (eigenvalue. If)

  • Nx (n_comp =)

  • components. (the maximum possible number of)

fit(
x: Annotated[DataArray, DataArraySchema(dims='time', coords='time', 'time', 'samples')],
z: DataArray,
) → ndarray[source]

Fit the model on the (x, z) dataset.

Solve the generalized eigenvalue problem and store the trained spatial filters W as a local state of the class.

Parameters:

  • x (NDTimeSeries, (channel, time)) – Temporal signal

  • Nt. (with Ne <)

  • z (DataArray, (time)) – Target (scalar) function

  • Ne (of shape 1 x)

  • Nt.

  • n_comp (int) – Number of components the algorithm will find in decreasing order of scores/eigenvalue. n_comp=1 returns the component of the highest eigenvalue. If None, n_comp = Nx, the maximum possible number of components.

Returns:

Array of Nx eigenvalues. The latter also coincide with

the corresponding covariances between P(W.T @ x) and z.

Return type:

scores

transform(
x: Annotated[DataArray, DataArraySchema(dims='time', coords='time', 'time', 'samples')],
get_bandpower: bool = True,
Ne: int | None = None,
) → DataArray | tuple[DataArray, DataArray][source]

Apply backward model to x to build reconstructed sources.

Get reconstructed sources s by projecting x along the spatial filtes. If get_bandpower = True, also estimate epoch-wise bandpower of the components via the per-epoch variance.

Parameters:

  • x (NDTimeSeries, (channel, time)) – Temporal signal of shape Nx x Nt.

  • get_bandpower – Wether to return only the reconstructed sources or also the epoch-wise bandpower.

  • Ne – Number of epochs along which to estimate the bandpower.

Returns:

Reconstructed sources (W.T @ x). s_power: standardized epoch-wise bandpower of s (Var(W.T @ x)).

Return type:

s

cedalion.sigdecomp.unimodal.spoc.standardize(
x: Annotated[DataArray, DataArraySchema(dims='time', coords='time', 'time', 'samples')],
dim: str = 'time',
)[source]

Standardize x along dimension dim.

Module contents