braintools.analysis.spectral.plv

Contents

braintools.analysis.spectral.plv#

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

Compute the phase-locking value between two continuous signals.

The instantaneous phases \(\phi_x, \phi_y\) are the angles of the analytic signals (analytic_signal()) and [1]

\[\mathrm{PLV} = \left| \frac{1}{T} \sum_{t} e^{i(\phi_x(t) - \phi_y(t))} \right|.\]
Parameters:

  • x (Array | ndarray | bool | number | bool | int | float | complex | Quantity) – Real signals of identical shape (T, ...); time is axis 0. Quantities are accepted (phases are scale-invariant).

  • y (Array | ndarray | bool | number | bool | int | float | complex | Quantity) – Real signals of identical shape (T, ...); time is axis 0. Quantities are accepted (phases are scale-invariant).

  • 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() (order=4) in band Hz. Phase is only meaningful for narrow-band signals, so either pass band or pre-filter the inputs.

Returns:

plv – Values in [0, 1] of shape x.shape[1:]; 1 means a constant phase difference.

Return type:

Array

Raises:

ValueError – If the shapes differ, band is given without dt, or band is invalid (see bandpass()).

See also

pli

Phase-lag index (insensitive to zero-lag coupling).

wpli

Weighted phase-lag index.

braintools.analysis.spike.phase_locking_value

Spike-field locking. That function measures how consistently the spikes of each neuron fall at the same phase of an external reference oscillation of a given frequency (vector strength of spike phases), whereas this function measures phase locking between two continuous signals sampled at every time step (Lachaux et al. 1999).

Notes

Jittable and vmappable. Differentiable with respect to the signals wherever the analytic amplitudes are non-zero and PLV > 0.

References

Examples

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