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) / 2modulated to the band centre and doubled, so|output|is the amplitude of an in-band sinusoid.- Parameters:
settings (MultiBandEnvelopePowerSettings)
fs (float)
- Return type:
list[NDArray]
Classes
- class AnalyticFilterbankState[source]#
Bases:
object- 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 byband.
- class EnvelopePowerOutput(*values)[source]#
Bases:
OptionsEnumWhat
MultiBandEnvelopePowerTransformerreports 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:
SettingsSettings for
MultiBandEnvelopePowerTransformer.- Parameters:
transition_ratio (float)
stopband_attenuation (float)
bin_duration (float)
fractional (bool)
output (EnvelopePowerOutput)
min_phase (MinPhaseMode)
startup (StartupMode)
materialize (MaterializeMode)
- 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/2andhi + w/2 < fs/2, withwits transition width (seetransition_ratio); otherwise its one-sided kernel would pass negative frequencies, and reset raisesValueError.
- 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.
- output: EnvelopePowerOutput = 'Power'#
Power (mean of
a**2), amplitude (mean ofa) or log10 power, whereais the envelope. A sinusoid of amplitudeain a band reportsa**2power.
- 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:
transition_ratio (float)
stopband_attenuation (float)
bin_duration (float)
fractional (bool)
output (EnvelopePowerOutput)
min_phase (MinPhaseMode)
startup (StartupMode)
materialize (MaterializeMode)
- 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. Thebandaxis is aCoordinateAxiswhose data is a structured array with fieldsloandhi(Hz). All bands share one delay, which is subtracted from the time axis offset, so output timestamps refer to the input samples they describe.