ezmsg.sigproc.multibandpow#

Multi-band envelope power from an analytic FIR filterbank.

Pipeline: analytic filterbank (band-pass and Hilbert in one complex convolution per band) -> envelope |z| -> [square] -> mean over fixed-duration bins -> [log10]. A (time, ch) input gives a (time, ch, band) output, with time binned.

Unlike squaring a real band-passed signal, the envelope carries no ripple at twice the carrier, so the bin mean is the band’s power at any bin size.

Functions

design_analytic_kernels(settings, fs)[source]#

One complex, linear-phase kernel per band: a Kaiser low-pass prototype of cutoff (hi - lo) / 2 modulated to the band centre and doubled, so |output| is the amplitude of an in-band sinusoid.

Parameters:
Return type:

list[NDArray]

Classes

class AnalyticFilterbankState[source]#

Bases: object

axis: str = ''#
filterbank: FilterbankTransformer | None = None#
class AnalyticFilterbankTransformer(*args, **kwargs)[source]#

Bases: BaseStatefulTransformer[MultiBandEnvelopePowerSettings, AxisArray, AxisArray, AnalyticFilterbankState]

First stage of MultiBandEnvelopePowerTransformer: designs the analytic kernels from the sample rate at reset and applies them, delay-compensated. Output is complex, with the input’s dims followed by band.

flush(message=None)[source]#

Process message if given, then release what BUFFERED start-up still holds (see flush()).

Parameters:

message (AxisArray | None)

Return type:

AxisArray | None

class EnvelopePowerOutput(*values)[source]#

Bases: OptionsEnum

What MultiBandEnvelopePowerTransformer reports per bin.

POWER = 'Power'#

Mean of the squared envelope, mean(a**2).

AMPLITUDE = 'Amplitude'#

Mean of the envelope, mean(a).

LOG_POWER = 'Log10 Power'#

log10(mean(a**2)).

class MultiBandEnvelopePower(*args, settings=None, **kwargs)[source]#

Bases: BaseTransformerUnit[MultiBandEnvelopePowerSettings, AxisArray, AxisArray, MultiBandEnvelopePowerTransformer]

Parameters:

settings (Settings | None)

SETTINGS#

alias of MultiBandEnvelopePowerSettings

class MultiBandEnvelopePowerSettings(bands, transition_ratio=0.5, stopband_attenuation=60.0, bin_duration=0.02, fractional=True, output=EnvelopePowerOutput.POWER, min_phase=MinPhaseMode.NONE, startup=StartupMode.CONSTANT, materialize=MaterializeMode.ASYNC)[source]#

Bases: Settings

Settings for MultiBandEnvelopePowerTransformer.

Parameters:
bands: list[tuple[float, float]]#

(lo, hi) band limits in Hz, at the filter’s -6 dB (half-amplitude) points, so adjacent bands cross over where their amplitude responses sum to one. Each band needs 0 < lo - w/2 and hi + w/2 < fs/2, with w its transition width (see transition_ratio); otherwise its one-sided kernel would pass negative frequencies, and reset raises ValueError.

transition_ratio: float = 0.5#

Transition width of each band’s filter, as a fraction of that band’s width, in (0, 1]. The default puts a flat pass-band over the central half of the band. Kernel length, and so delay, scales as 1 / (transition_ratio * (hi - lo)): the narrowest band sets the delay. A wide band’s transition reaches into a narrower neighbour: with the default, 13-30 Hz passes 0.5 % of the power of a 10.5 Hz sinusoid. Lower it for sharper edges at the cost of longer kernels.

stopband_attenuation: float = 60.0#

Stop-band attenuation in dB of the Kaiser-window design (scipy.signal.kaiserord). The pass-band ripple is the same fraction, so 60 dB keeps the gain within 0.1 %.

bin_duration: float = 0.02#

Output bin duration in seconds. See BinnedAggregateSettings.bin_duration.

fractional: bool = True#

See BinnedAggregateSettings.fractional.

output: EnvelopePowerOutput = 'Power'#

Power (mean of a**2), amplitude (mean of a) or log10 power, where a is the envelope. A sinusoid of amplitude a in a band reports a**2 power.

min_phase: MinPhaseMode = 'No kernel modification'#

Passed to FilterbankSettings.min_phase; the bands are always aligned on one delay (compensate_delay=True). NONE keeps every kernel linear phase: alignment across bands is exact and the common delay is half the narrowest band’s kernel. HOMOMORPHICFULL converts only the bands that would set the common delay to minimum phase, for lower latency; their delay is then frequency dependent, so alignment is approximate. HILBERT and HOMOMORPHIC raise: complex kernels do not support the former, and the latter halves the magnitude response in dB.

startup: StartupMode = "Constant pre-history at the first sample's value"#

Passed to FilterbankSettings.startup. The default holds the first sample as the pre-history, so a DC offset does not ring through the bands at the start of a stream.

materialize: MaterializeMode = 'async'#

How to evaluate the output on a lazy backend (MLX); see MaterializeMode. No-op elsewhere.

__init__(bands, transition_ratio=0.5, stopband_attenuation=60.0, bin_duration=0.02, fractional=True, output=EnvelopePowerOutput.POWER, min_phase=MinPhaseMode.NONE, startup=StartupMode.CONSTANT, materialize=MaterializeMode.ASYNC)#
Parameters:
Return type:

None

class MultiBandEnvelopePowerTransformer(*args, **kwargs)[source]#

Bases: CompositeProcessor[MultiBandEnvelopePowerSettings, AxisArray, AxisArray]

Binned envelope power in several bands at once.

Pipeline: analytic filterbank -> abs -> [square] -> binned mean -> [log10]. (time, ch) in, (time, ch, band) out. The band axis is a CoordinateAxis whose data is a structured array with fields lo and hi (Hz). All bands share one delay, which is subtracted from the time axis offset, so output timestamps refer to the input samples they describe.