elephant.conversion.BinnedSpikeTrain¶
-
class
elephant.conversion.
BinnedSpikeTrain
(spiketrains, bin_size=None, n_bins=None, t_start=None, t_stop=None, tolerance=1e-08, sparse_format='csr')[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 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
- sparse_format{‘csr’, ‘csc’}, optional
The sparse matrix format. By default, CSR format is used to perform slicing and computations efficiently. Default: ‘csr’
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
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. copy
()Copies the binned sparse matrix and returns a view. get_num_of_spikes
([axis])Compute the number of binned spikes. rescale
(units)Inplace rescaling to the new quantity units. time_slice
([t_start, t_stop, copy])Returns a view or a copied view of currently binned spike trains with (t_start, t_stop)
time slice.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. to_spike_trains
([spikes, as_array, …])Generate spike trains from the binned spike train object. Attributes
bin_centers
Returns each center time point of all bins between t_start
andt_stop
points.bin_edges
Returns all time edges as a quantity array with n_bins
bins.bin_size
Bin size quantity. binsize
Deprecated in favor of bin_size
.is_binary
Returns True if the sparse matrix contains binary values only. num_bins
Deprecated in favor of n_bins
.shape
The shape of the sparse matrix. sparsity
The sparsity of the sparse matrix computed as the no. 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_start quantity; spike times below this value have been ignored. t_stop
t_stop quantity; spike times above this value have been ignored. -
__getitem__
(item)[source]¶ Returns a binned slice view of itself; t_start and t_stop will be set accordingly to the second slicing argument, if any.
Parameters: - itemint or slice or tuple
Spike train and bin index slicing, passed to
self.sparse_matrix
.
Returns: - BinnedSpikeTrainView
A slice of itself that carry the original data. Any changes to the returned binned sparse matrix will affect the original data.
-
__setitem__
(key, value)[source]¶ Changes the values of
self.sparse_matrix
according to key and value. A shortcut toself.sparse_matrix[key] = value
.Parameters: - keyint or list or tuple or slice
The binned sparse matrix keys (axes slice) to change.
- valueint or list or tuple or slice
New values of the sparse matrix selection.
-
property
bin_centers
¶ Returns each center time point of all bins between
t_start
andt_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
andt_stop
with a stepbin_size
. It is crucial for many analyses that all bins have the same size, so ift_stop
-t_start
is not divisible bybin_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 matchn_bins
.Returns:
-
property
bin_size
¶ Bin size quantity.
-
binarize
(copy=True)[source]¶ 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
If True, a shallow copy - a view of BinnedSpikeTrain - is returned with the data array filled with zeros and ones. Otherwise, the binarization (clipping) is done in-place. A shallow copy means that
indices
andindptr
of a sparse matrix is shared with the original sparse matrix. Only the data is copied. If you want to perform a deep copy, callBinnedSpikeTrain.copy()
prior to binarizing. Default: True
Returns: - bstBinnedSpikeTrain or BinnedSpikeTrainView
A (view of) BinnedSpikeTrain with the sparse matrix data clipped to zeros and ones.
-
copy
()[source]¶ Copies the binned sparse matrix and returns a view. Any changes to the copied object won’t affect the original object.
Returns: - BinnedSpikeTrainView
A copied view of itself.
-
get_num_of_spikes
(axis=None)[source]¶ 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
¶ Returns True if the sparse matrix contains binary values only. Beware, that the function does not know if the input was 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.
-
property
num_bins
¶ Deprecated in favor of
n_bins
.
-
rescale
(units)[source]¶ 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
shape
¶ The shape of the sparse matrix.
-
property
sparsity
¶ The sparsity of the sparse matrix computed as the no. of nonzero elements divided by the matrix size.
Returns: - float
-
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 self.sparse_matrix.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]]
-
property
t_start
¶ t_start quantity; spike times below this value have been ignored.
-
property
t_stop
¶ t_stop quantity; spike times above this value have been ignored.
-
time_slice
(t_start=None, t_stop=None, copy=False)[source]¶ Returns a view or a copied view of currently binned spike trains with
(t_start, t_stop)
time slice. Only valid (fully overlapping) bins are sliced.Parameters: - t_start, t_stoppq.Quantity or None, optional
Start and stop times or Nones. Default: None
- copybool, optional
Copy the sparse matrix or not. Default: False
Returns: - BinnedSpikeTrainView
A time slice of itself.
-
to_array
(dtype=None)[source]¶ 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
()[source]¶ 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
()[source]¶ Getter for sparse matrix with time points. Deprecated in favor of
sparse_matrix
.Returns: - scipy.sparse.csr_matrix or scipy.sparse.csc_matrix
Sparse matrix, version with spike counts.
See also
scipy.sparse.csr_matrix
to_array
-
to_sparse_bool_array
()[source]¶ Getter for boolean version of the sparse matrix, calculated from sparse matrix with counted time points.
Returns: - scipy.sparse.csr_matrix or scipy.sparse.csc_matrix
Sparse matrix, binary, boolean version.
See also
scipy.sparse.csr_matrix
to_bool_array
-
to_spike_trains
(spikes='random', as_array=False, annotate_bins=False)[source]¶ Generate spike trains from the binned spike train object. This function is inverse to binning such that
BinnedSpikeTrain(binned_st.to_spike_trains()) == binned_st
The object bin size is stored in resulting
spiketrain.annotations['bin_size']
.Parameters: - spikes{“left”, “center”, “random”}, optional
Specifies how to generate spikes inside bins.
- “left”: align spikes from left to right to have equal inter-
spike interval;
- “center”: align spikes around center to have equal inter-spike
interval;
- “random”: generate spikes from a homogenous Poisson process;
it’s the fastest mode.
Default: “random”
- as_arraybool, optional
If True, numpy arrays are returned; otherwise, wrap the arrays in neo.SpikeTrain. Default: False
- annotate_binsbool, optional
If as_array is False, this flag allows to include the bin index in resulting
spiketrain.array_annotations['bins']
. Default: False
Returns: - spiketrainslist of neo.SpikeTrain
A list of spike trains - one possible realisation of spiketrains that could have been used as the input to BinnedSpikeTrain.