van_rossum_distance

van_rossum_distance#

class braintools.analysis.spike.van_rossum_distance(spike_times_1, spike_times_2, tau=1.0, t_max=None)#

Calculate van Rossum distance between two spike trains.

The van Rossum distance measures dissimilarity between spike trains by convolving each with an exponential kernel and computing the Euclidean distance between the resulting continuous functions [1].

Each spike train is convolved with kernel \(K(t) = \frac{1}{\tau}e^{-t/\tau}H(t)\) where \(H(t)\) is the Heaviside step function. The distance is:

\[D_{vR} = \sqrt{\int_0^{T} [f_1(t) - f_2(t)]^2 dt}\]

where \(f_i(t)\) is the convolved spike train.

Parameters:

  • spike_times_1 (Array | ndarray | bool | number | bool | int | float | complex | Quantity) – First spike train as a 1-D array of spike times. Entries equal to +inf are padding and are ignored, so a row of SpikeTrains.times can be passed directly.

  • spike_times_2 (Array | ndarray | bool | number | bool | int | float | complex | Quantity) – Second spike train, same convention.

  • tau (float) – Time constant of the exponential kernel. Larger values emphasize longer-term dependencies.

  • t_max (float | None) – End \(T\) of the integration window. If None, uses the largest (non-padding) spike time + 5 * tau; this default depends on the data, so t_max must be given when the spike times are traced (inside jax.jit, jax.vmap or jax.grad).

Returns:

van Rossum distance, a 0-d array (0 when both trains are empty and t_max is None).

Return type:

jax.Array

Raises:

ValueError – If t_max is None while the spike times are traced.

See also

victor_purpura_distance

Edit distance between two spike trains.

spike_distance

Time-resolved SPIKE-distance between two populations.

Notes

Convention: each spike train is convolved with the rate-normalized kernel \(K(t) = \frac{1}{\tau} e^{-t/\tau} H(t)\) and the distance is \(\sqrt{\int (f_1 - f_2)^2\, dt}\) (no extra \(1/\tau\) prefactor on the integral). Other texts use \(K(t) = e^{-t/\tau}\) with a \(1/\tau\) integral prefactor; both differ only by an overall scale.

The integral over \([0, T]\) is evaluated in closed form (one term per spike pair), so there is no quadrature error; only the deliberate truncation at t_max (default max(spike_time) + 5*tau, whose 5*tau tail leaves out less than \(e^{-10} \approx 5\cdot10^{-5}\) of the exponential) remains. Pass a larger t_max to reduce that further. Spike pairs are evaluated with vectorized array ops rather than a Python loop over spikes.

With t_max given, the function works under jax.jit and jax.vmap and is differentiable with respect to the spike times, tau and t_max (except where the distance is 0). tau, t_max and the spike times must use consistent time units.

Before version 0.4 this function returned a Python float; float(d) still works on the 0-d array.

Examples

>>> import jax
>>> import jax.numpy as jnp
>>> import braintools
>>> spikes1 = jnp.array([1.0, 3.0, 5.0])
>>> spikes2 = jnp.array([1.2, 3.2, 5.2])
>>> d = braintools.analysis.spike.van_rossum_distance(spikes1, spikes2, tau=0.5)
>>> round(float(d), 4)
1.4022
>>>
>>> # Under jit, give ``t_max``; ``+inf`` entries are padding.
>>> f = jax.jit(lambda a, b: braintools.analysis.spike.van_rossum_distance(
...     a, b, tau=0.5, t_max=10.0))
>>> d = f(jnp.array([1.0, 3.0, 5.0, jnp.inf]), spikes2)
>>> round(float(d), 4)
1.4022

References