braintools.analysis.spike.spike_triggered_average

braintools.analysis.spike.spike_triggered_average#

braintools.analysis.spike.spike_triggered_average(trains, signal, dt, window)#

Average a sampled signal around the spikes of every neuron.

For neuron \(n\) with usable spikes \(t_1, \dots, t_m\),

\[\mathrm{STA}_n[l] = \frac{1}{m} \sum_{k=1}^{m} x[s_k + l], \qquad l = 0, \dots, L - 1,\]

where \(s_k = \lfloor (t_k - t_\text{before} - t_0) / dt \rfloor\) is the first sample of the window of spike \(k\) and \(L = \lceil (t_\text{before} + t_\text{after}) / dt \rceil\).

Parameters:

  • trains (SpikeTrains) – Spike trains with N neurons.

  • signal (Any) – Signal of shape (T, ...): sample i is at time trains.t_start + i * dt. Shared by all neurons.

  • dt (Any) – Sampling interval, static and positive. A plain number is in milliseconds, like the other spike-time arguments.

  • window (Sequence[Any]) – (t_before, t_after): the average spans [-t_before, t_after) around each spike (a positive t_before reaches before the spike). Static; plain numbers are in milliseconds.

Return type:

Tuple[Any, Any]

Returns:

  • sta (jax.Array or Quantity) – Averages of shape (N, L) + signal.shape[1:], a Quantity when signal is one. nan for a neuron without a usable spike.

  • lags (jax.Array or Quantity) – Nominal lag of every sample, -t_before + l * dt, shape (L,); a Quantity when the spike times carry units, else milliseconds.

Raises:

  • TypeError – If trains is not a SpikeTrains, or dt/window are traced.

  • ValueError – If signal is a scalar, dt is not positive, or the window has non-positive length.

See also

psth

Event-aligned spike histograms.

braintools.spike.SpikeTrains.from_dense

Build the input from a raster.

Notes

A spike is used only if its whole window lies inside the signal, t - t_before >= t_0 and t + t_after <= t_0 + T dt; other spikes, e.g. near the start of the recording, are excluded [1].

This matches elephant.sta.spike_triggered_average(signal, trains, window=(-t_before, t_after)): Elephant gives the window as signed (start, stop) offsets, while here t_before is the (positive) time before the spike.

The windows are gathered with O(N K L D) memory, where D is the number of signal channels. Works under jax.jit and jax.vmap with static dt and window, and is differentiable with respect to signal.

References

Examples

>>> import brainunit as u
>>> import jax.numpy as jnp
>>> from braintools.spike import SpikeTrains
>>> from braintools.analysis.spike import spike_triggered_average
>>> signal = jnp.arange(10.) * u.mV
>>> raster = jnp.zeros((10, 1)).at[jnp.array([1, 4, 6]), 0].set(1)
>>> st = SpikeTrains.from_dense(raster, dt=1. * u.ms)
>>> sta, lags = spike_triggered_average(st, signal, dt=1. * u.ms,
...                                     window=(2. * u.ms, 1. * u.ms))
>>> sta     # the spike at 1 ms is excluded
Quantity([[3. 4. 5.]], "mV")
>>> lags
Quantity([-2. -1.  0.], "ms")