Source code for ezmsg.sigproc.util.startup

"""Data-primed filter start-up: build the filter state from the first samples of a stream."""

import math
import typing

import numpy as np
from array_api_compat import get_namespace
from ezmsg.util.messages.axisarray import AxisArray, slice_along_axis
from ezmsg.util.messages.util import replace

from ..spectrum import OptionsEnum
from .array import xp_flip

#: Fraction of a pole's initial contribution left when its settling length has passed.
SETTLE_TOL = 1e-3


[docs] class StartupMode(OptionsEnum): """What a filter assumes about the signal before the first sample it sees.""" ZERO = "Zero pre-history" CONSTANT = "Constant pre-history at the first sample's value" FIRST_CHUNK = "Prime the state from a reflection of the first message" BUFFERED = "Hold output until enough samples arrive to prime the state, then release them"
[docs] def settle_samples(poles: typing.Any, order: int, tol: float = SETTLE_TOL) -> float: """Samples until a filter's state is (nearly) independent of its initial conditions. ``order`` for a filter with all poles at the origin (an FIR: its state is exactly the last ``order`` inputs), otherwise ``ceil(log(tol) / log(max|pole|))``, the length over which the slowest pole decays to ``tol``. ``inf`` for a pole on or outside the unit circle. """ radius = float(np.max(np.abs(poles), initial=0.0)) if radius == 0.0: return order if radius >= 1.0: return math.inf return math.ceil(math.log(tol) / math.log(radius))
def _linear_axis(message: AxisArray, axis: str) -> AxisArray.LinearAxis: ax = message.axes.get(axis) if not isinstance(ax, AxisArray.LinearAxis): raise TypeError(f"Data-primed start-up requires a LinearAxis on the '{axis}' dimension.") return ax
[docs] def startup_n_pad(n: float, message: AxisArray, axis: str, max_dur: float | None) -> int: """Cap a pad length ``n`` (samples) at ``max_dur`` seconds of ``message``'s stream (None: no cap).""" if max_dur is not None: n = min(n, int(max_dur / _linear_axis(message, axis).gain)) if math.isinf(n): raise ValueError( "The filter has a pole on or outside the unit circle, so it never settles; " "set startup_max_dur to bound the start-up pad." ) return int(n)
[docs] def prime_with_reflection( run: typing.Callable[[AxisArray], typing.Any], message: AxisArray, axis: str, n_pad: int ) -> None: """Prime a stateful processor from the start of ``message`` and discard what it emits. Builds up to ``n_pad`` samples of synthetic pre-history by odd reflection of the first samples about the first one, ``2 * x[0] - x[n_pad:0:-1]`` (the padding :func:`scipy.signal.filtfilt` uses), stamps them with the times just before ``message`` and passes them to ``run``, whose output is dropped. ``n_pad`` is cut to what ``message`` holds (one fewer than its length); with nothing to reflect, ``run`` is not called. Args: run: The processor, or any callable that advances its state on an AxisArray. message: The first real message. It needs a LinearAxis on ``axis``. axis: The stream dimension. n_pad: Pad length in samples. """ ax_idx = message.get_axis_idx(axis) n_pad = min(n_pad, message.data.shape[ax_idx] - 1) if n_pad <= 0: return ax = _linear_axis(message, axis) x0 = slice_along_axis(message.data, slice(0, 1), ax_idx) pad = 2 * x0 - xp_flip(slice_along_axis(message.data, slice(1, n_pad + 1), ax_idx), axis=ax_idx) run(replace(message, data=pad, axes={**message.axes, axis: replace(ax, offset=ax.offset - n_pad * ax.gain)}))
[docs] def hold_for_startup(held: list[AxisArray], message: AxisArray, axis: str, n: int) -> AxisArray | None: """Collect messages until they hold ``n`` samples on ``axis``. Appends ``message`` to ``held``. Returns None while fewer than ``n`` samples are held; then empties ``held`` and returns everything as one message carrying the first held message's axes and the latest message's attrs, segment and config_id. """ held.append(message) ax_idx = message.get_axis_idx(axis) if sum(m.data.shape[ax_idx] for m in held) < n: return None return release_held(held, axis)
[docs] def release_held(held: list[AxisArray], axis: str) -> AxisArray: """Empty a non-empty ``held`` and return its messages as one, as :func:`hold_for_startup` releases them. A processor's ``flush`` calls this to emit a start-up buffer that never filled. """ last = held[-1] data = get_namespace(last.data).concat([m.data for m in held], axis=last.get_axis_idx(axis)) released = replace(held[0], data=data, attrs=last.attrs, segment=last.segment, config_id=last.config_id) held.clear() return released