correlation_index

correlation_index#

class braintools.metric.correlation_index(spike_matrix, window_size, dt=None)#

Calculate correlation index for spike train synchrony.

The correlation index measures the strength of pairwise correlations in spike trains by computing the average Pearson correlation coefficient between binned spike counts.

The index is computed as:

\[CI = \frac{1}{N(N-1)} \sum_{i \neq j} \rho_{ij}\]

where \(\rho_{ij}\) is the Pearson correlation coefficient between the binned spike counts of neurons i and j.

Parameters:

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

  • window_size (float) – Size of the time windows used to bin spikes. Must use the same time unit as dt.

  • dt (float) – Time step between successive samples. If None, uses brainstate default.

Returns:

Correlation index representing the average pairwise correlation. Values range from -1 to 1, where positive values indicate synchrony.

Return type:

float

Notes

This is the mean pairwise Pearson correlation of binned spike counts. It is distinct from the Wong–Meister/Mastronarde “correlation index”, which is a coincidence-rate ratio (expected-vs-observed near-coincident firings) with a different range and interpretation. Use this function when a normalized [-1, 1] linear-correlation summary is desired.

This function runs on host (concrete) arrays — it uses Python loops and numpy.corrcoef(), so it is not jit/vmap/grad-compatible.

References

Examples

>>> import brainstate
>>> import braintools
>>> # Two correlated trains and one independent train.
>>> base = (brainstate.random.rand(1000, 1) < 0.1).astype(float)
>>> noise = (brainstate.random.rand(1000, 1) < 0.1).astype(float)
>>> third = (brainstate.random.rand(1000, 1) < 0.1).astype(float)
>>> import jax.numpy as jnp
>>> spikes = jnp.concatenate([base, jnp.clip(base + noise, 0, 1), third], axis=1)
>>> ci = braintools.metric.correlation_index(spikes, window_size=50.0, dt=1.0)
>>> bool(-1.0 <= ci <= 1.0)
True