elephant.conversion module — Elephant 0.5.0 documentation

# elephant.conversion module

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)

  Bases: `object`

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

  Attributes

  Methods

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

  `remove_stored_array`()

    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`(store_array=False)

    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`()

    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`()

    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`()

    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)

  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.