phase_locking_value

phase_locking_value#

class braintools.analysis.spike.phase_locking_value(spike_matrix, reference_freq, dt=None)#

Calculate phase-locking value (PLV) for spike synchronization.

The PLV measures the consistency of phase relationships between spike trains and a reference oscillation, indicating rhythmic synchronization [1].

For each spike, the phase relative to the reference oscillation is computed, and the PLV is the magnitude of the mean resultant vector:

\[PLV = \left|\frac{1}{N}\sum_{k=1}^{N} e^{i\phi_k}\right|\]

where \(\phi_k\) is the phase of the k-th spike.

Parameters:

  • spike_matrix (Array | ndarray | bool | number | bool | int | float | complex | Quantity) – Spike matrix with shape (n_time_steps, n_neurons).

  • reference_freq (float) – Reference frequency for phase computation (in Hz).

  • dt (float | Quantity | None) – Time step between successive samples. If None, uses the brainstate default. A plain float is assumed to be in seconds (so that it is consistent with reference_freq in Hz); a brainunit.Quantity is converted to seconds.

Returns:

Phase-locking values for each neuron. Shape (n_neurons,). Values range from 0 (no phase locking) to 1 (perfect phase locking).

Return type:

jnp.ndarray

See also

braintools.analysis.spectral.plv

Phase-locking value between two continuous signals (Lachaux et al. 1999).

Notes

This computes the vector strength (Rayleigh resultant length) of each neuron’s spikes relative to an external reference oscillation of frequency reference_freq. It is therefore a spike–field locking measure, not the Lachaux et al. (1999) [1] pairwise PLV between two continuous signals.

Vector strength is biased upward for small spike counts: a neuron with a single spike trivially yields PLV = 1, and a handful of spikes can give a large value by chance. Interpret values with caution when spike counts are low, and consider a Rayleigh-style bias correction or a minimum-spike threshold.

This function runs on host (concrete) arrays (Python loop over neurons, boolean-mask indexing), so it is not jit/vmap/grad-compatible.

References

Examples

>>> import jax.numpy as jnp
>>> import braintools
>>> n_time, n_neurons = 1000, 5
>>> spikes = jnp.zeros((n_time, n_neurons))
>>> freq, dt = 10.0, 0.001  # 10 Hz reference, 1 ms step
>>> # Place one spike per 10 Hz cycle for neuron 0 (strong locking).
>>> idx = (jnp.arange(10) / freq / dt).astype(int)
>>> spikes = spikes.at[idx, 0].set(1.0)
>>> plv = braintools.analysis.spike.phase_locking_value(spikes, freq, dt)
>>> plv.shape
(5,)