ezmsg.event.kernel#

Kernel abstractions for sparse event processing.

Kernels can be applied to sparse events to produce either: 1. Dense signals (via SparseKernelInserter) 2. Binned activation features (via BinnedKernelActivation)

Functions

alpha_kernel(t, sigma)[source]#

Alpha function kernel: k(t) = (t/sigma^2) * exp(-t/sigma) for t >= 0.

Peaks at t = sigma. Normalized so that integral from 0 to inf equals 1.

Parameters:

t (NDArray)
sigma (float)

Return type:

NDArray

boxcar_kernel(t, sigma)[source]#

Boxcar (rectangular) kernel: k(t) = 1/(2*sigma) for abs(t) < sigma.

Symmetric (acausal). Width is 2*sigma. Normalized so that integral equals 1.

Parameters:

t (NDArray)
sigma (float)

Return type:

NDArray

causal_boxcar_kernel(t, sigma)[source]#

Causal boxcar kernel: k(t) = 1/sigma for 0 <= t < sigma.

Normalized so that integral equals 1.

Parameters:

t (NDArray)
sigma (float)

Return type:

NDArray

exponential_kernel(t, sigma)[source]#

Causal exponential decay kernel: k(t) = exp(-t/sigma) / sigma for t >= 0.

Normalized so that integral from 0 to inf equals 1.

Parameters:

t (NDArray)
sigma (float)

Return type:

NDArray

gaussian_kernel(t, sigma)[source]#

Gaussian kernel: k(t) = exp(-t^2 / (2*sigma^2)) / (sigma * sqrt(2*pi)).

Symmetric (acausal). Normalized so that integral equals 1.

Parameters:

t (NDArray)
sigma (float)

Return type:

NDArray

Classes

class ArrayKernel(data, pre_samples=0)[source]#

Bases: Kernel

Kernel from explicit array (e.g., spike waveforms).

Parameters:

data (NDArray) – 1D array of kernel values.
pre_samples (int) – Number of samples before t=0. Default 0 (causal kernel). For a waveform centered at t=0, use pre_samples = len(data) // 2.

__init__(data, pre_samples=0)[source]#

Parameters:

data (NDArray)
pre_samples (int)

property length: int#: Total kernel length in samples.

property pre_samples: int#: Number of samples before t=0 (for acausal kernels).

property data: NDArray[float64]#: Raw kernel data array.

evaluate(t)[source]#

Evaluate kernel at time offsets.

Parameters:: t (NDArray[floating])
Return type:: NDArray[floating]

class FunctionalKernel(func, sigma, fs, truncate_at=5.0, causal=True)[source]#

Bases: Kernel

Kernel from a function (e.g., exponential decay, Gaussian).

The function should accept (t, sigma) where t is time in samples and sigma is the time constant in samples.

Parameters:

func (Callable[[NDArray, float], NDArray]) – Kernel function f(t, sigma) -> values.
sigma (float) – Time constant in seconds.
fs (float) – Sample rate in Hz (for converting sigma to samples).
truncate_at (float) – Truncate kernel at this many time constants. Default 5.0.
causal (bool) – If True, kernel is zero for t < 0. Default True.

Example

>>> kernel = FunctionalKernel(
...     func=lambda t, s: (t >= 0) * np.exp(-t / s) / s,
...     sigma=0.010,  # 10ms
...     fs=30000,
... )

__init__(func, sigma, fs, truncate_at=5.0, causal=True)[source]#

Parameters:

func (Callable[[NDArray, float], NDArray])
sigma (float)
fs (float)
truncate_at (float)
causal (bool)

property length: int#: Total kernel length in samples.

property pre_samples: int#: Number of samples before t=0 (for acausal kernels).

property sigma: float#: Time constant in seconds.

property sigma_samples: float#: Time constant in samples.

evaluate(t)[source]#

Evaluate kernel function at time offsets.

Parameters:: t (NDArray[floating])
Return type:: NDArray[floating]

class Kernel[source]#

Bases: ABC

Base class for kernels applied to sparse events.

A kernel defines a shape that gets inserted/convolved at event locations. Supports both causal (forward-looking) and acausal (symmetric) kernels.

abstract property length: int#: Total kernel length in samples.

abstract property pre_samples: int#: Number of samples before t=0 (for acausal kernels).

abstractmethod evaluate(t)[source]#

Evaluate kernel at time offsets t (in samples relative to event).

Parameters:: t (NDArray[floating]) – Array of time offsets in samples. t=0 is the event time.
Returns:: Kernel values at the given offsets.
Return type:: NDArray[floating]

property is_causal: bool#: True if kernel is zero for t < 0.

property post_samples: int#: Number of samples at and after t=0.

class MultiKernel(kernels, default_key=None)[source]#

Bases: object

Dictionary of kernels indexed by event value.

Useful when different event types (e.g., waveform IDs 1, 2, 3) should produce different kernel shapes.

Parameters:

kernels (dict[int, Kernel]) – Dictionary mapping event values to Kernel objects.
default_key (int | None) – Key to use for unknown event values. Default is first key.

__init__(kernels, default_key=None)[source]#

Parameters:

kernels (dict[int, Kernel])
default_key (int | None)

get(value)[source]#

Get kernel for event value, falling back to default.

Parameters:: value (int)
Return type:: Kernel

property max_length: int#: Maximum kernel length across all kernels.

property max_pre_samples: int#: Maximum pre_samples across all kernels.

property max_post_samples: int#: Maximum post_samples across all kernels.

property keys: list[int]#: Available kernel keys.