ezmsg-sigproc 1.5.0__tar.gz → 1.6.0__tar.gz

{ezmsg_sigproc-1.5.0 → ezmsg_sigproc-1.6.0}/.github/workflows/python-tests.yml

@@ -13,7 +13,7 @@ jobs:
   build:
     strategy:
       matrix:
-        python-version: [3.9, "3.10", "3.11", "3.12"]
+        python-version: ["3.10", "3.11", "3.12"]
         os:
           - "ubuntu-latest"
           - "windows-latest"

{ezmsg_sigproc-1.5.0 → ezmsg_sigproc-1.6.0}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.3
 Name: ezmsg-sigproc
-Version: 1.5.0
+Version: 1.6.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>
 License: MIT
-Requires-Python: >=3.9
+Requires-Python: >=3.10.15
 Requires-Dist: ezmsg>=3.6.0
 Requires-Dist: numpy>=1.26.0
 Requires-Dist: pywavelets>=1.6.0

{ezmsg_sigproc-1.5.0 → ezmsg_sigproc-1.6.0}/pyproject.toml

@@ -8,7 +8,7 @@ authors = [
 ]
 license = "MIT"
 readme = "README.md"
-requires-python = ">=3.9"
+requires-python = ">=3.10.15"
 dynamic = ["version"]
 dependencies = [
     "ezmsg>=3.6.0",

{ezmsg_sigproc-1.5.0 → ezmsg_sigproc-1.6.0}/src/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.6.0'
+__version_tuple__ = version_tuple = (1, 6, 0)

{ezmsg_sigproc-1.5.0 → ezmsg_sigproc-1.6.0}/src/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-1.5.0 → ezmsg_sigproc-1.6.0}/src/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-1.5.0 → ezmsg_sigproc-1.6.0}/src/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-1.5.0 → ezmsg_sigproc-1.6.0}/src/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-1.6.0/src/ezmsg/sigproc/butterworthfilter.py

@@ -0,0 +1,160 @@
+import functools
+import typing
+
+import scipy.signal
+from ezmsg.util.messages.axisarray import AxisArray
+from scipy.signal import normalize
+
+from .filter import (
+    FilterBaseSettings,
+    FilterCoefsMultiType,
+    FilterBase,
+    filter_gen_by_design,
+)
+
+
+class ButterworthFilterSettings(FilterBaseSettings):
+    """Settings for :obj:`ButterworthFilter`."""
+
+    order: int = 0
+    """
+    Filter order
+    """
+
+    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. 
+    """
+
+    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,
+    ) -> tuple[str, float | tuple[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 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: str | None,
+    order: int = 0,
+    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.
+
+    Args:
+        axis: The name of the axis to filter.
+            Note: The axis must be represented in the message .axes and be of type AxisArray.LinearAxis.
+        order: Filter order.
+        cuton: Corner frequency of the filter in Hz.
+        cutoff: Corner frequency of the filter in Hz.
+        coef_type: "ba" or "sos"
+
+    Returns:
+        A primed generator object which accepts an :obj:`AxisArray` via .send(axis_array)
+         and yields an :obj:`AxisArray` with filtered data.
+
+    """
+    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-1.6.0/src/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-1.5.0 → ezmsg_sigproc-1.6.0}/src/ezmsg/sigproc/decimate.py

@@ -1,9 +1,8 @@
-import scipy.signal
 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
 
 
 class Decimate(ez.Collection):
@@ -17,24 +16,21 @@ class Decimate(ez.Collection):
     INPUT_SIGNAL = ez.InputStream(AxisArray)
     OUTPUT_SIGNAL = ez.OutputStream(AxisArray)
 
-    FILTER = Filter()
+    FILTER = ChebyshevFilter()
     DOWNSAMPLE = Downsample()
 
     def configure(self) -> None:
+        cheby_settings = ChebyshevFilterSettings(
+            order=8 if self.SETTINGS.factor > 1 else 0,
+            ripple_tol=0.05,
+            Wn=0.8 / self.SETTINGS.factor if self.SETTINGS.factor > 1 else None,
+            btype="lowpass",
+            axis=self.SETTINGS.axis,
+            wn_hz=False,
+        )
+        self.FILTER.apply_settings(cheby_settings)
         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))
-
     def network(self) -> ez.NetworkDefinition:
         return (
             (self.INPUT_SIGNAL, self.FILTER.INPUT_SIGNAL),

{ezmsg_sigproc-1.5.0 → ezmsg_sigproc-1.6.0}/src/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, factor: int = 1
 ) -> typing.Generator[AxisArray, AxisArray, None]:
     """
     Construct a generator that yields a downsampled version of the data .send() to it.
@@ -96,7 +96,7 @@ class DownsampleSettings(ez.Settings):
     See :obj:`downsample` documentation for a description of the parameters.
     """
 
-    axis: typing.Optional[str] = None
+    axis: str | None = None
     factor: int = 1
 
 

{ezmsg_sigproc-1.5.0 → ezmsg_sigproc-1.6.0}/src/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