GaborFilterbank¶

gabor ¶

Gabor Filterbank and RSF Extraction

Implements 2D Gabor filters for spectro-temporal modulation analysis, following Bellur & Elhilali (2017).

Pipeline: 1. Cached: 2D Gabor kernels tuned to (rate, scale) pairs, plus their FFTs 2. Hot path: FFT input spectrogram → broadcast multiply → batch IFFT → magnitude → frame integration

Memory-adaptive: at high resolutions the kernel FFT cache can exceed GPU memory. When it would, falls back to streaming mode (kernels are rebuilt and FFT'd per chunk inside the compute loop). Slower per call but works on any GPU, including lower-memory devices like the Jetson Orin Nano.

PARAM_OPTIONS `module-attribute` ¶

PARAM_OPTIONS = {'sigma_t': array([1 / 1.4, 1 / 1.6, 1 / 1.8, 1 / 2.0, 1 / 2.2, 1 / 2.4, 1 / 2.6]), 'sigma_f': array([1 / 1.4, 1 / 1.6, 1 / 1.8, 1 / 2.0, 1 / 2.2, 1 / 2.4, 1 / 2.6]), 'theta': radians(array([-4.5, -3.0, -1.5, 0.0, 1.5, 3.0, 4.5])), 'alpha': array([0.7, 0.8, 0.9, 1.0, 1.1, 1.2, 1.3])}

Per-kernel Gabor parameter options for adaptive (GA) tuning.

Each entry is a discrete grid of candidate values. A genetic algorithm or other tuner emits a 4-column integer array indexing into these grids, which :meth:GaborFilterbank.compute decodes per kernel.

DEFAULT_PARAM_IDX `module-attribute` ¶

DEFAULT_PARAM_IDX = 3

Index into each :data:PARAM_OPTIONS grid that selects the canonical (untuned) Gabor parameters used by the default cached path.

GaborFilterbank ¶

GaborFilterbank(config: Config | None = None)

2D Gabor filterbank for spectro-temporal modulation analysis.

Each filter is tuned to a (rate, scale) pair, where rate is the temporal modulation in Hz and scale is the spectral modulation in cycles/octave.

Dispatch is memory-adaptive. If the full kernel-FFT cache fits in the available memory budget (see :data:_CACHE_MEMORY_BUDGET), the cached batched path is used. Otherwise the filterbank emits a :class:ResourceWarning and falls back to a streaming path that rebuilds and FFTs kernels per chunk — slower per call, but works at arbitrary resolution and on low-memory devices.

PARAMETER	DESCRIPTION
`config`	Configuration object. If `None`, uses defaults. TYPE: `Config` DEFAULT: `None`

ATTRIBUTE	DESCRIPTION
`rates`	Temporal modulation rates in Hz, length `n_rates`. TYPE: `ndarray`
`scales`	Spectral modulation scales in cycles/octave, length `n_scales`. TYPE: `ndarray`
`use_gpu`	Whether GPU acceleration is active. TYPE: `bool`

RAISES	DESCRIPTION
`ValueError`	If `config.resolution` is not one of the keys in :data:`RESOLUTION_MULTIPLIERS`.

WARNS	DESCRIPTION
`ResourceWarning`	At construction time if the chosen resolution produces more than :data:`_KERNEL_COUNT_WARN_THRESHOLD` kernels (compute time scales linearly with the kernel count regardless of memory mode).

compute_device ¶

compute_device(spec_device, params: ndarray | None = None)

Process a device-resident spectrogram and return RSF on device.

Hot path. Memory-adaptive dispatch:

Default mode (params is None): try to cache kernel FFTs. If they fit, use the batched cached path. If not, fall back to streaming.
GA mode (params given): always stream. Kernels change per call, so caching has no benefit, and this avoids GA's own OOM risk at high resolution.

PARAMETER	DESCRIPTION
`spec_device`	Spectrogram of shape `(n_time, n_freq)` already on the active backend. TYPE: `ndarray or ndarray`
`params`	Per-kernel parameter indices of shape `(n_kernels, 4)`, decoded via :data:`PARAM_OPTIONS`. If omitted, the default (untuned) Gabor parameters are used. TYPE: `ndarray` DEFAULT: `None`

RETURNS	DESCRIPTION
`ndarray or ndarray`	RSF tensor of shape `(n_frames, n_rates, n_scales, n_freq)` on the active backend.

compute ¶

compute(spectrogram: Spectrogram, params: ndarray | None = None) -> RSF

Compute the RSF representation from a spectrogram, returning a host dataclass.

Wraps :meth:compute_device with the necessary input transfer and a host copy of the result.

PARAMETER	DESCRIPTION
`spectrogram`	Auditory spectrogram. If a raw 2D array is passed, it is assumed to be in `(n_freq, n_time)` orientation and the frequency axis is filled with placeholder integer indices. TYPE: `Spectrogram or ndarray`
`params`	Per-kernel parameter indices of shape `(n_kernels, 4)`. See :meth:`compute_device`. TYPE: `ndarray` DEFAULT: `None`

RETURNS	DESCRIPTION
`RSF`	Host-side RSF with `data` shape `(n_frames, n_rates, n_scales, n_freq)` and time, rate, scale, and frequency axes.