elephant.spike_train_correlation.correlation_coefficient

elephant.spike_train_correlation.correlation_coefficient(binned_spiketrain, binary=False, fast=True)

Calculate the NxN matrix of pairwise Pearson’s correlation coefficients between all combinations of N binned spike trains.

For each pair of spike trains \((i,j)\), the correlation coefficient \(C[i,j]\) is obtained by binning \(i\) and \(j\) at the desired bin size. Let \(b_i\) and \(b_j\) denote the binned spike trains and \(\mu_i\) and \(\mu_j\) their respective means. Then

\[C[i,j] = <b_i-\mu_i, b_j-\mu_j> / \sqrt{<b_i-\mu_i, b_i-\mu_i> \cdot <b_j-\mu_j, b_j-\mu_j>}\]

where <., .> is the scalar product of two vectors.

For an input of N spike trains, an N x N matrix is returned. Each entry in the matrix is a real number ranging between -1 (perfectly anti-correlated spike trains) and +1 (perfectly correlated spike trains). However, if k-th spike train is empty, k-th row and k-th column of the returned matrix are set to np.nan.

If binary is True, the binned spike trains are clipped to 0 or 1 before computing the correlation coefficients, so that the binned vectors \(b_i\) and \(b_j\) are binary.

Visualization of this function is covered in Viziphant: viziphant.spike_train_correlation.plot_corrcoef().

Parameters:

binned_spiketrain(N, ) elephant.conversion.BinnedSpikeTrain

A binned spike train containing the spike trains to be evaluated.

binarybool, optional

If True, two spikes of a particular spike train falling in the same bin are counted as 1, resulting in binary binned vectors \(b_i\). If False, the binned vectors \(b_i\) contain the spike counts per bin. Default: False

fastbool, optional

If fast=True and the sparsity of binned_spiketrain is > 0.1, use np.corrcoef(). Otherwise, use memory efficient implementation. See Notes[2] Default: True

Returns:

C(N, N) np.ndarray

The square matrix of correlation coefficients. The element \(C[i,j]=C[j,i]\) is the Pearson’s correlation coefficient between binned_spiketrain[i] and binned_spiketrain[j]. If binned_spiketrain contains only one neo.SpikeTrain, C=1.0.

Raises:

MemoryError

When using fast=True and binned_spiketrain shape is large.

Warns:

UserWarning

If at least one row in binned_spiketrain is empty (has no spikes).

See also

covariance

Notes

1. The spike trains in the binned structure are assumed to cover the complete time span [t_start, t_stop) of binned_spiketrain.

2. Using fast=True might lead to MemoryError. If it’s the case, switch to fast=False.

Examples

Correlation coefficient of two Poisson spike train processes.

>>> import neo
>>> import numpy as np
>>> import quantities as pq
>>> from elephant.spike_train_generation import StationaryPoissonProcess
>>> from elephant.conversion import BinnedSpikeTrain
>>> from elephant.spike_train_correlation import correlation_coefficient

>>> np.random.seed(1)
>>> st1 = StationaryPoissonProcess(rate=10*pq.Hz,
... t_stop=10.0*pq.s).generate_spiketrain()
>>> st2 = StationaryPoissonProcess(rate=10*pq.Hz,
... t_stop=10.0*pq.s).generate_spiketrain()
>>> corrcoef = correlation_coefficient(BinnedSpikeTrain([st1, st2],
...     bin_size=5*pq.ms))
>>> corrcoef 
array([[ 1.        , -0.02946313],
       [-0.02946313,  1.        ]])