cedalion.sigdecomp package

Submodules

cedalion.sigdecomp.ERBM module

Independent Component Analysis by Entropy Bound Rate Minimization (ICA-ERBM) based on Li and Adali [LA10a] and Fu et al. [FPA+14]. This code is based on 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.ERBM.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.ERBM.lfc(x: ndarray, p: int, choice, a0) → tuple[ndarray, ndarray][source]

Helper function for ERBM ICA: computes the linear filtering coefficients (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.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.ERBM.cnstd_and_gain(a: ndarray) → tuple[ndarray, ndarray][source]

Helper function for ERBM ICA: returns constraint direction used for calculating projected gradient and gain of filter a.

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.ERBM.calculate_cos_sin_mtx(p: int) → None[source]

Helper function for ERBM ICA: calculates 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.ERBM.pre_processing(X: ndarray) → tuple[ndarray, ndarray][source]

Helper function for ERBM ICA: 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.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.ICA_EBM module

Independent Component Analysis by Entropy Bound Minimization (ICA-EBM) based on Li and Adali [LA10b]. This code is based on 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.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.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.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.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.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.dummy module

cedalion.sigdecomp.dummy.split_frequency_bands(
ts: Annotated[DataArray, DataArraySchema(dims='time', coords='time', 'time', 'samples')],
) → Annotated[DataArray, DataArraySchema(dims='time', coords='time', 'time', 'samples')][source]

Extract signal components in different frequency bands.

This is not intended for real use but should act rather as an example how signal decomposition methods could be implemented.

cedalion.sigdecomp.spoc module

Source Power Co-modulation (SPoC) algorithm.

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

Bases: object

Implements the 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

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

  • None (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 only_component = False, 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.

  • only_component – 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.spoc.standardize(
x: DataArraySchema(dims='time', coords='time', 'time', 'samples'),
dim: str = 'time',
)[source]

Standardize x along dimension dim.

Module contents