gastropy.phase_locking_value

gastropy.phase_locking_value#

gastropy.phase_locking_value(phase_a, phase_b, mask=None)[source]#

Compute the phase-locking value between two phase time series.

PLV measures the consistency of the phase difference between two signals across time. A PLV of 1 indicates perfect phase locking, while 0 indicates no consistent phase relationship.

Parameters:

  • phase_a (array_like, shape (n_timepoints,) or (n_timepoints, n_signals)) – Phase time series in radians. When 2D, PLV is computed between each column and phase_b.

  • phase_b (array_like, shape (n_timepoints,)) – Reference phase time series in radians. Broadcast against columns of phase_a when phase_a is 2D.

  • mask (array_like of bool, shape (n_timepoints,), optional) – Boolean mask where True = include, False = exclude. Only the included timepoints contribute to the PLV.

Returns:

plv – Phase-locking value(s) in [0, 1]. Scalar if both inputs are 1D, otherwise array of shape (n_signals,).

Return type:

float or np.ndarray

See also

phase_locking_value_complex

Returns full complex PLV (magnitude + lag).

Examples

>>> import numpy as np
>>> t = np.arange(0, 100, 0.1)
>>> phase_a = 2 * np.pi * 0.05 * t  # constant-frequency phase
>>> phase_b = phase_a + 0.3          # constant offset = perfect locking
>>> plv = phase_locking_value(phase_a, phase_b)
>>> round(plv, 2)
1.0
Contents