conversion - Data format conversions

This module allows to convert standard data representations (e.g., a spike train stored as Neo SpikeTrain object) into other representations useful to perform calculations on the data. An example is the representation of a spike train as a sequence of 0-1 values (binned spike train).

class elephant.conversion.BinnedSpikeTrain(spiketrains, binsize=None, num_bins=None, t_start=None, t_stop=None)[source]

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 columns contains Trues, which indicate a spike.

A matrix with counted time points is calculated the same way, but its columns contain the number of spikes that occurred in the spike train(s). It counts the occurrence of the timing of a spike in its respective spike train.

Parameters:
spiketrains : List of neo.SpikeTrain, a neo.SpikeTrain object, or

numpy array. Spiketrain(s)to be binned. Accepts also a matrix representation (as a list of lists or 2d ndarray) and converts it to a BinnedSpikeTrain object.

binsize : quantities.Quantity

Width of each time bin. Default is None

num_bins : int

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

t_start : quantities.Quantity

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

t_stop : quantities.Quantity

Stopping time of the last bin (right extreme; excluded). Default is None

See also

_convert_to_binned
spike_indices
to_bool_array
to_array

Notes

There are four cases the given parameters must fulfill. Each parameter must be a combination of following order or it will raise a value error: * t_start, num_bins, binsize * t_start, num_bins, t_stop * t_start, bin_size, t_stop * t_stop, num_bins, binsize

It is possible to give the SpikeTrain objects and one parameter (num_bins or binsize). The start and stop time will be calculated from given SpikeTrain objects (max start and min stop point). Missing parameter will also 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.

bin_centers

Returns each center time point of all bins between start and stop points.

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

Returns:
bin_edges : quantities.Quantity array

All center edges in interval (start, stop) are returned as a quantity array.

bin_edges

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

The borders of all time steps between start and stop [start, stop] with:attr:num_bins bins are regarded as edges. The border of the last bin is included.

Returns:
bin_edges : quantities.Quantity array

All edges in interval [start, stop] with num_bins bins are returned as a quantity array.

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).

remove_stored_array(self)[source]

Removes the matrix with counted time points from memory.

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, num_bins=10, binsize=1 * pq.s, t_start=0 * pq.s)
>>> print(x.spike_indices)
[[0, 0, 1, 3, 4, 5, 6]]
>>> print(x.to_sparse_array().nonzero()[1])
[0 1 3 4 5 6]
to_array(self, store_array=False)[source]

Returns a dense matrix, calculated from the sparse matrix with counted time points, which rows represents the number of spike trains and the columns represents the binned index position of a spike in a spike train. The matrix columns contain the number of spikes that occurred in the spike train(s). If the boolean store_array is set to True the matrix will be stored in memory.

Returns:
matrix : numpy.ndarray

Matrix with spike times. Columns represent the index position of the binned spike 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
>>> 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, num_bins=10, binsize=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(self)[source]

Returns a dense matrix (scipy.sparse.csr_matrix), which rows represent the number of spike trains and the columns represent the binned index position of a spike in a spike train. The matrix columns contain True, which indicate a spike and False for non spike.

Returns:
bool matrix : numpy.ndarray

Returns a dense matrix representation of the sparse matrix, with True indicating a spike and False* for non spike. The Trues in the columns represent the index position of the spike in the spike train 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, num_bins=10, binsize=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(self)[source]

Getter for sparse matrix with time points.

Returns:
matrix: scipy.sparse.csr_matrix

Sparse matrix, counted version.

See also

scipy.sparse.csr_matrix
to_array
to_sparse_bool_array(self)[source]

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

Returns:
matrix: scipy.sparse.csr_matrix

Sparse matrix, binary, boolean version.

See also

scipy.sparse.csr_matrix
to_bool_array
elephant.conversion.binarize(spiketrain, sampling_rate=None, t_start=None, t_stop=None, return_times=None)[source]

Return an array indicating if spikes occured at individual time points.

The array contains boolean values identifying whether one or more spikes happened in the corresponding time bin. Time bins start at t_start and end at t_stop, spaced in 1/sampling_rate intervals.

Accepts either a Neo SpikeTrain, a Quantity array, or a plain NumPy array. Returns a boolean array with each element being the presence or absence of a spike in that time bin. The number of spikes in a time bin is not considered.

Optionally also returns an array of time points corresponding to the elements of the boolean array. The units of this array will be the same as the units of the SpikeTrain, if any.

Parameters:
spiketrain : Neo SpikeTrain or Quantity array or NumPy array

The spike times. Does not have to be sorted.

sampling_rate : float or Quantity scalar, optional

The sampling rate to use for the time points. If not specified, retrieved from the sampling_rate attribute of spiketrain.

t_start : float or Quantity scalar, optional

The start time to use for the time points. If not specified, retrieved from the t_start attribute of spiketrain. If that is not present, default to 0. Any value from spiketrain below this value is ignored.

t_stop : float or Quantity scalar, optional

The start time to use for the time points. If not specified, retrieved from the t_stop attribute of spiketrain. If that is not present, default to the maximum value of sspiketrain. Any value from spiketrain above this value is ignored.

return_times : bool

If True, also return the corresponding time points.

Returns:
values : NumPy array of bools

A True value at a particular index indicates the presence of one or more spikes at the corresponding time point.

times : NumPy array or Quantity array, optional

The time points. This will have the same units as spiketrain. If spiketrain has no units, this will be an NumPy array.

Raises:
TypeError

If spiketrain is a NumPy array and t_start, t_stop, or sampling_rate is a Quantity..

ValueError

t_start and t_stop can be inferred from spiketrain if not explicitly defined and not an attribute of spiketrain. sampling_rate cannot, so an exception is raised if it is not explicitly defined and not present as an attribute of spiketrain.

Notes

Spike times are placed in the bin of the closest time point, going to the higher bin if exactly between two bins.

So in the case where the bins are 5.5 and 6.5, with the spike time being 6.0, the spike will be placed in the 6.5 bin.

The upper edge of the last bin, equal to t_stop, is inclusive. That is, a spike time exactly equal to t_stop will be included.

If spiketrain is a Quantity or Neo SpikeTrain and t_start, t_stop or sampling_rate is not, then the arguments that are not quantities will be assumed to have the same units as spiketrain.