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 or a neo.SpikeTrain object
Spiketrain(s)to be binned.
- 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
orbinsize
). 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.
-
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
(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
()[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
()[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
()[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.