Bens Spiker Algorithm

bens_spiker(signal: ndarray, window_length: int, cutoff: float | ndarray, threshold: float | int | list[float, int] | ndarray, width: int | None = None, window_type: Literal['barthann', 'brthan', 'bth', 'bartlett', 'bart', 'brt', 'blackman', 'black', 'blk', 'blackmanharris', 'blackharr', 'bkh', 'bohman', 'bman', 'bmn', 'boxcar', 'box', 'ones', 'rect', 'rectangular', 'cosine', 'halfcosine', 'exponential', 'poisson', 'flattop', 'flat', 'flt', 'hamming', 'hamm', 'ham', 'hann', 'han', 'lanczos', 'sinc', 'nuttall', 'nutl', 'nut', 'parzen', 'parz', 'par', 'taylor', 'taylorwin', 'triangle', 'triang', 'tri', 'tukey', 'tuk'] = 'hann', pass_zero: bool | str = True, scale: bool = True, fs: float | None = None) → tuple[ndarray, ndarray, ndarray][source]

Perform Ben’s Spiker (BSA) encoding on the input signal.

BSA is an efficient algorithm for converting an analog (positive-valued) signal into a unipolar spike train from which the original signal can be well reconstructed via convolution with the same FIR filter used during encoding. The method iteratively detects spike locations by comparing two cumulative error metrics over a sliding segment of length equal to the FIR filter:

  • error1: sum of absolute differences between the current signal segment and the filter coefficients

  • error2: sum of absolute values of the current signal segment

A positive spike (+1) is emitted at time t if error1 ≤ error2 - threshold. When a spike is detected, the filter is subtracted from the corresponding signal segment, removing the detected pattern for subsequent iterations.

Note

  • BSA requires non-negative input signals. The function automatically shifts the signal by its minimum value (per feature) if negative values are present.

  • The FIR filter is designed using scipy.signal.firwin with the specified cutoff, window type, etc.

  • When the maximum amplitute of the signal is greater than 1, filter coefficients are automatically scaled up (sum ≈ 2 × max amplitude) for improved dynamic range and reduced saturation (recommended practice).

  • For multi-feature signals, the same filter shape is applied across all features, but scaling is performed independently per feature based on its amplitude.

Refer to the Ben’s Spiker Algorithm (BSA) Encoding for a detailed explanation of the Ben’s Spiker algorithm.

Code Example:

import numpy as np
from spikify.encoders.temporal.deconvolution import bens_spiker
signal = np.array([0.1, 0.2, 0.8, 0.95, 0.5, 0.3, 0.1])
window_length = 3
threshold = 0.1
cutoff = 0.1
encoded_signal, fir_coeffs, shift = bens_spiker(signal, window_length, cutoff, threshold)
Parameters:

  • signal (numpy.ndarray) – Input signal to encode (1D or 2D: time × features or channels).

  • window_length (int) – Length of the FIR filter (number of coefficients).

  • cutoff (float | numpy.ndarray) – Cutoff frequency(ies) for the FIR filter design (normalized 0 to 1, where 1 = Nyquist). Scalar or an array of cutoff frequencies (that is, band edges).

  • threshold (float | int | list[float | int] | numpy.ndarray) – Threshold factor for spike detection. Scalar or per-feature sequence.

  • width (int | None) – Transition width for FIR filter design (optional, used with certain window types).

  • window_type (str) – Window function for FIR filter design (e.g., ‘hann’, ‘hamming’, ‘blackman’, ‘boxcar’).

  • pass_zero (bool | str) – Whether the filter should be low-pass (True) or high-pass (False/’highpass’).

  • scale (bool) – Set to True to scale the coefficients so that the frequency response is exactly unity at a certain frequency.

  • fs (float | None) – Sampling frequency (used for physical frequency units in cutoff; optional).

Returns:

  • spikes: A numpy array representing the encoded spike train. (values in {0, +1})

  • fir_bank: Final filter coefficients used, shape (window_length, features or channels).

  • shift: Per-feature shift values subtracted to make signal non-negative, shape (features or channels,).

Return type:

tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray]

Raises:

ValueError – If the input signal is empty or if the threshold dimensions do not match the signal feature dimensions or if the window_length is greater than the signal lenght.