gastropy.surrogate_plv

Contents

gastropy.surrogate_plv#

gastropy.surrogate_plv(phase_a, phase_b, buffer_samples=None, n_surrogates=None, stat='median', seed=None, mask=None)[source]#

Compute surrogate PLV via circular time-shifting.

Creates a null distribution of PLV by circularly shifting the reference phase time series (phase_b) and recomputing PLV for each shift. This preserves the autocorrelation of both signals while destroying the true phase relationship.

Parameters:

  • phase_a (array_like, shape (n_timepoints,) or (n_timepoints, n_signals)) – Phase time series (e.g., BOLD voxel phases).

  • phase_b (array_like, shape (n_timepoints,)) – Reference phase time series (e.g., EGG phase). This signal is circularly shifted.

  • buffer_samples (int, optional) – Number of samples to exclude from each edge when generating shifts. Prevents near-zero shifts that would approximate the empirical PLV. Default is n_timepoints // 10 (10% of signal length).

  • n_surrogates (int, optional) – Number of random shifts to use. If None (default), uses all valid shifts (excluding the buffer at each edge).

  • stat ({"median", "mean", "all"}) – Summary statistic across surrogates. "median" (default) returns the median surrogate PLV (as in Banellis et al. 2025). "mean" returns the mean. "all" returns the full array of surrogate PLV values.

  • seed (int or np.random.Generator, optional) – Random seed for reproducibility when n_surrogates is set.

  • mask (array_like of bool, shape (n_timepoints,), optional) – Boolean mask where True = include. Passed through to phase_locking_value for each surrogate shift.

Returns:

surr_plv – Surrogate PLV value(s). Shape depends on stat and input dimensions:

  • stat="median" or "mean": same shape as phase_locking_value(phase_a, phase_b)

  • stat="all": shape (n_shifts,) for 1D phase_a, or (n_shifts, n_signals) for 2D phase_a

Return type:

float, np.ndarray

Examples

>>> import numpy as np
>>> rng = np.random.default_rng(42)
>>> phase_a = rng.uniform(-np.pi, np.pi, 200)
>>> phase_b = rng.uniform(-np.pi, np.pi, 200)
>>> surr = surrogate_plv(phase_a, phase_b, seed=42)
Contents