spiketools.transforms

  1"""Transform spike trains or time-resolved signals onto new time axes.
  2
  3Examples
  4--------
  5Shared example setup used throughout the documentation:
  6
  7```python
  8import numpy as np
  9
 10from spiketools import gamma_spikes, gaussian_kernel, kernel_rate, time_warp
 11
 12np.random.seed(0)
 13rates = np.array([6.0] * 10 + [5.6, 6.3, 5.9, 6.5, 5.8, 6.1, 5.7, 6.4, 6.0, 5.5], dtype=float)
 14orders = np.array([0.2] * 10 + [1.0, 2.0, 2.0, 3.0, 1.0, 2.0, 3.0, 2.0, 1.0, 3.0], dtype=float)
 15spiketimes = gamma_spikes(rates=rates, order=orders, tlim=[0.0, 5000.0], dt=1.0)
 16
 17kernel = gaussian_kernel(25.0, dt=1.0)
 18rates, rate_time = kernel_rate(spiketimes, kernel, tlim=[0.0, 5000.0], dt=1.0, pool=True)
 19warped_spikes = time_warp(spiketimes[0], rate_time, rate_time)
 20```
 21"""
 22
 23from __future__ import annotations
 24
 25import pylab
 26
 27__all__ = [
 28    "resample",
 29    "time_stretch",
 30    "time_warp",
 31]
 32
 33
 34def time_warp(events, told, tnew):
 35    """Map event times from one timeline onto another by interpolation.
 36
 37    Parameters
 38    ----------
 39    events:
 40        Event times to transform.
 41    told:
 42        Original reference time axis.
 43    tnew:
 44        New reference axis aligned to `told`.
 45
 46    Returns
 47    -------
 48    np.ndarray
 49        Warped event times. Values outside the interpolation range become `nan`.
 50
 51    Examples
 52    --------
 53    >>> time_warp([0.0, 5.0, 10.0], [0.0, 10.0], [0.0, 20.0]).tolist()
 54    [0.0, 10.0, 20.0]
 55    """
 56    return pylab.interp(events, told, tnew, left=pylab.nan, right=pylab.nan)
 57
 58
 59def time_stretch(spiketimes, stretchstart, stretchend, endtime=None):
 60    """Stretch trial-wise spike times between two markers to a common duration.
 61
 62    Parameters
 63    ----------
 64    spiketimes:
 65        Canonical spike representation. The function modifies and returns this
 66        array in place.
 67    stretchstart:
 68        One start time per trial.
 69    stretchend:
 70        One end time per trial.
 71    endtime:
 72        Common target end time. Defaults to the mean of `stretchend`.
 73
 74    Examples
 75    --------
 76    >>> spikes = pylab.array([[1.0, 3.0, 2.0], [0.0, 0.0, 1.0]])
 77    >>> stretched = time_stretch(spikes.copy(), pylab.array([0.0, 0.0]), pylab.array([4.0, 2.0]), endtime=4.0)
 78    >>> stretched[0].tolist()
 79    [1.0, 3.0, 4.0]
 80    """
 81    if endtime is None:
 82        endtime = stretchend.mean()
 83
 84    trials = pylab.unique(spiketimes[1, :])
 85
 86    for i, trial in enumerate(trials):
 87        trialmask = spiketimes[1, :] == trial
 88        trialspikes = spiketimes[0, trialmask]
 89        trialspikes -= stretchstart[i]
 90        se = stretchend[i] - stretchstart[i]
 91        trialspikes /= se
 92        trialspikes *= endtime - stretchstart[i]
 93        trialspikes += stretchstart[i]
 94        spiketimes[0, trialmask] = trialspikes
 95
 96    return spiketimes
 97
 98
 99def resample(vals, time, new_time):
100    """Interpolate a time-resolved signal onto a new time axis.
101
102    Parameters
103    ----------
104    vals:
105        Values sampled on `time`.
106    time:
107        Original sampling points.
108    new_time:
109        Target sampling points.
110
111    Examples
112    --------
113    >>> resample([0.0, 1.0], [0.0, 2.0], [0.0, 1.0, 2.0]).tolist()
114    [0.0, 0.5, 1.0]
115    """
116    if len(vals) > 0:
117        return pylab.interp(new_time, time, vals, right=pylab.nan, left=pylab.nan)
118    return pylab.ones(new_time.shape) * pylab.nan