elephant.conversion.BinnedSpikeTrain

class elephant.conversion.BinnedSpikeTrain(**kwargs)

Class which calculates a binned spike train and provides methods to transform the binned spike train to a boolean matrix or a matrix with counted time points.

A binned spike train represents the occurrence of spikes in a certain time frame. I.e., a time series like [0.5, 0.7, 1.2, 3.1, 4.3, 5.5, 6.7] is represented as [0, 0, 1, 3, 4, 5, 6]. The outcome is dependent on given parameter such as size of bins, number of bins, start and stop points.

A boolean matrix represents the binned spike train in a binary (True/False) manner. Its rows represent the number of spike trains and the columns represent the binned index position of a spike in a spike train. The calculated matrix entry containing True indicates a spike.

A matrix with counted time points is calculated the same way, but its entries contain the number of spikes that occurred in the given bin of the given spike train.

Note that with most common parameter combinations spike times can end up on bin edges. This makes the binning susceptible to rounding errors which is accounted for by moving spikes which are within tolerance of the next bin edge into the following bin. This can be adjusted using the tolerance parameter and turned off by setting tolerance=None.

Parameters:

spiketrainsneo.SpikeTrain or list of neo.SpikeTrain or np.ndarray

Spike train(s) to be binned.

bin_sizepq.Quantity, optional

Width of a time bin. Default: None

n_binsint, optional

Number of bins of the binned spike train. Default: None

t_startpq.Quantity, optional

Time of the left edge of the first bin (left extreme; included). Default: None

t_stoppq.Quantity, optional

Time of the right edge of the last bin (right extreme; excluded). Default: None

tolerancefloat, optional

Tolerance for rounding errors in the binning process and in the input data Default: 1e-8

Raises:

AttributeError

If less than 3 optional parameters are None.

TypeError

If spiketrains is an np.ndarray with dimensionality different than NxM or if type of n_bins is not an int or n_bins < 0.

ValueError

When number of bins calculated from t_start, t_stop and bin_size differs from provided n_bins or if t_stop of any spike train is smaller than any t_start or if any spike train does not cover the full [t_start, t_stop`] range.

Warns:

UserWarning

If some spikes fall outside of [t_start, t_stop] range

See also

_convert_to_binned

spike_indices

to_bool_array

to_array

Notes

There are four minimal configurations of the optional parameters which have to be provided, otherwise a ValueError will be raised: * t_start, n_bins, bin_size * t_start, n_bins, t_stop * t_start, bin_size, t_stop * t_stop, n_bins, bin_size

If spiketrains is a neo.SpikeTrain or a list thereof, it is enough to explicitly provide only one parameter: n_bins or bin_size. The t_start and t_stop will be calculated from given spiketrains (max t_start and min t_stop of `neo.SpikeTrain`s). Missing parameter will be calculated automatically. All parameters will be checked for consistency. A corresponding error will be raised, if one of the four parameters does not match the consistency requirements.

Methods

__init__(spiketrains[, bin_size, n_bins, …])	Initialize self.
binarize([copy])	Clip the internal array (no.
get_num_of_spikes([axis])	Compute the number of binned spikes.
rescale(units)	Inplace rescaling to the new quantity units.
to_array([dtype])	Returns a dense matrix, calculated from the sparse matrix, with counted time points of spikes.
to_bool_array()	Returns a matrix, in which the rows correspond to the spike trains and the columns correspond to the bins in the BinnedSpikeTrain.
to_sparse_array()	Getter for sparse matrix with time points.
to_sparse_bool_array()	Getter for boolean version of the sparse matrix, calculated from sparse matrix with counted time points.

Attributes

bin_centers	Returns each center time point of all bins between t_start and t_stop points.
bin_edges	Returns all time edges as a quantity array with n_bins bins.
bin_size
binsize
is_binary	Checks and returns True if given input is a binary input.
num_bins
shape
sparsity	Returns:
spike_indices	A list of lists for each spike train (i.e., rows of the binned matrix), that in turn contains for each spike the index into the binned matrix where this spike enters.
t_start
t_stop

property bin_centers

Returns each center time point of all bins between t_start and t_stop points.

The center of each bin of all time steps between start and stop.

Returns:

bin_edgespq.Quantity

All center edges in interval (start, stop).

property bin_edges

Returns all time edges as a quantity array with n_bins bins.

The borders of all time steps between t_start and t_stop with a step bin_size. It is crucial for many analyses that all bins have the same size, so if t_stop - t_start is not divisible by bin_size, there will be some leftover time at the end (see https://github.com/NeuralEnsemble/elephant/issues/255). The length of the returned array should match n_bins.

Returns:

bin_edgespq.Quantity

All edges in interval [t_start, t_stop] with n_bins bins are returned as a quantity array.

binarize(copy=None)

Clip the internal array (no. of spikes in a bin) to 0 (no spikes) or 1 (at least one spike) values only.

Parameters:

copybool, optional

Deprecated parameter. It has no effect.

Returns:

bst_BinnedSpikeTrainView

A view of BinnedSpikeTrain with a sparse matrix containing data clipped to `0`s and `1`s.

get_num_of_spikes(axis=None)

Compute the number of binned spikes.

Parameters:

axisint, optional

If None, compute the total num. of spikes. Otherwise, compute num. of spikes along axis. If axis is 1, compute num. of spikes per spike train (row). Default is None.

Returns:

n_spikes_per_rowint or np.ndarray

The number of binned spikes.

property is_binary

Checks and returns True if given input is a binary input. Beware, that the function does not know if the input is binary because e.g to_bool_array() was used before or if the input is just sparse (i.e. only one spike per bin at maximum).

Returns:

bool

True for binary input, False otherwise.

rescale(units)

Inplace rescaling to the new quantity units.

Parameters:

unitspq.Quantity or str

New quantity units.

Raises:

TypeError

If the input units are not quantities.

property sparsity

Returns:

float

Matrix sparsity defined as no. of nonzero elements divided by the matrix size

property spike_indices

A list of lists for each spike train (i.e., rows of the binned matrix), that in turn contains for each spike the index into the binned matrix where this spike enters.

In contrast to to_sparse_array().nonzero(), this function will report two spikes falling in the same bin as two entries.

Examples

>>> import elephant.conversion as conv
>>> import neo as n
>>> import quantities as pq
>>> st = n.SpikeTrain([0.5, 0.7, 1.2, 3.1, 4.3, 5.5, 6.7] * pq.s,
...                   t_stop=10.0 * pq.s)
>>> x = conv.BinnedSpikeTrain(st, n_bins=10, bin_size=1 * pq.s,
...                           t_start=0 * pq.s)
>>> print(x.spike_indices)
[[0, 0, 1, 3, 4, 5, 6]]
>>> print(x.sparse_matrix.nonzero()[1])
[0 1 3 4 5 6]
>>> print(x.to_array())
[[2, 1, 0, 1, 1, 1, 1, 0, 0, 0]]

to_array(dtype=None)

Returns a dense matrix, calculated from the sparse matrix, with counted time points of spikes. The rows correspond to spike trains and the columns correspond to bins in a BinnedSpikeTrain. Entries contain the count of spikes that occurred in the given bin of the given spike train.

Returns:

matrixnp.ndarray

Matrix with spike counts. Columns represent the index positions of the binned spikes and rows represent the spike trains.

See also

scipy.sparse.csr_matrix

scipy.sparse.csr_matrix.toarray

Examples

>>> import elephant.conversion as conv
>>> import neo as n
>>> import quantities as pq
>>> a = n.SpikeTrain([0.5, 0.7, 1.2, 3.1, 4.3, 5.5, 6.7] * pq.s,
...                  t_stop=10.0 * pq.s)
>>> x = conv.BinnedSpikeTrain(a, n_bins=10, bin_size=1 * pq.s,
...                           t_start=0 * pq.s)
>>> print(x.to_array())
[[2 1 0 1 1 1 1 0 0 0]]

to_bool_array()

Returns a matrix, in which the rows correspond to the spike trains and the columns correspond to the bins in the BinnedSpikeTrain. True indicates a spike in given bin of given spike train and False indicates lack of spikes.

Returns:

numpy.ndarray

Returns a dense matrix representation of the sparse matrix, with True indicating a spike and False indicating a no-spike. The columns represent the index position of the bins and rows represent the number of spike trains.

See also

scipy.sparse.csr_matrix

scipy.sparse.csr_matrix.toarray

Examples

>>> import elephant.conversion as conv
>>> import neo as n
>>> import quantities as pq
>>> a = n.SpikeTrain([0.5, 0.7, 1.2, 3.1, 4.3, 5.5, 6.7] * pq.s,
...                  t_stop=10.0 * pq.s)
>>> x = conv.BinnedSpikeTrain(a, n_bins=10, bin_size=1 * pq.s,
...                           t_start=0 * pq.s)
>>> print(x.to_bool_array())
[[ True  True False  True  True  True  True False False False]]

to_sparse_array()

Getter for sparse matrix with time points.

Returns:

scipy.sparse.csr_matrix

Sparse matrix, version with spike counts.

See also

scipy.sparse.csr_matrix

to_array

to_sparse_bool_array()

Getter for boolean version of the sparse matrix, calculated from sparse matrix with counted time points.

Returns:

scipy.sparse.csr_matrix

Sparse matrix, binary, boolean version.

See also

scipy.sparse.csr_matrix

to_bool_array