phase_locking_value

class braintools.metric.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.

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) – Time step between successive samples. If None, uses brainstate default.

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

Examples

>>> import jax.numpy as jnp
>>> import braintools as braintools
>>> # Create phase-locked spikes
>>> n_time, n_neurons = 1000, 5
>>> spikes = jnp.zeros((n_time, n_neurons))
>>> freq = 10.0  # 10 Hz reference
>>> dt = 0.001   # 1 ms
>>> # Add spikes at preferred phases
>>> for i in range(n_neurons):
>>>     phase_pref = i * jnp.pi / 4  # Different preferred phases
>>>     for cycle in range(10):
>>>         t_spike = int((cycle / freq + phase_pref / (2*jnp.pi*freq)) / dt)
>>>         if t_spike < n_time:
>>>             spikes = spikes.at[t_spike, i].set(1)
>>> plv = braintools.metric.phase_locking_value(spikes, freq, dt)
>>> print(f"PLV: {plv}")