ezmsg-sigproc 1.5.0__py3-none-any.whl → 1.7.0__py3-none-any.whl

ezmsg/sigproc/__version__.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '1.5.0'
-__version_tuple__ = version_tuple = (1, 5, 0)
+__version__ = version = '1.7.0'
+__version_tuple__ = version_tuple = (1, 7, 0)

ezmsg/sigproc/activation.py

@@ -3,7 +3,8 @@ import typing
 import numpy as np
 import scipy.special
 import ezmsg.core as ez
-from ezmsg.util.messages.axisarray import AxisArray, replace
+from ezmsg.util.messages.axisarray import AxisArray
+from ezmsg.util.messages.util import replace
 from ezmsg.util.generator import consumer
 
 from .spectral import OptionsEnum
@@ -40,7 +41,7 @@ ACTIVATIONS = {
 
 @consumer
 def activation(
-    function: typing.Union[str, ActivationFunction],
+    function: str | ActivationFunction,
 ) -> typing.Generator[AxisArray, AxisArray, None]:
     """
     Transform the data with a simple activation function.

ezmsg/sigproc/affinetransform.py

@@ -5,7 +5,8 @@ import typing
 import numpy as np
 import numpy.typing as npt
 import ezmsg.core as ez
-from ezmsg.util.messages.axisarray import AxisArray, AxisBase, replace
+from ezmsg.util.messages.axisarray import AxisArray, AxisBase
+from ezmsg.util.messages.util import replace
 from ezmsg.util.generator import consumer
 
 from .base import GenAxisArray
@@ -13,8 +14,8 @@ from .base import GenAxisArray
 
 @consumer
 def affine_transform(
-    weights: typing.Union[np.ndarray, str, Path],
-    axis: typing.Optional[str] = None,
+    weights: np.ndarray | str | Path,
+    axis: str | None = None,
     right_multiply: bool = True,
 ) -> typing.Generator[AxisArray, AxisArray, None]:
     """
@@ -46,7 +47,7 @@ def affine_transform(
 
     # State variables
     # New axis with transformed labels, if required
-    new_axis: typing.Optional[AxisBase] = None
+    new_axis: AxisBase | None = None
 
     # Reset if any of these change.
     check_input = {"key": None}
@@ -132,8 +133,8 @@ class AffineTransformSettings(ez.Settings):
     See :obj:`affine_transform` for argument details.
     """
 
-    weights: typing.Union[np.ndarray, str, Path]
-    axis: typing.Optional[str] = None
+    weights: np.ndarray | str | Path
+    axis: str | None = None
     right_multiply: bool = True
 
 
@@ -156,7 +157,7 @@ def zeros_for_noop(data: npt.NDArray, **ignore_kwargs) -> npt.NDArray:
 
 @consumer
 def common_rereference(
-    mode: str = "mean", axis: typing.Optional[str] = None, include_current: bool = True
+    mode: str = "mean", axis: str | None = None, include_current: bool = True
 ) -> typing.Generator[AxisArray, AxisArray, None]:
     """
     Perform common average referencing (CAR) on streaming data.
@@ -213,7 +214,7 @@ class CommonRereferenceSettings(ez.Settings):
     """
 
     mode: str = "mean"
-    axis: typing.Optional[str] = None
+    axis: str | None = None
     include_current: bool = True
 
 

ezmsg/sigproc/aggregate.py

@@ -56,8 +56,8 @@ AGGREGATORS = {
 
 @consumer
 def ranged_aggregate(
-    axis: typing.Optional[str] = None,
-    bands: typing.Optional[typing.List[typing.Tuple[float, float]]] = None,
+    axis: str | None = None,
+    bands: list[tuple[float, float]] | None = None,
     operation: AggregationFunction = AggregationFunction.MEAN,
 ):
     """
@@ -75,9 +75,9 @@ def ranged_aggregate(
     msg_out = AxisArray(np.array([]), dims=[""])
 
     # State variables
-    slices: typing.Optional[typing.List[typing.Tuple[typing.Any, ...]]] = None
-    out_axis: typing.Optional[AxisBase] = None
-    ax_vec: typing.Optional[npt.NDArray] = None
+    slices: list[tuple[typing.Any, ...]] | None = None
+    out_axis: AxisBase | None = None
+    ax_vec: npt.NDArray | None = None
 
     # Reset if any of these changes. Key not checked because continuity between chunks not required.
     check_inputs = {"gain": None, "offset": None, "len": None, "key": None}
@@ -163,8 +163,8 @@ class RangedAggregateSettings(ez.Settings):
     See :obj:`ranged_aggregate` for details.
     """
 
-    axis: typing.Optional[str] = None
-    bands: typing.Optional[typing.List[typing.Tuple[float, float]]] = None
+    axis: str | None = None
+    bands: list[tuple[float, float]] | None = None
     operation: AggregationFunction = AggregationFunction.MEAN
 
 

ezmsg/sigproc/bandpower.py

@@ -14,7 +14,7 @@ from .base import GenAxisArray
 @consumer
 def bandpower(
     spectrogram_settings: SpectrogramSettings,
-    bands: typing.Optional[typing.List[typing.Tuple[float, float]]] = [
+    bands: list[tuple[float, float]] | None = [
         (17, 30),
         (70, 170),
     ],
@@ -58,7 +58,7 @@ class BandPowerSettings(ez.Settings):
     spectrogram_settings: SpectrogramSettings = field(
         default_factory=SpectrogramSettings
     )
-    bands: typing.Optional[typing.List[typing.Tuple[float, float]]] = field(
+    bands: list[tuple[float, float]] | None = field(
         default_factory=lambda: [(17, 30), (70, 170)]
     )
 

ezmsg/sigproc/butterworthfilter.py

@@ -1,15 +1,19 @@
+import functools
 import typing
 
-import ezmsg.core as ez
 import scipy.signal
-import numpy as np
 from ezmsg.util.messages.axisarray import AxisArray
-from ezmsg.util.generator import consumer
+from scipy.signal import normalize
 
-from .filter import filtergen, Filter, FilterState, FilterSettingsBase
+from .filter import (
+    FilterBaseSettings,
+    FilterCoefsMultiType,
+    FilterBase,
+    filter_gen_by_design,
+)
 
 
-class ButterworthFilterSettings(FilterSettingsBase):
+class ButterworthFilterSettings(FilterBaseSettings):
     """Settings for :obj:`ButterworthFilter`."""
 
     order: int = 0
@@ -17,25 +21,28 @@ class ButterworthFilterSettings(FilterSettingsBase):
     Filter order
     """
 
-    cuton: typing.Optional[float] = None
+    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: typing.Optional[float] = None
+    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. 
     """
 
+    wn_hz: bool = True
+    """
+    Set False if provided Wn are normalized from 0 to 1, where 1 is the Nyquist frequency
+    """
+
     def filter_specs(
         self,
-    ) -> typing.Optional[
-        typing.Tuple[str, typing.Union[float, typing.Tuple[float, float]]]
-    ]:
+    ) -> tuple[str, float | tuple[float, float]] | None:
         """
         Determine the filter type given the corner frequencies.
 
@@ -58,15 +65,74 @@ class ButterworthFilterSettings(FilterSettingsBase):
                 return "bandstop", (self.cutoff, self.cuton)
 
 
-@consumer
+def butter_design_fun(
+    fs: float,
+    order: int = 0,
+    cuton: float | None = None,
+    cutoff: float | None = None,
+    coef_type: str = "ba",
+    wn_hz: bool = True,
+) -> FilterCoefsMultiType | None:
+    """
+    See :obj:`ButterworthFilterSettings.filter_specs` for an explanation of specifying different
+    filter types (lowpass, highpass, bandpass, bandstop) from the parameters.
+    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.
+        coef_type: "ba", "sos", or "zpk"
+        wn_hz: Set False if provided Wn are normalized from 0 to 1, where 1 is the Nyquist frequency
+
+    Returns:
+        The filter coefficients as a tuple of (b, a) for coef_type "ba", or as a single ndarray for "sos",
+        or (z, p, k) for "zpk".
+
+    """
+    coefs = None
+    if order > 0:
+        btype, cutoffs = ButterworthFilterSettings(
+            order=order, cuton=cuton, cutoff=cutoff
+        ).filter_specs()
+        coefs = scipy.signal.butter(
+            order,
+            Wn=cutoffs,
+            btype=btype,
+            fs=fs if wn_hz else None,
+            output=coef_type,
+        )
+    if coefs is not None and coef_type == "ba":
+        coefs = normalize(*coefs)
+    return coefs
+
+
+class ButterworthFilter(FilterBase):
+    SETTINGS = ButterworthFilterSettings
+
+    def design_filter(
+        self,
+    ) -> typing.Callable[[float], FilterCoefsMultiType | 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,
+        )
+
+
 def butter(
-    axis: typing.Optional[str],
+    axis: str | None,
     order: int = 0,
-    cuton: typing.Optional[float] = None,
-    cutoff: typing.Optional[float] = None,
+    cuton: float | None = None,
+    cutoff: float | None = None,
     coef_type: str = "ba",
 ) -> typing.Generator[AxisArray, AxisArray, None]:
     """
+    Convenience generator wrapping filter_gen_by_design for Butterworth filters.
     Apply Butterworth filter to streaming data. Uses :obj:`scipy.signal.butter` to design the filter.
     See :obj:`ButterworthFilterSettings.filter_specs` for an explanation of specifying different
     filter types (lowpass, highpass, bandpass, bandstop) from the parameters.
@@ -84,79 +150,11 @@ def butter(
          and yields an :obj:`AxisArray` with filtered data.
 
     """
-    # IO
-    msg_out = AxisArray(np.array([]), dims=[""])
-
-    # Check parameters
-    btype, cutoffs = ButterworthFilterSettings(
-        order=order, cuton=cuton, cutoff=cutoff
-    ).filter_specs()
-
-    # State variables
-    # Initialize filtergen as passthrough until we can calculate coefs.
-    filter_gen = filtergen(axis, None, coef_type)
-
-    # Reset if these change.
-    check_input = {"gain": None}
-    # Key not checked because filter_gen will handle resetting if .key changes.
-
-    while True:
-        msg_in: AxisArray = yield msg_out
-        axis = axis or msg_in.dims[0]
-
-        b_reset = msg_in.axes[axis].gain != check_input["gain"]
-        b_reset = b_reset and order > 0  # Not passthrough
-        if b_reset:
-            check_input["gain"] = msg_in.axes[axis].gain
-            coefs = scipy.signal.butter(
-                order,
-                Wn=cutoffs,
-                btype=btype,
-                fs=1 / msg_in.axes[axis].gain,
-                output=coef_type,
-            )
-            filter_gen = filtergen(axis, coefs, coef_type)
-
-        msg_out = filter_gen.send(msg_in)
-
-
-class ButterworthFilterState(FilterState):
-    design: ButterworthFilterSettings
-
-
-class ButterworthFilter(Filter):
-    """:obj:`Unit` for :obj:`butterworth`"""
-
-    SETTINGS = ButterworthFilterSettings
-    STATE = ButterworthFilterState
-
-    INPUT_FILTER = ez.InputStream(ButterworthFilterSettings)
-
-    async def initialize(self) -> None:
-        self.STATE.design = self.SETTINGS
-        self.STATE.filt_designed = True
-        await super().initialize()
-
-    def design_filter(self) -> typing.Optional[typing.Tuple[np.ndarray, np.ndarray]]:
-        specs = self.STATE.design.filter_specs()
-        if self.STATE.design.order > 0 and specs is not None:
-            btype, cut = specs
-            return scipy.signal.butter(
-                self.STATE.design.order,
-                Wn=cut,
-                btype=btype,
-                fs=self.STATE.fs,
-                output="ba",
-            )
-        else:
-            return None
-
-    @ez.subscriber(INPUT_FILTER)
-    async def redesign(self, message: ButterworthFilterSettings) -> None:
-        if type(message) is not ButterworthFilterSettings:
-            return
-
-        if self.STATE.design.order != message.order:
-            self.STATE.zi = None
-        self.STATE.design = message
-        self.update_filter()
+    design_fun = functools.partial(
+        butter_design_fun,
+        order=order,
+        cuton=cuton,
+        cutoff=cutoff,
+        coef_type=coef_type,
+    )
+    return filter_gen_by_design(axis, coef_type, design_fun)

ezmsg/sigproc/cheby.py

@@ -0,0 +1,119 @@
+import functools
+import typing
+
+import scipy.signal
+from scipy.signal import normalize
+
+from .filter import (
+    FilterBaseSettings,
+    FilterCoefsMultiType,
+    FilterBase,
+)
+
+
+class ChebyshevFilterSettings(FilterBaseSettings):
+    """Settings for :obj:`ButterworthFilter`."""
+
+    order: int = 0
+    """
+    Filter order
+    """
+
+    ripple_tol: float | None = None
+    """
+    The maximum ripple allowed below unity gain in the passband. Specified in decibels, as a positive number.
+    """
+
+    Wn: float | tuple[float, float] | None = None
+    """
+    A scalar or length-2 sequence giving the critical frequencies.
+    For Type I filters, this is the point in the transition band at which the gain first drops below -rp.
+    For digital filters, Wn are in the same units as fs unless wn_hz is False.
+    For analog filters, Wn is an angular frequency (e.g., rad/s).
+    """
+
+    btype: str = "lowpass"
+    """
+    {‘lowpass’, ‘highpass’, ‘bandpass’, ‘bandstop’}
+    """
+
+    analog: bool = False
+    """
+    When True, return an analog filter, otherwise a digital filter is returned.
+    """
+
+    cheby_type: str = "cheby1"
+    """
+    Which type of Chebyshev filter to design. Either "cheby1" or "cheby2".
+    """
+
+    wn_hz: bool = True
+    """
+    Set False if provided Wn are normalized from 0 to 1, where 1 is the Nyquist frequency
+    """
+
+
+def cheby_design_fun(
+    fs: float,
+    order: int = 0,
+    ripple_tol: float | None = None,
+    Wn: float | tuple[float, float] | None = None,
+    btype: str = "lowpass",
+    analog: bool = False,
+    coef_type: str = "ba",
+    cheby_type: str = "cheby1",
+    wn_hz: bool = True,
+) -> FilterCoefsMultiType:
+    """
+    Chebyshev type I and type II digital and analog filter design.
+    Design an `order`th-order digital or analog Chebyshev type I or type II filter and return the filter coefficients.
+    See :obj:`ChebyFilterSettings` for argument description.
+
+    Returns:
+        The filter coefficients as a tuple of (b, a) for coef_type "ba", or as a single ndarray for "sos",
+        or (z, p, k) for "zpk".
+    """
+    coefs = None
+    if order > 0:
+        if cheby_type == "cheby1":
+            coefs = scipy.signal.cheby1(
+                order,
+                ripple_tol,
+                Wn,
+                btype=btype,
+                analog=analog,
+                output=coef_type,
+                fs=fs if wn_hz else None,
+            )
+        elif cheby_type == "cheby2":
+            coefs = scipy.signal.cheby2(
+                order,
+                ripple_tol,
+                Wn,
+                btype=btype,
+                analog=analog,
+                output=coef_type,
+                fs=fs,
+            )
+    if coefs is not None and coef_type == "ba":
+        coefs = normalize(*coefs)
+    return coefs
+
+
+class ChebyshevFilter(FilterBase):
+    SETTINGS = ChebyshevFilterSettings
+
+    def design_filter(
+        self,
+    ) -> typing.Callable[[float], FilterCoefsMultiType | None]:
+        return functools.partial(
+            cheby_design_fun,
+            order=self.SETTINGS.order,
+            ripple_tol=self.SETTINGS.ripple_tol,
+            Wn=self.SETTINGS.Wn,
+            btype=self.SETTINGS.btype,
+            analog=self.SETTINGS.analog,
+            coef_type=self.SETTINGS.coef_type,
+            cheby_type=self.SETTINGS.cheby_type,
+            wn_hz=self.SETTINGS.wn_hz,
+        )

ezmsg/sigproc/decimate.py

@@ -1,9 +1,31 @@
-import scipy.signal
+import typing
+
 import ezmsg.core as ez
 from ezmsg.util.messages.axisarray import AxisArray
 
+from .cheby import ChebyshevFilter, ChebyshevFilterSettings
 from .downsample import Downsample, DownsampleSettings
-from .filter import Filter, FilterCoefficients, FilterSettings
+from .filter import FilterCoefsMultiType
+
+
+class ChebyForDecimate(ChebyshevFilter):
+    """
+    A :obj:`ChebyshevFilter` node with a design filter method that additionally accepts a target sampling rate,
+     and if the target rate cannot be achieved it returns None, else it returns the filter coefficients.
+    """
+
+    def design_filter(
+        self,
+    ) -> typing.Callable[[float], FilterCoefsMultiType | None]:
+        def cheby_opt_design_fun(fs: float) -> FilterCoefsMultiType | None:
+            if fs is None:
+                return None
+            ds_factor = int(fs / (2.5 * self.SETTINGS.Wn))
+            if ds_factor < 2:
+                return None
+            partial_fun = super(ChebyForDecimate, self).design_filter()
+            return partial_fun(fs)
+        return cheby_opt_design_fun
 
 
 class Decimate(ez.Collection):
@@ -17,23 +39,21 @@ class Decimate(ez.Collection):
     INPUT_SIGNAL = ez.InputStream(AxisArray)
     OUTPUT_SIGNAL = ez.OutputStream(AxisArray)
 
-    FILTER = Filter()
+    FILTER = ChebyForDecimate()
     DOWNSAMPLE = Downsample()
 
     def configure(self) -> None:
-        self.DOWNSAMPLE.apply_settings(self.SETTINGS)
 
-        if self.SETTINGS.factor < 1:
-            raise ValueError("Decimation factor must be >= 1 (no decimation")
-        elif self.SETTINGS.factor == 1:
-            filt = FilterCoefficients()
-        else:
-            # See scipy.signal.decimate for IIR Filter Condition
-            b, a = scipy.signal.cheby1(8, 0.05, 0.8 / self.SETTINGS.factor)
-            system = scipy.signal.dlti(b, a)
-            filt = FilterCoefficients(b=system.num, a=system.den)  # type: ignore
-
-        self.FILTER.apply_settings(FilterSettings(filt=filt))
+        cheby_settings = ChebyshevFilterSettings(
+            order=8,
+            ripple_tol=0.05,
+            Wn=0.4 * self.SETTINGS.target_rate,
+            btype="lowpass",
+            axis=self.SETTINGS.axis,
+            wn_hz=True,
+        )
+        self.FILTER.apply_settings(cheby_settings)
+        self.DOWNSAMPLE.apply_settings(self.SETTINGS)
 
     def network(self) -> ez.NetworkDefinition:
         return (

ezmsg/sigproc/downsample.py

@@ -14,7 +14,7 @@ from .base import GenAxisArray
 
 @consumer
 def downsample(
-    axis: typing.Optional[str] = None, factor: int = 1
+    axis: str | None = None, target_rate: float | None = None
 ) -> typing.Generator[AxisArray, AxisArray, None]:
     """
     Construct a generator that yields a downsampled version of the data .send() to it.
@@ -26,7 +26,8 @@ def downsample(
     Args:
         axis: The name of the axis along which to downsample.
             Note: The axis must exist in the message .axes and be of type AxisArray.LinearAxis.
-        factor: Downsampling factor.
+        target_rate: Desired rate after downsampling. The actual rate will be the nearest integer factor of the
+            input rate that is the same or higher than the target rate.
 
     Returns:
         A primed generator object ready to receive an :obj:`AxisArray` via `.send(axis_array)`
@@ -37,10 +38,8 @@ def downsample(
     """
     msg_out = AxisArray(np.array([]), dims=[""])
 
-    if factor < 1:
-        raise ValueError("Downsample factor must be at least 1 (no downsampling)")
-
     # state variables
+    factor: int = 0  # The integer downsampling factor. It will be determined based on the target rate.
     s_idx: int = 0  # Index of the next msg's first sample into the virtual rotating ds_factor counter.
 
     check_input = {"gain": None, "key": None}
@@ -62,6 +61,16 @@ def downsample(
             check_input["key"] = msg_in.key
             # Reset state variables
             s_idx = 0
+            if target_rate is None:
+                factor = 1
+            else:
+                factor = int(1 / (axis_info.gain * target_rate))
+            if factor < 1:
+                ez.logger.warning(
+                    f"Target rate {target_rate} cannot be achieved with input rate of {1/axis_info.gain}."
+                    "Setting factor to 1."
+                )
+                factor = 1
 
         n_samples = msg_in.data.shape[axis_idx]
         samples = np.arange(s_idx, s_idx + n_samples) % factor
@@ -96,8 +105,8 @@ class DownsampleSettings(ez.Settings):
     See :obj:`downsample` documentation for a description of the parameters.
     """
 
-    axis: typing.Optional[str] = None
-    factor: int = 1
+    axis: str | None = None
+    target_rate: float | None = None
 
 
 class Downsample(GenAxisArray):
@@ -107,5 +116,5 @@ class Downsample(GenAxisArray):
 
     def construct_generator(self):
         self.STATE.gen = downsample(
-            axis=self.SETTINGS.axis, factor=self.SETTINGS.factor
+            axis=self.SETTINGS.axis, target_rate=self.SETTINGS.target_rate
         )

ezmsg/sigproc/ewmfilter.py

@@ -2,14 +2,15 @@ import asyncio
 import typing
 
 import ezmsg.core as ez
-from ezmsg.util.messages.axisarray import AxisArray, replace
+from ezmsg.util.messages.axisarray import AxisArray
+from ezmsg.util.messages.util import replace
 import numpy as np
 
 from .window import Window, WindowSettings
 
 
 class EWMSettings(ez.Settings):
-    axis: typing.Optional[str] = None
+    axis: str | None = None
     """Name of the axis to accumulate."""
 
     zero_offset: bool = True
@@ -23,7 +24,8 @@ class EWMState(ez.State):
 
 class EWM(ez.Unit):
     """
-    Exponentially Weighted Moving Average Standardization
+    Exponentially Weighted Moving Average Standardization.
+    This is deprecated. Please use :obj:`ezmsg.sigproc.scaler.AdaptiveStandardScaler` instead.
 
     References https://stackoverflow.com/a/42926270
     """
@@ -36,6 +38,9 @@ class EWM(ez.Unit):
     OUTPUT_SIGNAL = ez.OutputStream(AxisArray)
 
     async def initialize(self) -> None:
+        ez.logger.warning(
+            "EWM/EWMFilter is deprecated and will be removed in a future version. Use AdaptiveStandardScaler instead."
+        )
         self.STATE.signal_queue = asyncio.Queue()
         self.STATE.buffer_queue = asyncio.Queue()
 
@@ -99,7 +104,7 @@ class EWMFilterSettings(ez.Settings):
     history_dur: float
     """Previous data to accumulate for standardization."""
 
-    axis: typing.Optional[str] = None
+    axis: str | None = None
     """Name of the axis to accumulate."""
 
     zero_offset: bool = True
@@ -112,7 +117,7 @@ class EWMFilter(ez.Collection):
     leads to :obj:`Window` which then feeds into :obj:`EWM` 's INPUT_BUFFER
     and another branch that feeds directly into :obj:`EWM` 's INPUT_SIGNAL.
 
-    Consider :obj:`scaler` for a more efficient alternative.
+    This is deprecated. Please use :obj:`ezmsg.sigproc.scaler.AdaptiveStandardScaler` instead.
     """
 
     SETTINGS = EWMFilterSettings