ezmsg-sigproc 2.4.0__py3-none-any.whl → 2.5.0__py3-none-any.whl

ezmsg/sigproc/__version__.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '2.4.0'
-__version_tuple__ = version_tuple = (2, 4, 0)
+__version__ = version = '2.5.0'
+__version_tuple__ = version_tuple = (2, 5, 0)
 
 __commit_id__ = commit_id = None

ezmsg/sigproc/butterworthzerophase.py

@@ -0,0 +1,132 @@
+import functools
+import typing
+
+import ezmsg.core as ez
+import numpy as np
+import scipy.signal
+from ezmsg.sigproc.base import SettingsType
+from ezmsg.sigproc.butterworthfilter import ButterworthFilterSettings, butter_design_fun
+from ezmsg.sigproc.filter import (
+    BACoeffs,
+    BaseFilterByDesignTransformerUnit,
+    FilterByDesignTransformer,
+    SOSCoeffs,
+)
+from ezmsg.util.messages.axisarray import AxisArray
+from ezmsg.util.messages.util import replace
+
+
+class ButterworthZeroPhaseSettings(ButterworthFilterSettings):
+    """Settings for :obj:`ButterworthZeroPhase`."""
+
+    # axis, coef_type, order, cuton, cutoff, wn_hz are inherited from ButterworthFilterSettings
+    padtype: str | None = None
+    """
+    Padding type to use in `scipy.signal.filtfilt`.
+    Must be one of {'odd', 'even', 'constant', None}.
+    Default is None for no padding.
+    """
+
+    padlen: int | None = 0
+    """
+    Length of the padding to use in `scipy.signal.filtfilt`.
+    If None, SciPy's default padding is used.
+    """
+
+
+class ButterworthZeroPhaseTransformer(
+    FilterByDesignTransformer[ButterworthZeroPhaseSettings, BACoeffs | SOSCoeffs]
+):
+    """Zero-phase (filtfilt) Butterworth using your design function."""
+
+    def get_design_function(
+        self,
+    ) -> typing.Callable[[float], BACoeffs | SOSCoeffs | None]:
+        return functools.partial(
+            butter_design_fun,
+            order=self.settings.order,
+            cuton=self.settings.cuton,
+            cutoff=self.settings.cutoff,
+            coef_type=self.settings.coef_type,
+            wn_hz=self.settings.wn_hz,
+        )
+
+    def update_settings(
+        self, new_settings: typing.Optional[SettingsType] = None, **kwargs
+    ) -> None:
+        """
+        Update settings and mark that filter coefficients need to be recalculated.
+
+        Args:
+            new_settings: Complete new settings object to replace current settings
+            **kwargs: Individual settings to update
+        """
+        # Update settings
+        if new_settings is not None:
+            self.settings = new_settings
+        else:
+            self.settings = replace(self.settings, **kwargs)
+
+        # Set flag to trigger recalculation on next message
+        self._coefs_cache = None
+        self._fs_cache = None
+        self.state.needs_redesign = True
+
+    def _reset_state(self, message: AxisArray) -> None:
+        self._coefs_cache = None
+        self._fs_cache = None
+        self.state.needs_redesign = True
+
+    def _process(self, message: AxisArray) -> AxisArray:
+        axis = message.dims[0] if self.settings.axis is None else self.settings.axis
+        ax_idx = message.get_axis_idx(axis)
+        fs = 1 / message.axes[axis].gain
+
+        if (
+            self._coefs_cache is None
+            or self.state.needs_redesign
+            or (self._fs_cache is None or not np.isclose(self._fs_cache, fs))
+        ):
+            self._coefs_cache = self.get_design_function()(fs)
+            self._fs_cache = fs
+            self.state.needs_redesign = False
+
+        if (
+            self._coefs_cache is None
+            or self.settings.order <= 0
+            or message.data.size <= 0
+        ):
+            return message
+
+        x = message.data
+        if self.settings.coef_type == "sos":
+            y = scipy.signal.sosfiltfilt(
+                self._coefs_cache,
+                x,
+                axis=ax_idx,
+                padtype=self.settings.padtype,
+                padlen=self.settings.padlen,
+            )
+        elif self.settings.coef_type == "ba":
+            b, a = self._coefs_cache
+            y = scipy.signal.filtfilt(
+                b,
+                a,
+                x,
+                axis=ax_idx,
+                padtype=self.settings.padtype,
+                padlen=self.settings.padlen,
+            )
+        else:
+            ez.logger.error("coef_type must be 'sos' or 'ba'.")
+            raise ValueError("coef_type must be 'sos' or 'ba'.")
+
+        return replace(message, data=y)
+
+
+class ButterworthZeroPhase(
+    BaseFilterByDesignTransformerUnit[
+        ButterworthZeroPhaseSettings, ButterworthZeroPhaseTransformer
+    ]
+):
+    SETTINGS = ButterworthZeroPhaseSettings

ezmsg/sigproc/denormalize.py

@@ -22,15 +22,13 @@ class DenormalizeSettings(ez.Settings):
 
 
 @processor_state
-class DenormalizeRateState:
+class DenormalizeState:
     gains: npt.NDArray | None = None
     offsets: npt.NDArray | None = None
 
 
 class DenormalizeTransformer(
-    BaseStatefulTransformer[
-        DenormalizeSettings, AxisArray, AxisArray, DenormalizeRateState
-    ]
+    BaseStatefulTransformer[DenormalizeSettings, AxisArray, AxisArray, DenormalizeState]
 ):
     """
     Scales data from a normalized distribution (mean=0, std=1) to a denormalized
@@ -78,7 +76,7 @@ class DenormalizeTransformer(
         )
 
 
-class DenormalizeRateUnit(
+class DenormalizeUnit(
     BaseTransformerUnit[
         DenormalizeSettings, AxisArray, AxisArray, DenormalizeTransformer
     ]

ezmsg/sigproc/fir_hilbert.py

@@ -0,0 +1,353 @@
+import functools
+import typing
+
+import ezmsg.core as ez
+import numpy as np
+import scipy.signal as sps
+from ezmsg.sigproc.base import BaseStatefulTransformer, processor_state
+from ezmsg.sigproc.filter import (
+    BACoeffs,
+    BaseFilterByDesignTransformerUnit,
+    BaseTransformerUnit,
+    FilterBaseSettings,
+    FilterByDesignTransformer,
+)
+from ezmsg.util.messages.axisarray import AxisArray
+from ezmsg.util.messages.util import replace
+
+
+class FIRHilbertFilterSettings(FilterBaseSettings):
+    """Settings for :obj:`FIRHilbertFilter`."""
+
+    # axis inherited from FilterBaseSettings
+
+    coef_type: str = "ba"
+    """
+    Coefficient type. Must be 'ba' for FIR.
+    """
+
+    order: int = 170
+    """
+    Filter order (taps = order + 1).
+    Hilbert (type-III) filters require even order (odd taps).
+    If odd order (even taps), order will be incremented by 1.
+    """
+
+    f_lo: float = 1.0
+    """
+    Lower corner of Hilbert “pass” band (Hz).
+    Transition starts at f_lo.
+    """
+
+    f_hi: float | None = None
+    """
+    Upper corner of Hilbert “pass” band (Hz).
+    Transition starts at f_hi.
+    If None, highpass from f_lo to Nyquist.
+    """
+
+    trans_lo: float = 1.0
+    """
+    Transition width (Hz) below f_lo.
+    Decrease to sharpen transition.
+    """
+
+    trans_hi: float = 1.0
+    """
+    Transition width (Hz) at high end.
+    Decrease to sharpen transition.
+    """
+
+    weight_pass: float = 1.0
+    """
+    Weight for Hilbert pass region. 
+    """
+
+    weight_stop_lo: float = 1.0
+    """
+    Weight for low stop band.
+    """
+
+    weight_stop_hi: float = 1.0
+    """
+    Weight for high stop band.
+    """
+
+    norm_band: tuple[float, float] | None = None
+    """ 
+    Optional normalization band (f_lo, f_hi) in Hz for gain normalization.
+    If None, no normalization is applied.
+    """
+
+    norm_freq: float | None = None
+    """
+    Optional normalization frequency in Hz for gain normalization.
+    If None, no normalization is applied.
+    """
+
+
+def fir_hilbert_design_fun(
+    fs: float,
+    order: int = 170,
+    f_lo: float = 1.0,
+    f_hi: float | None = None,
+    trans_lo: float = 1.0,
+    trans_hi: float = 1.0,
+    weight_pass: float = 1.0,
+    weight_stop_lo: float = 1.0,
+    weight_stop_hi: float = 1.0,
+    norm_band: tuple[float, float] | None = None,
+    norm_freq: float | None = None,
+) -> BACoeffs | None:
+    """
+    Hilbert FIR filter design using the Remez exchange algorithm.
+    Design an `order`th-order FIR Hilbert filter and return the filter coefficients.
+    See :obj:`FIRHilbertFilterSettings` for argument description.
+
+    Returns:
+        The filter coefficients as a tuple of (b, a).
+    """
+    if order <= 0:
+        return None
+    if order % 2 == 1:
+        order += 1
+    nyq = fs / 2.0
+    taps = order + 1
+    f1 = max(f_lo, 0.0) + trans_lo
+    f2 = (nyq - trans_hi) if (f_hi is None) else min(f_hi, nyq - trans_hi)
+    if not (0.0 < f1 < f2 < nyq):
+        raise ValueError(
+            f"Hilbert passband collapsed or invalid: "
+            f"f_lo={f_lo}, f_hi={f_hi}, trans_lo={trans_lo}, trans_hi={trans_hi}, fs={fs}"
+        )
+    # Bands: [0, f1-trans_lo] stop ; [f1, f2] pass (Hilbert) ; [f2+trans_hi, nyq] stop
+    bands = [0.0, max(f1 - trans_lo, 0.0), f1, f2, min(f2 + trans_hi, nyq), nyq]
+    desired = [0.0, 1.0, 0.0]
+    weight = [max(weight_stop_lo, 0.0), max(weight_pass, 0.0), max(weight_stop_hi, 0.0)]
+    for i in range(1, len(bands) - 1):
+        if bands[i] <= bands[i - 1]:
+            bands[i] = np.nextafter(bands[i - 1], np.inf)
+    if bands[-2] >= nyq:
+        ez.logger.warning(
+            "Hilbert upper stopband collapsed; using 2-band (stop/pass) design."
+        )
+        bands = bands[:-3] + [nyq]
+        desired = desired[:-1]
+        weight = weight[:-1]
+    b = sps.remez(taps, bands, desired, weight=weight, type="hilbert", fs=fs)
+    a = np.array([1.0])
+    g = None
+    if norm_freq is not None:
+        if norm_freq < f1 or norm_freq > f2:
+            ez.logger.warning(
+                "Invalid normalization frequency specifications. Skipping normalization."
+            )
+        else:
+            f0 = float(norm_freq)
+            w = 2.0 * np.pi * (np.asarray([f0], dtype=np.float64) / fs)
+            _, H = sps.freqz(b, a, worN=w)
+            g = float(np.abs(H[0]))
+    elif norm_band is not None:
+        lo, hi = norm_band
+        if lo < f1 or hi > f2:
+            lo = max(lo, f1)
+            hi = min(hi, f2)
+            ez.logger.warning(
+                "Normalization band outside passband. Clipping to passband for normalization."
+            )
+        if lo >= hi:
+            ez.logger.warning(
+                "Invalid normalization band specifications. Skipping normalization."
+            )
+        else:
+            freqs = np.linspace(lo, hi, 2048, dtype=np.float64)
+            w = 2.0 * np.pi * (np.asarray(freqs, dtype=np.float64) / fs)
+            _, H = sps.freqz(b, a, worN=w)
+            g = float(np.median(np.abs(H)))
+    if g is not None and g > 0:
+        b = b / g
+    return (b, a)
+
+
+class FIRHilbertFilterTransformer(
+    FilterByDesignTransformer[FIRHilbertFilterSettings, BACoeffs]
+):
+    def get_design_function(self) -> typing.Callable[[float], BACoeffs | None]:
+        if self.settings.coef_type != "ba":
+            ez.logger.error("FIRHilbert only supports coef_type='ba'.")
+            raise ValueError("FIRHilbert only supports coef_type='ba'.")
+
+        return functools.partial(
+            fir_hilbert_design_fun,
+            order=self.settings.order,
+            f_lo=self.settings.f_lo,
+            f_hi=self.settings.f_hi,
+            trans_lo=self.settings.trans_lo,
+            trans_hi=self.settings.trans_hi,
+            weight_pass=self.settings.weight_pass,
+            weight_stop_lo=self.settings.weight_stop_lo,
+            weight_stop_hi=self.settings.weight_stop_hi,
+            norm_band=self.settings.norm_band,
+            norm_freq=self.settings.norm_freq,
+        )
+
+    def get_taps(self) -> int | None:
+        if self._state.filter is None:
+            return None
+        b, _ = self._state.filter.settings.coefs
+        return b.size if b is not None else None
+
+
+class FIRHilbertFilterUnit(
+    BaseFilterByDesignTransformerUnit[
+        FIRHilbertFilterSettings, FIRHilbertFilterTransformer
+    ]
+):
+    SETTINGS = FIRHilbertFilterSettings
+
+
+@processor_state
+class FIRHilbertEnvelopeState:
+    filter: FIRHilbertFilterTransformer | None = None
+    delay_buf: np.ndarray | None = None
+    dly: int | None = None
+
+
+class FIRHilbertEnvelopeTransformer(
+    BaseStatefulTransformer[
+        FIRHilbertFilterSettings, AxisArray, AxisArray, FIRHilbertEnvelopeState
+    ]
+):
+    """
+    Processor for computing the envelope of a signal using the Hilbert transform.
+
+    This processor applies a Hilbert FIR filter to the input signal to obtain the analytic signal, from which the
+    envelope is computed.
+
+    The processor expects and outputs `AxisArray` messages with a `"time"` (time) axis.
+
+    Settings:
+    ---------
+    order : int
+        Filter order (taps = order + 1).
+        Hilbert (type-III) filters require even order (odd taps).
+        If odd order (even taps), order will be incremented by 1.
+    f_lo : float
+        Lower corner of Hilbert “pass” band (Hz).
+        Transition starts at f_lo.
+    f_hi : float, optional
+        Upper corner of Hilbert “pass” band (Hz).
+        Transition starts at f_hi.
+        If None, highpass from f_lo to Nyquist.
+    trans_lo : float
+        Transition width (Hz) below f_lo.
+        Decrease to sharpen transition.
+    trans_hi : float
+        Transition width (Hz) above f_hi.
+        Decrease to sharpen transition.
+    weight_pass : float
+        Weight for Hilbert pass region.
+    weight_stop_lo : float
+        Weight for low stop band.
+    weight_stop_hi : float
+        Weight for high stop band.
+    norm_band : tuple(float, float), optional
+        Optional normalization band (f_lo, f_hi) in Hz for gain normalization.
+        If None, no normalization is applied.
+    norm_freq : float, optional
+        Optional normalization frequency in Hz for gain normalization.
+        If None, no normalization is applied.
+
+    Example:
+    -----------------------------
+    ```python
+    processor = FIRHilbertEnvelopeTransformer(
+        settings=FIRHilbertFilterSettings(
+            order=170,
+            f_lo=1.0,
+            f_hi=50.0,
+        )
+    )
+    ```
+
+    """
+
+    def _hash_message(self, message: AxisArray) -> int:
+        axis = self.settings.axis or message.dims[0]
+        gain = getattr(self._state.filter, "gain", 0.0)
+        axis_idx = message.get_axis_idx(axis)
+        samp_shape = message.data.shape[:axis_idx] + message.data.shape[axis_idx + 1 :]
+        return hash((message.key, samp_shape, gain))
+
+    def _reset_state(self, message: AxisArray) -> None:
+        self._state.filter = FIRHilbertFilterTransformer(settings=self.settings)
+        self._state.delay_buf = None
+        self._state.dly = None
+
+    def _process(self, message: AxisArray) -> AxisArray:
+        y_imag_msg = self._state.filter(message)
+        y_imag = y_imag_msg.data
+
+        axis_name = self.settings.axis or message.dims[0]
+        axis_idx = message.get_axis_idx(axis_name)
+        if self._state.dly is None:
+            taps = self._state.filter.get_taps()
+            self._state.dly = (taps - 1) // 2
+
+        x = message.data
+
+        move_axis = False
+        if axis_idx != x.ndim - 1:
+            x = np.moveaxis(x, axis_idx, -1)
+            y_imag = np.moveaxis(y_imag, axis_idx, -1)
+            move_axis = True
+
+        if self._state.delay_buf is None:
+            lead_shape = x.shape[:-1]
+            self._state.delay_buf = np.zeros(
+                lead_shape + (self._state.dly,), dtype=x.dtype
+            )
+
+        x_cat = np.concatenate([self._state.delay_buf, x], axis=-1)
+        x_delayed_full = x_cat[..., : -self._state.dly]
+        y_real = x_delayed_full[..., -x.shape[-1] :]
+
+        self._state.delay_buf = x_cat[..., -self._state.dly :].copy()
+
+        analytic = y_real.astype(np.complex64) + 1j * y_imag.astype(np.complex64)
+        out = np.abs(analytic)
+
+        if move_axis:
+            out = np.moveaxis(out, -1, axis_idx)
+
+        return replace(message, data=out, axes=message.axes)
+
+
+class FIRHilbertEnvelopeUnit(
+    BaseTransformerUnit[
+        FIRHilbertFilterSettings,
+        AxisArray,
+        AxisArray,
+        FIRHilbertEnvelopeTransformer,
+    ]
+):
+    """
+    Unit wrapper for the `FIRHilbertEnvelopeTransformer`.
+
+    This unit provides a plug-and-play interface for calculating the envelope using the FIR Hilbert transform on a
+    signal in an ezmsg graph-based system. It takes in `AxisArray` inputs and outputs processed data in the same format.
+
+    Example:
+    --------
+    ```python
+    unit = FIRHilbertEnvelopeUnit(
+        settings=FIRHilbertFilterSettings(
+            order=170,
+            f_lo=1.0,
+            f_hi=50.0,
+        )
+    )
+    ```
+    """
+
+    SETTINGS = FIRHilbertFilterSettings

ezmsg/sigproc/fir_pmc.py

@@ -0,0 +1,214 @@
+import functools
+import typing
+
+import ezmsg.core as ez
+import numpy as np
+import scipy.signal
+from ezmsg.sigproc.filter import (
+    BACoeffs,
+    BaseFilterByDesignTransformerUnit,
+    FilterBaseSettings,
+    FilterByDesignTransformer,
+)
+
+
+class ParksMcClellanFIRSettings(FilterBaseSettings):
+    """Settings for :obj:`ParksMcClellanFIR`."""
+
+    # axis inherited from FilterBaseSettings
+
+    coef_type: str = "ba"
+    """
+    Coefficient type. Must be 'ba' for FIR.
+    """
+
+    order: int = 0
+    """
+    Filter order (taps = order + 1).
+    PMC FIR filters require even order (odd taps).
+    If odd order (even taps), order will be incremented by 1.
+    """
+
+    cuton: float | None = None
+    """
+    Cuton frequency (Hz). If `cutoff` is not specified then this is the highpass corner. Otherwise,
+    if this is lower than `cutoff` then this is the beginning of the bandpass
+    or if this is greater than `cutoff` then this is the end of the bandstop. 
+    """
+
+    cutoff: float | None = None
+    """
+    Cutoff frequency (Hz). If `cuton` is not specified then this is the lowpass corner. Otherwise,
+    if this is greater than `cuton` then this is the end of the bandpass,
+    or if this is less than `cuton` then this is the beginning of the bandstop. 
+    """
+
+    transition: float = 10.0
+    """
+    Transition bandwidth (Hz) applied to each passband edge.
+    For low/high: single transition. For bands: both edges.
+    """
+
+    weight_pass: float = 1.0
+    """
+    Weight for the passband.
+    Used for both high and low passbands in bandstop filters.
+    """
+
+    weight_stop_lo: float = 1.0
+    """
+    Weight for the lower stopband.
+    Not used for bandstop filters.
+    """
+
+    weight_stop_hi: float = 1.0
+    """
+    Weight for the upper stopband.
+    Used as the central-stop weight for bandstop filters.
+    """
+
+    def filter_specs(
+        self,
+    ) -> tuple[str, tuple[float, float] | float] | None:
+        """
+        Determine the filter type given the corner frequencies.
+
+        Returns:
+            A tuple with the first element being a string indicating the filter type
+            (one of "lowpass", "highpass", "bandpass", "bandstop")
+            and the second element being the corner frequency or frequencies.
+
+        """
+        if self.cuton is None and self.cutoff is None:
+            return None
+        elif self.cuton is None and self.cutoff is not None:
+            return "lowpass", self.cutoff
+        elif self.cuton is not None and self.cutoff is None:
+            return "highpass", self.cuton
+        elif self.cuton is not None and self.cutoff is not None:
+            if self.cuton <= self.cutoff:
+                return "bandpass", (self.cuton, self.cutoff)
+            else:
+                return "bandstop", (self.cutoff, self.cuton)
+
+
+def parks_mcclellan_design_fun(
+    fs: float,
+    order: int = 0,
+    cuton: float | None = None,
+    cutoff: float | None = None,
+    transition: float = 10.0,
+    weight_pass: float = 1.0,
+    weight_stop_lo: float = 1.0,
+    weight_stop_hi: float = 1.0,
+) -> BACoeffs | None:
+    """
+    See :obj:`ParksMcClellanFIRSettings.filter_specs` for an explanation of specifying different
+    filter types (lowpass, highpass, bandpass, bandstop) from the parameters.
+
+    Designs a Parks-McClellan FIR filter via the Remez exchange algorithm using the given specifications.
+    PMC filters are equiripple and linear phase.
+
+    You are likely to want to use this function with :obj:`filter_by_design`, which only passes `fs` to the design
+    function (this), meaning that you should wrap this function with a lambda or prepare with functools.partial.
+
+    Args:
+        fs: The sampling frequency of the data in Hz.
+        order: Filter order.
+        cuton: Corner frequency of the filter in Hz.
+        cutoff: Corner frequency of the filter in Hz.
+        transition: Transition bandwidth (Hz) applied to each passband edge.
+        weight_pass: Weight for the passband.
+        weight_stop_lo: Weight for the lower stopband.
+        weight_stop_hi: Weight for the upper stopband.
+
+    Returns:
+        The filter coefficients as a tuple of (b, a).
+    """
+    if order <= 0:
+        return None
+    if order % 2 == 1:
+        order += 1
+
+    specs = ParksMcClellanFIRSettings(cuton=cuton, cutoff=cutoff).filter_specs()
+    if specs is None:
+        # Under-specified: no filter
+        return None
+
+    btype, corners = specs
+    nyq = fs / 2.0
+    tw = max(transition, 0.0)
+
+    def clip_hz(x: float) -> float:
+        return float(min(max(x, 0.0), nyq))
+
+    if btype == "lowpass":
+        b = [0.0, clip_hz(corners), clip_hz(corners + tw), nyq]
+        d = [1.0, 0.0]
+        w = [max(weight_pass, 0.0), max(weight_stop_hi, 0.0)]
+
+    elif btype == "highpass":
+        b = [0.0, clip_hz(corners - tw), clip_hz(corners), nyq]
+        d = [0.0, 1.0]
+        w = [max(weight_stop_lo, 0.0), max(weight_pass, 0.0)]
+
+    elif btype == "bandpass":
+        b = [
+            0.0,
+            clip_hz(corners[0] - tw),
+            clip_hz(corners[0]),
+            clip_hz(corners[1]),
+            clip_hz(corners[1] + tw),
+            nyq,
+        ]
+        d = [0.0, 1.0, 0.0]
+        w = [max(weight_stop_lo, 0.0), max(weight_pass, 0.0), max(weight_stop_hi, 0.0)]
+
+    else:
+        b = [
+            0.0,
+            clip_hz(corners[0]),
+            clip_hz(corners[0] + tw),
+            clip_hz(corners[1] - tw),
+            clip_hz(corners[1]),
+            nyq,
+        ]
+        d = [1.0, 0.0, 1.0]
+        # For bandstop we can reuse stop_hi as central-stop weight; stop_lo is the DC-side passband stop weight
+        w = [max(weight_pass, 0.0), max(weight_stop_hi, 0.0), max(weight_pass, 0.0)]
+
+    # Ensure bands strictly increase and have nonzero width per segment
+    # Adjust tiny overlaps due to clipping
+    for i in range(1, len(b)):
+        if b[i] <= b[i - 1]:
+            b[i] = min(b[i - 1] + 1e-6, nyq)
+
+    b = scipy.signal.remez(numtaps=order + 1, bands=b, desired=d, weight=w, fs=fs)
+    return (b, np.array([1.0]))
+
+
+class ParksMcClellanFIRTransformer(
+    FilterByDesignTransformer[ParksMcClellanFIRSettings, BACoeffs]
+):
+    def get_design_function(self) -> typing.Callable[[float], BACoeffs | None]:
+        if self.settings.coef_type != "ba":
+            ez.logger.error("ParksMcClellanFIR only supports coef_type='ba'.")
+            raise ValueError("ParksMcClellanFIR only supports coef_type='ba'.")
+        return functools.partial(
+            parks_mcclellan_design_fun,
+            order=self.settings.order,
+            cuton=self.settings.cuton,
+            cutoff=self.settings.cutoff,
+            transition=self.settings.transition,
+            weight_pass=self.settings.weight_pass,
+            weight_stop_lo=self.settings.weight_stop_lo,
+            weight_stop_hi=self.settings.weight_stop_hi,
+        )
+
+
+class ParksMcClellanFIR(
+    BaseFilterByDesignTransformerUnit[
+        ParksMcClellanFIRSettings, ParksMcClellanFIRTransformer
+    ]
+):
+    SETTINGS = ParksMcClellanFIRSettings

ezmsg/sigproc/rollingscaler.py

@@ -0,0 +1,257 @@
+from collections import deque
+
+import ezmsg.core as ez
+import numpy as np
+import numpy.typing as npt
+from ezmsg.sigproc.base import (
+    BaseAdaptiveTransformer,
+    BaseAdaptiveTransformerUnit,
+    processor_state,
+)
+from ezmsg.sigproc.sampler import SampleMessage
+from ezmsg.util.messages.axisarray import AxisArray
+from ezmsg.util.messages.util import replace
+
+
+class RollingScalerSettings(ez.Settings):
+    axis: str = "time"
+    """
+    Axis along which samples are arranged.
+    """
+
+    k_samples: int | None = 20
+    """
+    Rolling window size in number of samples.
+    """
+
+    window_size: float | None = None
+    """
+    Rolling window size in seconds.
+    If set, overrides `k_samples`.
+    `update_with_signal` likely should be True if using this option.
+    """
+
+    update_with_signal: bool = False
+    """
+    If True, update rolling statistics using the incoming process stream.
+    """
+
+    min_samples: int = 1
+    """
+    Minimum number of samples required to compute statistics.
+    Used when `window_size` is not set.
+    """
+
+    min_seconds: float = 1.0
+    """
+    Minimum duration in seconds required to compute statistics.
+    Used when `window_size` is set.
+    """
+
+    artifact_z_thresh: float | None = None
+    """
+    Threshold for z-score based artifact detection.
+    If set, samples with any channel exceeding this z-score will be excluded
+    from updating the rolling statistics.
+    """
+
+    clip: float | None = 10.0
+    """
+    If set, clip the output values to the range [-clip, clip].
+    """
+
+
+@processor_state
+class RollingScalerState:
+    mean: npt.NDArray | None = None
+    N: int = 0
+    M2: npt.NDArray | None = None
+    samples: deque | None = None
+    k_samples: int | None = None
+    min_samples: int | None = None
+
+
+class RollingScalerProcessor(
+    BaseAdaptiveTransformer[
+        RollingScalerSettings, AxisArray, AxisArray, RollingScalerState
+    ]
+):
+    """
+    Processor for rolling z-score normalization of input `AxisArray` messages.
+
+    The processor maintains rolling statistics (mean and variance) over the last `k_samples`
+    samples received via the `partial_fit()` method. When processing an `AxisArray` message,
+    it normalizes the data using the current rolling statistics.
+
+    The input `AxisArray` messages are expected to have shape `(time, ch)`, where `ch` is the
+    channel axis. The processor computes the z-score for each channel independently.
+
+    Note: You should consider instead using the AdaptiveStandardScalerTransformer which
+    is computationally more efficient and uses less memory. This RollingScalerProcessor
+    is primarily provided to reproduce processing in the literature.
+
+    Settings:
+    ---------
+    k_samples: int
+        Number of previous samples to use for rolling statistics.
+
+    Example:
+    -----------------------------
+    ```python
+    processor = RollingScalerProcessor(
+        settings=RollingScalerSettings(
+            k_samples=20  # Number of previous samples to use for rolling statistics
+        )
+    )
+    ```
+    """
+
+    def _hash_message(self, message: AxisArray) -> int:
+        axis = message.dims[0] if self.settings.axis is None else self.settings.axis
+        gain = message.axes[axis].gain if hasattr(message.axes[axis], "gain") else 1
+        axis_idx = message.get_axis_idx(axis)
+        samp_shape = message.data.shape[:axis_idx] + message.data.shape[axis_idx + 1 :]
+        return hash((message.key, samp_shape, gain))
+
+    def _reset_state(self, message: AxisArray) -> None:
+        ch = message.data.shape[-1]
+        self._state.mean = np.zeros(ch)
+        self._state.N = 0
+        self._state.M2 = np.zeros(ch)
+        self._state.k_samples = (
+            int(
+                np.ceil(
+                    self.settings.window_size / message.axes[self.settings.axis].gain
+                )
+            )
+            if self.settings.window_size is not None
+            else self.settings.k_samples
+        )
+        if self._state.k_samples is not None and self._state.k_samples < 1:
+            ez.logger.warning(
+                "window_size smaller than sample gain; setting k_samples to 1."
+            )
+            self._state.k_samples = 1
+        elif self._state.k_samples is None:
+            ez.logger.warning(
+                "k_samples is None; z-score accumulation will be unbounded."
+            )
+        self._state.samples = deque(maxlen=self._state.k_samples)
+        self._state.min_samples = (
+            int(
+                np.ceil(
+                    self.settings.min_seconds / message.axes[self.settings.axis].gain
+                )
+            )
+            if self.settings.window_size is not None
+            else self.settings.min_samples
+        )
+        if (
+            self._state.k_samples is not None
+            and self._state.min_samples > self._state.k_samples
+        ):
+            ez.logger.warning(
+                "min_samples is greater than k_samples; adjusting min_samples to k_samples."
+            )
+            self._state.min_samples = self._state.k_samples
+
+    def _add_batch_stats(self, x: npt.NDArray) -> None:
+        x = np.asarray(x, dtype=np.float64)
+        n_b = x.shape[0]
+        mean_b = np.mean(x, axis=0)
+        M2_b = np.sum((x - mean_b) ** 2, axis=0)
+
+        if (
+            self._state.k_samples is not None
+            and len(self._state.samples) == self._state.k_samples
+        ):
+            n_old, mean_old, M2_old = self._state.samples.popleft()
+            N_T = self._state.N
+            N_new = N_T - n_old
+
+            if N_new <= 0:
+                self._state.N = 0
+                self._state.mean = np.zeros_like(self._state.mean)
+                self._state.M2 = np.zeros_like(self._state.M2)
+            else:
+                delta = mean_old - self._state.mean
+                self._state.N = N_new
+                self._state.mean = (N_T * self._state.mean - n_old * mean_old) / N_new
+                self._state.M2 = (
+                    self._state.M2 - M2_old - (delta * delta) * (N_T * n_old / N_new)
+                )
+
+        N_A = self._state.N
+        N = N_A + n_b
+        delta = mean_b - self._state.mean
+        self._state.mean = self._state.mean + delta * (n_b / N)
+        self._state.M2 = self._state.M2 + M2_b + (delta * delta) * (N_A * n_b / N)
+        self._state.N = N
+
+        self._state.samples.append((n_b, mean_b, M2_b))
+
+    def partial_fit(self, message: SampleMessage) -> None:
+        x = message.sample.data
+        self._add_batch_stats(x)
+
+    def _process(self, message: AxisArray) -> AxisArray:
+        if self._state.N == 0 or self._state.N < self._state.min_samples:
+            if self.settings.update_with_signal:
+                x = message.data
+                if self.settings.artifact_z_thresh is not None and self._state.N > 0:
+                    varis = self._state.M2 / self._state.N
+                    std = np.maximum(np.sqrt(varis), 1e-8)
+                    z = np.abs((x - self._state.mean) / std)
+                    mask = np.any(z > self.settings.artifact_z_thresh, axis=1)
+                    x = x[~mask]
+                if x.size > 0:
+                    self._add_batch_stats(x)
+            return message
+
+        varis = self._state.M2 / self._state.N
+        std = np.maximum(np.sqrt(varis), 1e-8)
+        with np.errstate(divide="ignore", invalid="ignore"):
+            result = (message.data - self._state.mean) / std
+        result = np.nan_to_num(result, nan=0.0, posinf=0.0, neginf=0.0)
+        if self.settings.clip is not None:
+            result = np.clip(result, -self.settings.clip, self.settings.clip)
+
+        if self.settings.update_with_signal:
+            x = message.data
+            if self.settings.artifact_z_thresh is not None:
+                z_scores = np.abs((x - self._state.mean) / std)
+                mask = np.any(z_scores > self.settings.artifact_z_thresh, axis=1)
+                x = x[~mask]
+            if x.size > 0:
+                self._add_batch_stats(x)
+
+        return replace(message, data=result)
+
+
+class RollingScalerUnit(
+    BaseAdaptiveTransformerUnit[
+        RollingScalerSettings,
+        AxisArray,
+        AxisArray,
+        RollingScalerProcessor,
+    ]
+):
+    """
+    Unit wrapper for :obj:`RollingScalerProcessor`.
+
+    This unit performs rolling z-score normalization on incoming `AxisArray` messages. The unit maintains rolling
+    statistics (mean and variance) over the last `k_samples` samples received. When processing an `AxisArray` message,
+    it normalizes the data using the current rolling statistics.
+
+    Example:
+    -----------------------------
+    ```python
+    unit = RollingScalerUnit(
+        settings=RollingScalerSettings(
+            k_samples=20  # Number of previous samples to use for rolling statistics
+        )
+    )
+    ```
+    """
+
+    SETTINGS = RollingScalerSettings

{ezmsg_sigproc-2.4.0.dist-info → ezmsg_sigproc-2.5.0.dist-info}/METADATA

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: ezmsg-sigproc
-Version: 2.4.0
+Version: 2.5.0
 Summary: Timeseries signal processing implementations in ezmsg
-Author-email: Griffin Milsap <griffin.milsap@gmail.com>, Preston Peranich <pperanich@gmail.com>, Chadwick Boulay <chadwick.boulay@gmail.com>
+Author-email: Griffin Milsap <griffin.milsap@gmail.com>, Preston Peranich <pperanich@gmail.com>, Chadwick Boulay <chadwick.boulay@gmail.com>, Kyle McGraw <kmcgraw@blackrockneuro.com>
 License-Expression: MIT
 License-File: LICENSE.txt
 Requires-Python: >=3.10.15

{ezmsg_sigproc-2.4.0.dist-info → ezmsg_sigproc-2.5.0.dist-info}/RECORD

@@ -1,5 +1,5 @@
 ezmsg/sigproc/__init__.py,sha256=8K4IcOA3-pfzadoM6s2Sfg5460KlJUocGgyTJTJl96U,52
-ezmsg/sigproc/__version__.py,sha256=69_lBCO99qjONN2phoPwQ0THjdLm1VftCSvDKqELbGk,704
+ezmsg/sigproc/__version__.py,sha256=bdfCUdK0KgIdZbIExZ_otf09cMr8k-qiQbglewDXQI8,704
 ezmsg/sigproc/activation.py,sha256=qWAhpbFBxSoqbGy4P9JKE5LY-5v8rQI1U81OvNxBG2Y,2820
 ezmsg/sigproc/adaptive_lattice_notch.py,sha256=3M65PrZpdgBlQtE7Ph4Gu2ISIyWw4j8Xxhm5PpSkLFw,9102
 ezmsg/sigproc/affinetransform.py,sha256=WU495KoDKZfHPS3Dumh65rgf639koNlfDIx_torIByg,8662
@@ -7,10 +7,11 @@ ezmsg/sigproc/aggregate.py,sha256=wHUP_aS9NgnOxBCPN1_tSxCqMMb8UPBEoKwGKX7-ASk,91
 ezmsg/sigproc/bandpower.py,sha256=j-Y6iWjD2xkggfi-4HAFJVBPJHHBGvAZy1uM4murZkQ,2319
 ezmsg/sigproc/base.py,sha256=PQr03O2P1v9LzcSR0GJLvPpBCLtnmGaz76gUeXphcH4,48753
 ezmsg/sigproc/butterworthfilter.py,sha256=7ZP4CRsXBt3-5dzyUjD45vc0J3Fhpm4CLrk-ps28jhc,5305
+ezmsg/sigproc/butterworthzerophase.py,sha256=B95FxHBk0uSXizsndR5yc8I2V_gXVNWZ9WVMS4m1Hek,4190
 ezmsg/sigproc/cheby.py,sha256=-aSauAwxJmmSSiRaw5qGY9rvYFOmk1bZlS4gGrS0jls,3737
 ezmsg/sigproc/combfilter.py,sha256=5UCfzGESpS5LSx6rxZv8_n25ZUvOOmws-mM_gpTZNhU,4777
 ezmsg/sigproc/decimate.py,sha256=Lz46fBllWagu17QeQzgklm6GWCV-zPysiydiby2IElU,2347
-ezmsg/sigproc/denormalize.py,sha256=qMXkxpNoEACHzEfluA0wV4716HQyGE_1tcFAa8uzhIc,3091
+ezmsg/sigproc/denormalize.py,sha256=CujviBepGysjB5X7RZoDOMC5tUC97ryHnUdqhi-eMPo,3065
 ezmsg/sigproc/detrend.py,sha256=7bpjFKdk2b6FdVn2GEtMbWtCuk7ToeiYKEBHVbN4Gd0,903
 ezmsg/sigproc/diff.py,sha256=P5BBjR7KdaCL9aD3GG09cmC7a-3cxDeEUw4nKdQ1HY8,2895
 ezmsg/sigproc/downsample.py,sha256=0X6EwPZ_XTwA2-nx5w-2HmMZUEDFuGAYF5EmPSuuVj8,3721
@@ -21,12 +22,15 @@ ezmsg/sigproc/fbcca.py,sha256=8NTJAOpHIvNFwQepui2_ZaJV4SMDFgXrqoWJyiQdF5U,12362
 ezmsg/sigproc/filter.py,sha256=1MQUZDFIf6HAHuuhGQEvH4Yd6Jv_vv12PM25YaHjdxc,11921
 ezmsg/sigproc/filterbank.py,sha256=pJzv_G6chgWa1ARmRjMAMgt9eEGnA-ZbMSge4EWrcYY,13633
 ezmsg/sigproc/filterbankdesign.py,sha256=OfIXM0ushSqbdSQG9DZB1Mh57d-lqdJQX8aqfxNN67E,4734
+ezmsg/sigproc/fir_hilbert.py,sha256=qqHTp-yIhAD3VBoENTxpBmy7TgF2lYqbZ65OSfqeWO4,11042
+ezmsg/sigproc/fir_pmc.py,sha256=ApWMl7WNQ9Ihr-J74DrAVwxD1r8gvLcElYcEL0RtQ2U,7024
 ezmsg/sigproc/firfilter.py,sha256=MCrwY3DLq-uMLX04JswVB9oHBSYJGbdUiQYW6eRdkxE,3805
 ezmsg/sigproc/gaussiansmoothing.py,sha256=NaVezgNwdvp-kam1I_7lSID4Obi0UCxZshH7A2afaVg,2692
 ezmsg/sigproc/kaiser.py,sha256=WsZB8a4DP7WwrYLlGczHS61L86TiH6qEStAB6zxODhY,3502
 ezmsg/sigproc/messages.py,sha256=y_twVPK7TxRj8ajmuSuBuxwvLTgyv9OF7Y7v9bw1tfs,926
 ezmsg/sigproc/quantize.py,sha256=VzaqE6PatibEjkk7XrGO-ubAXYurAed9FYOn4bcQZQk,2193
 ezmsg/sigproc/resample.py,sha256=wqSM7g3QrcrklCeGVNN4l_qZLSXRUPHXCUxl1L47300,11654
+ezmsg/sigproc/rollingscaler.py,sha256=RrVAoN7cRvFz7kHSyeQr1pjKiKkJDM_1ChQ5V9FWZKo,8860
 ezmsg/sigproc/sampler.py,sha256=D5oMIZHAJS6XIKMdOHsDw97d4ZxfNP7iZwpc6J8Jmpk,10898
 ezmsg/sigproc/scaler.py,sha256=fCLHvCNUSgv0XChf8iS9s5uHCSCVjCasM2TCvyG5BwQ,4111
 ezmsg/sigproc/signalinjector.py,sha256=hGC837JyDLtAGrfsdMwzEoOqWXiwP7r7sGlUC9nahTY,2948
@@ -53,7 +57,7 @@ ezmsg/sigproc/util/message.py,sha256=l_b1b6bXX8N6VF9RbUELzsHs73cKkDURBdIr0lt3CY0
 ezmsg/sigproc/util/profile.py,sha256=KNJ_QkKelQHNEp2C8MhqzdhYydMNULc_NQq3ccMfzIk,5775
 ezmsg/sigproc/util/sparse.py,sha256=mE64p1tYb5A1shaRE1D-VnH-RshbLb8g8kXSXxnA-J4,4842
 ezmsg/sigproc/util/typeresolution.py,sha256=5R7xmG-F4CkdqQ5aoQnqM-htQb-VwAJl58jJgxtClys,3146
-ezmsg_sigproc-2.4.0.dist-info/METADATA,sha256=FcsrFuRHBBbdrHsdlVGJjU7hUGkX-ql3xYWGAPdkD1M,4977
-ezmsg_sigproc-2.4.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-ezmsg_sigproc-2.4.0.dist-info/licenses/LICENSE.txt,sha256=seu0tKhhAMPCUgc1XpXGGaCxY1YaYvFJwqFuQZAl2go,1100
-ezmsg_sigproc-2.4.0.dist-info/RECORD,,
+ezmsg_sigproc-2.5.0.dist-info/METADATA,sha256=SiHigniH10jk8aeW-C7SLMqdldTbpphobjwVJbaBdX0,5019
+ezmsg_sigproc-2.5.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+ezmsg_sigproc-2.5.0.dist-info/licenses/LICENSE.txt,sha256=seu0tKhhAMPCUgc1XpXGGaCxY1YaYvFJwqFuQZAl2go,1100
+ezmsg_sigproc-2.5.0.dist-info/RECORD,,