ezmsg-sigproc 2.6.0__py3-none-any.whl → 2.8.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.6.0'
-__version_tuple__ = version_tuple = (2, 6, 0)
+__version__ = version = '2.8.0'
+__version_tuple__ = version_tuple = (2, 8, 0)
 
 __commit_id__ = commit_id = None

ezmsg/sigproc/activation.py

@@ -1,9 +1,9 @@
 import ezmsg.core as ez
 import scipy.special
+from ezmsg.baseproc import BaseTransformer, BaseTransformerUnit
 from ezmsg.util.messages.axisarray import AxisArray
 from ezmsg.util.messages.util import replace
 
-from .base import BaseTransformer, BaseTransformerUnit
 from .spectral import OptionsEnum
 
 

ezmsg/sigproc/adaptive_lattice_notch.py

@@ -2,11 +2,10 @@ import ezmsg.core as ez
 import numpy as np
 import numpy.typing as npt
 import scipy.signal
+from ezmsg.baseproc import BaseStatefulTransformer, processor_state
 from ezmsg.util.messages.axisarray import AxisArray, CoordinateAxis
 from ezmsg.util.messages.util import replace
 
-from .base import BaseStatefulTransformer, processor_state
-
 
 class AdaptiveLatticeNotchFilterSettings(ez.Settings):
     """Settings for the Adaptive Lattice Notch Filter."""

ezmsg/sigproc/affinetransform.py

@@ -1,24 +1,32 @@
+"""Affine transformations via matrix multiplication: y = Ax or y = Ax + B.
+
+For full matrix transformations where channels are mixed (off-diagonal weights),
+use :obj:`AffineTransformTransformer` or the `AffineTransform` unit.
+
+For simple per-channel scaling and offset (diagonal weights only), use
+:obj:`LinearTransformTransformer` from :mod:`ezmsg.sigproc.linear` instead,
+which is more efficient as it avoids matrix multiplication.
+"""
+
 import os
 from pathlib import Path
 
 import ezmsg.core as ez
 import numpy as np
 import numpy.typing as npt
-from ezmsg.util.messages.axisarray import AxisArray, AxisBase
-from ezmsg.util.messages.util import replace
-
-from .base import (
+from ezmsg.baseproc import (
     BaseStatefulTransformer,
     BaseTransformer,
     BaseTransformerUnit,
     processor_state,
 )
+from ezmsg.util.messages.axisarray import AxisArray, AxisBase
+from ezmsg.util.messages.util import replace
 
 
 class AffineTransformSettings(ez.Settings):
     """
     Settings for :obj:`AffineTransform`.
-    See :obj:`affine_transform` for argument details.
     """
 
     weights: np.ndarray | str | Path
@@ -40,6 +48,19 @@ class AffineTransformState:
 class AffineTransformTransformer(
     BaseStatefulTransformer[AffineTransformSettings, AxisArray, AxisArray, AffineTransformState]
 ):
+    """Apply affine transformation via matrix multiplication: y = Ax or y = Ax + B.
+
+    Use this transformer when you need full matrix transformations that mix
+    channels (off-diagonal weights), such as spatial filters or projections.
+
+    For simple per-channel scaling and offset where each output channel depends
+    only on its corresponding input channel (diagonal weight matrix), use
+    :obj:`LinearTransformTransformer` instead, which is more efficient.
+
+    The weights matrix can include an offset row (stacked as [A|B]) where the
+    input is automatically augmented with a column of ones to compute y = Ax + B.
+    """
+
     def __call__(self, message: AxisArray) -> AxisArray:
         # Override __call__ so we can shortcut if weights are None.
         if self.settings.weights is None or (

ezmsg/sigproc/aggregate.py

@@ -4,6 +4,12 @@ import ezmsg.core as ez
 import numpy as np
 import numpy.typing as npt
 from array_api_compat import get_namespace
+from ezmsg.baseproc import (
+    BaseStatefulTransformer,
+    BaseTransformer,
+    BaseTransformerUnit,
+    processor_state,
+)
 from ezmsg.util.messages.axisarray import (
     AxisArray,
     AxisBase,
@@ -11,12 +17,6 @@ from ezmsg.util.messages.axisarray import (
     slice_along_axis,
 )
 
-from .base import (
-    BaseStatefulTransformer,
-    BaseTransformer,
-    BaseTransformerUnit,
-    processor_state,
-)
 from .spectral import OptionsEnum
 
 

ezmsg/sigproc/bandpower.py

@@ -1,6 +1,12 @@
 from dataclasses import field
 
 import ezmsg.core as ez
+from ezmsg.baseproc import (
+    BaseProcessor,
+    BaseStatefulProcessor,
+    BaseTransformerUnit,
+    CompositeProcessor,
+)
 from ezmsg.util.messages.axisarray import AxisArray
 
 from .aggregate import (
@@ -8,12 +14,6 @@ from .aggregate import (
     RangedAggregateSettings,
     RangedAggregateTransformer,
 )
-from .base import (
-    BaseProcessor,
-    BaseStatefulProcessor,
-    BaseTransformerUnit,
-    CompositeProcessor,
-)
 from .spectrogram import SpectrogramSettings, SpectrogramTransformer
 
 

ezmsg/sigproc/butterworthzerophase.py

@@ -4,10 +4,10 @@ import typing
 import ezmsg.core as ez
 import numpy as np
 import scipy.signal
+from ezmsg.baseproc import SettingsType
 from ezmsg.util.messages.axisarray import AxisArray
 from ezmsg.util.messages.util import replace
 
-from ezmsg.sigproc.base import SettingsType
 from ezmsg.sigproc.butterworthfilter import ButterworthFilterSettings, butter_design_fun
 from ezmsg.sigproc.filter import (
     BACoeffs,

ezmsg/sigproc/coordinatespaces.py

@@ -0,0 +1,142 @@
+"""
+Coordinate space transformations for streaming data.
+
+This module provides utilities and ezmsg nodes for transforming between
+Cartesian (x, y) and polar (r, theta) coordinate systems.
+"""
+
+from enum import Enum
+from typing import Tuple
+
+import ezmsg.core as ez
+import numpy as np
+import numpy.typing as npt
+from ezmsg.baseproc import (
+    BaseTransformer,
+    BaseTransformerUnit,
+)
+from ezmsg.util.messages.axisarray import AxisArray, replace
+
+# -- Utility functions for coordinate transformations --
+
+
+def polar2z(r: npt.ArrayLike, theta: npt.ArrayLike) -> npt.ArrayLike:
+    """Convert polar coordinates to complex number representation."""
+    return r * np.exp(1j * theta)
+
+
+def z2polar(z: npt.ArrayLike) -> Tuple[npt.ArrayLike, npt.ArrayLike]:
+    """Convert complex number to polar coordinates (r, theta)."""
+    return np.abs(z), np.angle(z)
+
+
+def cart2z(x: npt.ArrayLike, y: npt.ArrayLike) -> npt.ArrayLike:
+    """Convert Cartesian coordinates to complex number representation."""
+    return x + 1j * y
+
+
+def z2cart(z: npt.ArrayLike) -> Tuple[npt.ArrayLike, npt.ArrayLike]:
+    """Convert complex number to Cartesian coordinates (x, y)."""
+    return np.real(z), np.imag(z)
+
+
+def cart2pol(x: npt.ArrayLike, y: npt.ArrayLike) -> Tuple[npt.ArrayLike, npt.ArrayLike]:
+    """Convert Cartesian coordinates (x, y) to polar coordinates (r, theta)."""
+    return z2polar(cart2z(x, y))
+
+
+def pol2cart(r: npt.ArrayLike, theta: npt.ArrayLike) -> Tuple[npt.ArrayLike, npt.ArrayLike]:
+    """Convert polar coordinates (r, theta) to Cartesian coordinates (x, y)."""
+    return z2cart(polar2z(r, theta))
+
+
+# -- ezmsg transformer classes --
+
+
+class CoordinateMode(str, Enum):
+    """Transformation mode for coordinate conversion."""
+
+    CART2POL = "cart2pol"
+    """Convert Cartesian (x, y) to polar (r, theta)."""
+
+    POL2CART = "pol2cart"
+    """Convert polar (r, theta) to Cartesian (x, y)."""
+
+
+class CoordinateSpacesSettings(ez.Settings):
+    """
+    Settings for :obj:`CoordinateSpaces`.
+
+    See :obj:`coordinate_spaces` for argument details.
+    """
+
+    mode: CoordinateMode = CoordinateMode.CART2POL
+    """The transformation mode: 'cart2pol' or 'pol2cart'."""
+
+    axis: str | None = None
+    """
+    The name of the axis containing the coordinate components.
+    Defaults to the last axis. Must have exactly 2 elements (x,y or r,theta).
+    """
+
+
+class CoordinateSpacesTransformer(BaseTransformer[CoordinateSpacesSettings, AxisArray, AxisArray]):
+    """
+    Transform between Cartesian and polar coordinate systems.
+
+    The input must have exactly 2 elements along the specified axis:
+    - For cart2pol: expects (x, y), outputs (r, theta)
+    - For pol2cart: expects (r, theta), outputs (x, y)
+    """
+
+    def _process(self, message: AxisArray) -> AxisArray:
+        axis = self.settings.axis or message.dims[-1]
+        axis_idx = message.get_axis_idx(axis)
+
+        if message.data.shape[axis_idx] != 2:
+            raise ValueError(
+                f"Coordinate transformation requires exactly 2 elements along axis '{axis}', "
+                f"got {message.data.shape[axis_idx]}."
+            )
+
+        # Extract components along the specified axis
+        slices_a = [slice(None)] * message.data.ndim
+        slices_b = [slice(None)] * message.data.ndim
+        slices_a[axis_idx] = 0
+        slices_b[axis_idx] = 1
+
+        component_a = message.data[tuple(slices_a)]
+        component_b = message.data[tuple(slices_b)]
+
+        if self.settings.mode == CoordinateMode.CART2POL:
+            # Input: x, y -> Output: r, theta
+            out_a, out_b = cart2pol(component_a, component_b)
+        else:
+            # Input: r, theta -> Output: x, y
+            out_a, out_b = pol2cart(component_a, component_b)
+
+        # Stack results back along the same axis
+        result = np.stack([out_a, out_b], axis=axis_idx)
+
+        # Update axis labels if present
+        axes = message.axes
+        if axis in axes and hasattr(axes[axis], "data"):
+            if self.settings.mode == CoordinateMode.CART2POL:
+                new_labels = np.array(["r", "theta"])
+            else:
+                new_labels = np.array(["x", "y"])
+            axes = {**axes, axis: replace(axes[axis], data=new_labels)}
+
+        return replace(message, data=result, axes=axes)
+
+
+class CoordinateSpaces(
+    BaseTransformerUnit[CoordinateSpacesSettings, AxisArray, AxisArray, CoordinateSpacesTransformer]
+):
+    """
+    Unit for transforming between Cartesian and polar coordinate systems.
+
+    See :obj:`CoordinateSpacesSettings` for configuration options.
+    """
+
+    SETTINGS = CoordinateSpacesSettings

ezmsg/sigproc/decimate.py

@@ -1,9 +1,9 @@
 import typing
 
 import ezmsg.core as ez
+from ezmsg.baseproc import BaseTransformerUnit
 from ezmsg.util.messages.axisarray import AxisArray
 
-from .base import BaseTransformerUnit
 from .cheby import ChebyshevFilterSettings, ChebyshevFilterTransformer
 from .downsample import Downsample, DownsampleSettings
 from .filter import BACoeffs, SOSCoeffs

ezmsg/sigproc/denormalize.py

@@ -1,14 +1,13 @@
 import ezmsg.core as ez
 import numpy as np
 import numpy.typing as npt
-from ezmsg.util.messages.axisarray import AxisArray
-from ezmsg.util.messages.util import replace
-
-from ezmsg.sigproc.base import (
+from ezmsg.baseproc import (
     BaseStatefulTransformer,
     BaseTransformerUnit,
     processor_state,
 )
+from ezmsg.util.messages.axisarray import AxisArray
+from ezmsg.util.messages.util import replace
 
 
 class DenormalizeSettings(ez.Settings):

ezmsg/sigproc/detrend.py

@@ -1,7 +1,7 @@
 import scipy.signal as sps
+from ezmsg.baseproc import BaseTransformerUnit
 from ezmsg.util.messages.axisarray import AxisArray, replace
 
-from ezmsg.sigproc.base import BaseTransformerUnit
 from ezmsg.sigproc.ewma import EWMASettings, EWMATransformer
 
 

ezmsg/sigproc/diff.py

@@ -1,14 +1,13 @@
 import ezmsg.core as ez
 import numpy as np
 import numpy.typing as npt
-from ezmsg.util.messages.axisarray import AxisArray, slice_along_axis
-from ezmsg.util.messages.util import replace
-
-from ezmsg.sigproc.base import (
+from ezmsg.baseproc import (
     BaseStatefulTransformer,
     BaseTransformerUnit,
     processor_state,
 )
+from ezmsg.util.messages.axisarray import AxisArray, slice_along_axis
+from ezmsg.util.messages.util import replace
 
 
 class DiffSettings(ez.Settings):

ezmsg/sigproc/downsample.py

@@ -1,17 +1,16 @@
 import ezmsg.core as ez
 import numpy as np
+from ezmsg.baseproc import (
+    BaseStatefulTransformer,
+    BaseTransformerUnit,
+    processor_state,
+)
 from ezmsg.util.messages.axisarray import (
     AxisArray,
     replace,
     slice_along_axis,
 )
 
-from .base import (
-    BaseStatefulTransformer,
-    BaseTransformerUnit,
-    processor_state,
-)
-
 
 class DownsampleSettings(ez.Settings):
     """

ezmsg/sigproc/ewma.py

@@ -5,11 +5,10 @@ import ezmsg.core as ez
 import numpy as np
 import numpy.typing as npt
 import scipy.signal as sps
+from ezmsg.baseproc import BaseStatefulTransformer, BaseTransformerUnit, processor_state
 from ezmsg.util.messages.axisarray import AxisArray, slice_along_axis
 from ezmsg.util.messages.util import replace
 
-from .base import BaseStatefulTransformer, BaseTransformerUnit, processor_state
-
 
 def _tau_from_alpha(alpha: float, dt: float) -> float:
     """
@@ -140,8 +139,15 @@ class EWMA_Deprecated:
 
 class EWMASettings(ez.Settings):
     time_constant: float = 1.0
+    """The amount of time for the smoothed response of a unit step function to reach 1 - 1/e approx-eq 63.2%."""
+
     axis: str | None = None
 
+    accumulate: bool = True
+    """If True, update the EWMA state with each sample. If False, only apply
+    the current EWMA estimate without updating state (useful for inference
+    periods where you don't want to adapt statistics)."""
+
 
 @processor_state
 class EWMAState:
@@ -167,15 +173,45 @@ class EWMATransformer(BaseStatefulTransformer[EWMASettings, AxisArray, AxisArray
             return message
         axis = self.settings.axis or message.dims[0]
         axis_idx = message.get_axis_idx(axis)
-        expected, self._state.zi = sps.lfilter(
-            [self._state.alpha],
-            [1.0, self._state.alpha - 1.0],
-            message.data,
-            axis=axis_idx,
-            zi=self._state.zi,
-        )
+        if self.settings.accumulate:
+            # Normal behavior: update state with new samples
+            expected, self._state.zi = sps.lfilter(
+                [self._state.alpha],
+                [1.0, self._state.alpha - 1.0],
+                message.data,
+                axis=axis_idx,
+                zi=self._state.zi,
+            )
+        else:
+            # Process-only: compute output without updating state
+            expected, _ = sps.lfilter(
+                [self._state.alpha],
+                [1.0, self._state.alpha - 1.0],
+                message.data,
+                axis=axis_idx,
+                zi=self._state.zi,
+            )
         return replace(message, data=expected)
 
 
 class EWMAUnit(BaseTransformerUnit[EWMASettings, AxisArray, AxisArray, EWMATransformer]):
     SETTINGS = EWMASettings
+
+    @ez.subscriber(BaseTransformerUnit.INPUT_SETTINGS)
+    async def on_settings(self, msg: EWMASettings) -> None:
+        """
+        Handle settings updates with smart reset behavior.
+
+        Only resets state if `axis` changes (structural change).
+        Changes to `time_constant` or `accumulate` are applied without
+        resetting accumulated state.
+        """
+        old_axis = self.SETTINGS.axis
+        self.apply_settings(msg)
+
+        if msg.axis != old_axis:
+            # Axis changed - need full reset
+            self.create_processor()
+        else:
+            # Only accumulate or time_constant changed - keep state
+            self.processor.settings = msg

ezmsg/sigproc/extract_axis.py

@@ -1,9 +1,8 @@
 import ezmsg.core as ez
 import numpy as np
+from ezmsg.baseproc import BaseTransformer, BaseTransformerUnit
 from ezmsg.util.messages.axisarray import AxisArray, replace
 
-from ezmsg.sigproc.base import BaseTransformer, BaseTransformerUnit
-
 
 class ExtractAxisSettings(ez.Settings):
     axis: str = "freq"

ezmsg/sigproc/fbcca.py

@@ -4,16 +4,16 @@ from dataclasses import field
 
 import ezmsg.core as ez
 import numpy as np
-from ezmsg.util.messages.axisarray import AxisArray
-from ezmsg.util.messages.util import replace
-
-from .base import (
+from ezmsg.baseproc import (
     BaseProcessor,
     BaseStatefulProcessor,
     BaseTransformer,
     BaseTransformerUnit,
     CompositeProcessor,
 )
+from ezmsg.util.messages.axisarray import AxisArray
+from ezmsg.util.messages.util import replace
+
 from .filterbankdesign import (
     FilterbankDesignSettings,
     FilterbankDesignTransformer,

ezmsg/sigproc/filter.py

@@ -6,10 +6,7 @@ import ezmsg.core as ez
 import numpy as np
 import numpy.typing as npt
 import scipy.signal
-from ezmsg.util.messages.axisarray import AxisArray
-from ezmsg.util.messages.util import replace
-
-from ezmsg.sigproc.base import (
+from ezmsg.baseproc import (
     BaseConsumerUnit,
     BaseStatefulTransformer,
     BaseTransformerUnit,
@@ -17,6 +14,8 @@ from ezmsg.sigproc.base import (
     TransformerType,
     processor_state,
 )
+from ezmsg.util.messages.axisarray import AxisArray
+from ezmsg.util.messages.util import replace
 
 
 @dataclass

ezmsg/sigproc/filterbank.py

@@ -7,15 +7,15 @@ import numpy as np
 import numpy.typing as npt
 import scipy.fft as sp_fft
 import scipy.signal as sps
-from ezmsg.util.messages.axisarray import AxisArray
-from ezmsg.util.messages.util import replace
-from scipy.special import lambertw
-
-from .base import (
+from ezmsg.baseproc import (
     BaseStatefulTransformer,
     BaseTransformerUnit,
     processor_state,
 )
+from ezmsg.util.messages.axisarray import AxisArray
+from ezmsg.util.messages.util import replace
+from scipy.special import lambertw
+
 from .spectrum import OptionsEnum
 from .window import WindowTransformer
 

ezmsg/sigproc/filterbankdesign.py

@@ -3,13 +3,13 @@ import typing
 import ezmsg.core as ez
 import numpy as np
 import numpy.typing as npt
-from ezmsg.util.messages.axisarray import AxisArray
-from ezmsg.util.messages.util import replace
-
-from .base import (
+from ezmsg.baseproc import (
     BaseStatefulTransformer,
     processor_state,
 )
+from ezmsg.util.messages.axisarray import AxisArray
+from ezmsg.util.messages.util import replace
+
 from .filterbank import (
     FilterbankMode,
     FilterbankSettings,

ezmsg/sigproc/fir_hilbert.py

@@ -4,10 +4,10 @@ import typing
 import ezmsg.core as ez
 import numpy as np
 import scipy.signal as sps
+from ezmsg.baseproc import BaseStatefulTransformer, processor_state
 from ezmsg.util.messages.axisarray import AxisArray
 from ezmsg.util.messages.util import replace
 
-from ezmsg.sigproc.base import BaseStatefulTransformer, processor_state
 from ezmsg.sigproc.filter import (
     BACoeffs,
     BaseFilterByDesignTransformerUnit,