elephant.phase_analysis.weighted_phase_lag_index

elephant.phase_analysis.weighted_phase_lag_index(signal_i, signal_j, sampling_frequency=None, absolute_value=True)[source]

Calculates the Weigthed Phase-Lag Index (WPLI) (Vinck et al., 2011).

This function estimates the WPLI, which is a measure of phase-synchrony. It describes for two given signals i and j, which is leading/lagging the other signal in the frequency domain across multiple trials.

Parameters:
signal_i, signal_jnp.array, pq.quantity.Quantity, neo.AnalogSignal

Time-series of the first and second signals, with t time points and n trials.

sampling_frequencypq.quantity.Quantity (default: None)

Sampling frequency of the signals in Hz. Not needed if signal i and j are neo.AnalogSignals.

absolute_valueboolean (default: True)

Takes the absolute value of the numerator in the WPLI-formula. When set to False, the WPLI contains additional directionality information about which signal leads/lags the other signal:

  • wpli > 0 : first signal i leads second signal j

  • wpli < 0 : first signal i lags second signal j

Returns:
freqspq.quantity.Quantity

Positive frequencies in Hz associated with the estimates of wpli. Range: \([0, sampling frequency/2]\)

wplinp.ndarray with dtype=float

Weighted phase-lag index of signal_i and signal_j across trials. Range: \([0, 1]\)

Raises:
ValueError

If trial number or trial length are different for signal i and j.

Notes

This implementation is based on the formula taken from (Vinck et al., 2011) (pp.1550, equation (8)) :

\[WPLI = \frac{| E( |Im(X)| * sgn(Im(X)) ) |}{E( |Im(X)| )}\]

with:

  • \(E{...}\) : expected value operator

  • \(Im{X}\) : imaginary component of the cross-spectrum

  • \(X = Z_i Z_{j}^{*}\) : cross-spectrum, averaged across trials

  • \(Z_i, Z_j\): complex-valued matrix, representing the Fourier spectra of a particular frequency of the signals i and j.