pyriemann.estimation.Coherences

class pyriemann.estimation.Coherences(window=128, overlap=0.75, fmin=None, fmax=None, fs=None, coh='ordinary')

Estimation of squared coherence matrices.

Squared coherence matrices estimation [1]. This method will return a 4-d array with a squared coherence matrix estimation for each input and in each frequency bin of the FFT.

Parameters:

windowint, default=128

The length of the FFT window used for spectral estimation.

overlapfloat, default=0.75

The percentage of overlap between window.

fminfloat | None, default=None

the minimal frequency to be returned.

fmaxfloat | None, default=None

The maximal frequency to be returned.

fsfloat | None, default=None

The sampling frequency of the signal.

coh{‘ordinary’, ‘instantaneous’, ‘lagged’, ‘imaginary’}, default=’ordinary’

The coherence type:

• ‘ordinary’ for the ordinary coherence, defined in Eq.(22) of [1]; this normalization of cross-spectral matrices captures both in-phase and out-of-phase correlations. However it is inflated by the artificial in-phase (zero-lag) correlation engendered by volume conduction.

• ‘instantaneous’ for the instantaneous coherence, Eq.(26) of [1], capturing only in-phase correlation.

• ‘lagged’ for the lagged-coherence, Eq.(28) of [1], capturing only out-of-phase correlation (not defined for DC and Nyquist bins).

• ‘imaginary’ for the imaginary coherence [2], Eq.(0.16) of [3], capturing out-of-phase correlation but still affected by in-phase correlation.

See also

Covariances

HankelCovariances

CospCovariances

Notes

New in version 0.3.

References

[1] (1,2,3,4)

Instantaneous and lagged measurements of linear and nonlinear dependence between groups of multivariate time series: frequency decomposition R. Pascual-Marqui. Technical report, 2007.

[2]

Identifying true brain interaction from EEG data using the imaginary part of coherency G. Nolte, O. Bai, L. Wheaton, Z. Mari, S. Vorbach, M. Hallett. Clinical Neurophysioly, Volume 115, Issue 10, October 2004, Pages 2292-2307

[3]

Non-Parametric Synchronization Measures used in EEG and MEG M. Congedo. Technical Report, 2018.

Attributes:

freqs_ndarray, shape (n_freqs,)

If transformed, the frequencies associated to cospectra. None if fs is None.

__init__(window=128, overlap=0.75, fmin=None, fmax=None, fs=None, coh='ordinary')

Init.

fit(X, y=None)

Fit.

Do nothing. For compatibility purpose.

Parameters:

Xndarray, shape (n_matrices, n_channels, n_times)

Multi-channel time-series.

yNone

Not used, here for compatibility with sklearn API.

Returns:

selfCospCovariances instance

The CospCovariances instance.

fit_transform(X, y=None, **fit_params)

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:

Xarray-like of shape (n_samples, n_features)

Input samples.

yarray-like of shape (n_samples,) or (n_samples, n_outputs), default=None

Target values (None for unsupervised transformations).

**fit_paramsdict

Additional fit parameters.

Returns:

X_newndarray array of shape (n_samples, n_features_new)

Transformed array.

get_metadata_routing()

Get metadata routing of this object.

Please check User Guide on how the routing mechanism works.

Returns:

routingMetadataRequest

A MetadataRequest encapsulating routing information.

get_params(deep=True)

Get parameters for this estimator.

Parameters:

deepbool, default=True

If True, will return the parameters for this estimator and contained subobjects that are estimators.

Returns:

paramsdict

Parameter names mapped to their values.

set_output(*, transform=None)

Set output container.

See sphx_glr_auto_examples_miscellaneous_plot_set_output.py for an example on how to use the API.

Parameters:

transform{“default”, “pandas”}, default=None

Configure output of transform and fit_transform.

• “default”: Default output format of a transformer

• “pandas”: DataFrame output

• None: Transform configuration is unchanged

Returns:

selfestimator instance

Estimator instance.

set_params(**params)

Set the parameters of this estimator.

The method works on simple estimators as well as on nested objects (such as Pipeline). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.

Parameters:

**paramsdict

Estimator parameters.

Returns:

selfestimator instance

Estimator instance.

transform(X)

Estimate the squared coherences matrices.

Parameters:

Xndarray, shape (n_matrices, n_channels, n_times)

Multi-channel time-series.

Returns:

covmatsndarray, shape (n_matrices, n_channels, n_channels, n_freqs)

Squared coherence matrices for each input and for each frequency bin.