braintools.analysis.spectral.wpli

Contents

braintools.analysis.spectral.wpli#

braintools.analysis.spectral.wpli(x, y, dt=None, band=None)#

Compute the weighted phase-lag index between two continuous signals.

With \(S(t) = z_x(t)\,\overline{z_y(t)}\) the cross-spectrum of the analytic signals, the weighted phase-lag index [1] is

\[\mathrm{wPLI} = \frac{\left| \langle \operatorname{Im} S(t) \rangle \right|} {\langle \left| \operatorname{Im} S(t) \right| \rangle},\]

i.e. the PLI with each sample weighted by the magnitude of the imaginary cross-spectrum, which down-weights samples near zero lag.

Parameters:

  • x (Array | ndarray | bool | number | bool | int | float | complex | Quantity) – Real signals of identical shape (T, ...); time is axis 0.

  • y (Array | ndarray | bool | number | bool | int | float | complex | Quantity) – Real signals of identical shape (T, ...); time is axis 0.

  • dt (float | Quantity | None) – Sampling interval (seconds if a plain number). Required with band.

  • band (Tuple[float, float] | None) – If given, both signals are first filtered with bandpass().

Returns:

wpli – Values in [0, 1] of shape x.shape[1:]. nan where the imaginary cross-spectrum is identically zero (e.g. identical signals), since the index is then undefined.

Return type:

Array

Raises:

ValueError – If the shapes differ, band is given without dt, or band is invalid.

See also

plv

Phase-locking value.

pli

Phase-lag index.

Notes

Jittable and vmappable. Differentiable with respect to the signals wherever the denominator is non-zero.

References

Examples

>>> import jax.numpy as jnp
>>> from braintools.analysis.spectral import wpli
>>> t = jnp.arange(1000) * 1e-3
>>> x = jnp.cos(2 * jnp.pi * 10 * t)
>>> round(float(wpli(x, jnp.cos(2 * jnp.pi * 10 * t - jnp.pi / 4))), 4)
1.0
Contents