elephant.spike_train_correlation.cross_correlation_histogram

elephant.spike_train_correlation.cross_correlation_histogram(binned_spiketrain_i, binned_spiketrain_j, window='full', border_correction=False, binary=False, kernel=None, method='speed', cross_correlation_coefficient=False)[source]

Computes the cross-correlation histogram (CCH) between two binned spike trains binned_spiketrain_i and binned_spiketrain_j. (Eggermont, 2010)

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

Parameters:
binned_spiketrain_i, binned_spiketrain_jBinnedSpikeTrain

Binned spike trains of lengths N and M to cross-correlate - the output of elephant.conversion.BinnedSpikeTrain. The input spike trains can have any t_start and t_stop.

window{‘valid’, ‘full’} or list of int, optional
‘full’: This returns the cross-correlation at each point of overlap,

with an output shape of (N+M-1,). At the end-points of the cross-correlogram, the signals do not overlap completely, and boundary effects may be seen.

‘valid’: Mode valid returns output of length max(M, N) - min(M, N) + 1.

The cross-correlation product is only given for points where the signals overlap completely. Values outside the signal boundary have no effect.

List of integers (min_lag, max_lag):

The entries of window are two integers representing the left and right extremes (expressed as number of bins) where the cross-correlation is computed.

Default: ‘full’
border_correctionbool, optional

whether to correct for the border effect. If True, the value of the CCH at bin \(b\) (for \(b=-H,-H+1, ...,H\), where \(H\) is the CCH half-length) is multiplied by the correction factor:

\[(H+1)/(H+1-|b|),\]

which linearly corrects for loss of bins at the edges. Default: False

binarybool, optional

If True, spikes falling in the same bin are counted as a single spike; otherwise they are counted as different spikes. Default: False

kernelnp.ndarray or None, optional

A one dimensional array containing a smoothing kernel applied to the resulting CCH. The length N of the kernel indicates the smoothing window. The smoothing window cannot be larger than the maximum lag of the CCH. The kernel is normalized to unit area before being applied to the resulting CCH. Popular choices for the kernel are

  • normalized boxcar kernel: numpy.ones(N)

  • hamming: numpy.hamming(N)

  • hanning: numpy.hanning(N)

  • bartlett: numpy.bartlett(N)

If None, the CCH is not smoothed. Default: None

method{‘speed’, ‘memory’}, optional

Defines the algorithm to use. “speed” uses numpy.correlate to calculate the correlation between two binned spike trains using a non-sparse data representation. Due to various optimizations, it is the fastest realization. In contrast, the option “memory” uses an own implementation to calculate the correlation based on sparse matrices, which is more memory efficient but slower than the “speed” option. Default: “speed”

cross_correlation_coefficientbool, optional

If True, a normalization is applied to the CCH to obtain the cross-correlation coefficient function ranging from -1 to 1 according to Equation (5.10) in (Eggermont, 2010). See Notes. Default: False

Returns:
cch_resultneo.AnalogSignal

Containing the cross-correlation histogram between binned_spiketrain_i and binned_spiketrain_j.

Offset bins correspond to correlations at delays equivalent to the differences between the spike times of binned_spiketrain_i and those of binned_spiketrain_j: an entry at positive lag corresponds to a spike in binned_spiketrain_j following a spike in binned_spiketrain_i bins to the right, and an entry at negative lag corresponds to a spike in binned_spiketrain_i following a spike in binned_spiketrain_j.

To illustrate this definition, consider two spike trains with the same t_start and t_stop: binned_spiketrain_i (‘reference neuron’) : 0 0 0 0 1 0 0 0 0 0 0 binned_spiketrain_j (‘target neuron’) : 0 0 0 0 0 0 0 1 0 0 0 Here, the CCH will have an entry of 1 at lag=+3.

Consistent with the definition of neo.AnalogSignals, the time axis represents the left bin borders of each histogram bin. For example, the time axis might be: np.array([-2.5 -1.5 -0.5 0.5 1.5]) * ms

lagsnp.ndarray

Contains the IDs of the individual histogram bins, where the central bin has ID 0, bins to the left have negative IDs and bins to the right have positive IDs, e.g.,: np.array([-3, -2, -1, 0, 1, 2, 3])

Notes

  1. The Eq. (5.10) in (Eggermont, 2010) is valid for binned spike trains with at most one spike per bin. For a general case, refer to the implementation of _covariance_sparse().

  2. Alias: cch

Examples

Plot the cross-correlation histogram between two Poisson spike trains

>>> import elephant
>>> import quantities as pq
>>> import numpy as np
>>> from elephant.conversion import BinnedSpikeTrain
>>> from elephant.spike_train_generation import StationaryPoissonProcess
>>> from elephant.spike_train_correlation import cross_correlation_histogram  # noqa
>>> np.random.seed(1)
>>> binned_spiketrain_i = BinnedSpikeTrain(
...        StationaryPoissonProcess(
...            10. * pq.Hz, t_start=0 * pq.ms,
...             t_stop=5000 * pq.ms).generate_spiketrain(),
...        bin_size=5. * pq.ms)
>>> binned_spiketrain_j = BinnedSpikeTrain(
...        StationaryPoissonProcess(
...            10. * pq.Hz, t_start=0 * pq.ms,
...             t_stop=5000 * pq.ms).generate_spiketrain(),
...        bin_size=5. * pq.ms)

>>> cc_hist, lags = cross_correlation_histogram(
...        binned_spiketrain_i, binned_spiketrain_j, window=[-10, 10],
...        border_correction=False,
...        binary=False, kernel=None)
>>> print(cc_hist.flatten()) 
[ 5.  3.  3.  2.  4.  0.  1.  5.  3.  4.  2.  2.  2.  5.
  1.  2.  4.  2. -0.  3.  3.] dimensionless

>>> lags 
array([-10,  -9,  -8,  -7,  -6,  -5,  -4,  -3,  -2,  -1,
     0,   1,   2,   3,   4,   5,   6,   7,   8,   9,
    10], dtype=int32)