ezmsg-sigproc 2.6.0__tar.gz → 2.8.0__tar.gz

ezmsg_sigproc-2.8.0/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: ezmsg-sigproc
+Version: 2.8.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>, Kyle McGraw <kmcgraw@blackrockneuro.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10.15
+Requires-Dist: array-api-compat>=1.11.1
+Requires-Dist: ezmsg-baseproc>=1.1.0
+Requires-Dist: ezmsg>=3.6.0
+Requires-Dist: numba>=0.61.0
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: pywavelets>=1.6.0
+Requires-Dist: scipy>=1.13.1
+Requires-Dist: sparse>=0.15.4
+Description-Content-Type: text/markdown
+
+# ezmsg-sigproc
+
+Signal processing primitives for the [ezmsg](https://www.ezmsg.org) message-passing framework.
+
+## Features
+
+* **Filtering** - Chebyshev, comb filters, and more
+* **Spectral analysis** - Spectrogram, spectrum, and wavelet transforms
+* **Resampling** - Downsample, decimate, and resample operations
+* **Windowing** - Sliding windows and buffering utilities
+* **Math operations** - Arithmetic, log, abs, difference, and more
+* **Signal generation** - Synthetic signal generators
+
+All modules use `AxisArray` as the primary data structure for passing signals between components.
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install ezmsg-sigproc
+```
+
+Or install from GitHub for the latest development version:
+
+```bash
+pip install git+https://github.com/ezmsg-org/ezmsg-sigproc.git@dev
+```
+
+## Documentation
+
+Full documentation is available at [ezmsg.org](https://www.ezmsg.org).
+
+## Development
+
+We use [`uv`](https://docs.astral.sh/uv/) for development.
+
+1. Fork and clone the repository
+2. `uv sync` to create a virtual environment and install dependencies
+3. `uv run pre-commit install` to set up linting and formatting hooks
+4. `uv run pytest tests` to run the test suite
+5. Submit a PR against the `dev` branch

ezmsg_sigproc-2.8.0/README.md

@@ -0,0 +1,42 @@
+# ezmsg-sigproc
+
+Signal processing primitives for the [ezmsg](https://www.ezmsg.org) message-passing framework.
+
+## Features
+
+* **Filtering** - Chebyshev, comb filters, and more
+* **Spectral analysis** - Spectrogram, spectrum, and wavelet transforms
+* **Resampling** - Downsample, decimate, and resample operations
+* **Windowing** - Sliding windows and buffering utilities
+* **Math operations** - Arithmetic, log, abs, difference, and more
+* **Signal generation** - Synthetic signal generators
+
+All modules use `AxisArray` as the primary data structure for passing signals between components.
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install ezmsg-sigproc
+```
+
+Or install from GitHub for the latest development version:
+
+```bash
+pip install git+https://github.com/ezmsg-org/ezmsg-sigproc.git@dev
+```
+
+## Documentation
+
+Full documentation is available at [ezmsg.org](https://www.ezmsg.org).
+
+## Development
+
+We use [`uv`](https://docs.astral.sh/uv/) for development.
+
+1. Fork and clone the repository
+2. `uv sync` to create a virtual environment and install dependencies
+3. `uv run pre-commit install` to set up linting and formatting hooks
+4. `uv run pytest tests` to run the test suite
+5. Submit a PR against the `dev` branch

ezmsg_sigproc-2.8.0/docs/source/api/index.rst

@@ -0,0 +1,11 @@
+API Reference
+=============
+
+This page contains auto-generated API reference documentation.
+
+.. autosummary::
+   :toctree: generated
+   :recursive:
+   :template: autosummary/module.rst
+
+   ezmsg.sigproc

{ezmsg_sigproc-2.6.0 → ezmsg_sigproc-2.8.0}/docs/source/guides/explanations/sigproc.rst

@@ -329,7 +329,7 @@ Often, all that is required is the following (e.g., for a custom transformer):
 
   import ezmsg.core as ez
   from ezmsg.util.messages.axisarray import AxisArray
-  from ezmsg.sigproc.base import BaseTransformer, BaseTransformerUnit
+  from ezmsg.baseproc import BaseTransformer, BaseTransformerUnit
 
 
   class CustomTransformerSettings(ez.Settings):

ezmsg_sigproc-2.8.0/docs/source/guides/sigproc/architecture.rst

@@ -0,0 +1,41 @@
+Architecture & Usage Patterns
+=============================
+
+This page describes the architecture of ezmsg-sigproc and different ways to use its components.
+
+Operating Styles: Standalone vs. Pipelines
+------------------------------------------
+
+While each processor is designed to be assembled into an ezmsg pipeline, the components are also well-suited for offline, ad-hoc analysis. You can instantiate processors directly in scripts or notebooks for quick prototyping or to validate results from other code. The companion Unit wrappers, however, are meant for assembling processors into a full ezmsg pipeline.
+
+A fully defined ezmsg pipeline shines in online streaming scenarios where message routing, scheduling, and latency handling are crucial. Nevertheless, you can run the same pipeline offline—say, within a Jupyter notebook—if your analysis benefits from ezmsg's structured execution model.
+
+Deciding between a standalone processor and a full pipeline comes down to the trade-off between simplicity and the operational overhead of the pipeline:
+
+* **Standalone processors**: Low overhead, ideal for one-off or exploratory offline tasks.
+* **Pipeline + Unit wrappers**: Additional setup cost but bring concurrency, standardized interfaces, and automatic message flow—useful when your offline experiment mirrors a live system or when you require fine-grained pipeline behavior.
+
+Source Layout
+-------------
+
+All source resides under ``src/ezmsg/sigproc``, which contains:
+
+* A suite of processors (for example, ``filter.py``, ``spectrogram.py``, ``spectrum.py``, ``sampler.py``)
+* ``math/`` and ``util/`` subpackages for mathematical operations and utilities
+
+Key Modules
+^^^^^^^^^^^
+
+* **base.py** (via ``ezmsg.baseproc``): Defines standard protocols—Processor, Producer, Consumer, and Transformer—that enable both stateless and stateful processing chains.
+* **filter.py**: Provides settings dataclasses and a stateful transformer that applies supplied coefficients to incoming data.
+* **spectrogram.py**: Implements spectral analysis using a composite transformer chaining windowing, spectrum computation, and axis adjustments.
+
+Where to Learn Next
+-------------------
+
+* Study the :doc:`base` page to master the processor architecture.
+* Explore unit tests in the repository for hands-on examples of composing processors and Units.
+* Review the `ezmsg framework <https://www.ezmsg.org>`_ to understand the surrounding ecosystem.
+* Experiment with the code—try running processors standalone and then integrate them into a small pipeline to observe the trade-offs firsthand.
+
+This approach equips newcomers to choose the right level of abstraction—raw processor, Unit wrapper, or full pipeline—based on the demands of their analysis or streaming application.

{ezmsg_sigproc-2.6.0 → ezmsg_sigproc-2.8.0}/docs/source/guides/sigproc/content-sigproc.rst

@@ -17,6 +17,7 @@ This may occur when the generator receives inadequate data to produce a valid ou
 .. toctree::
     :maxdepth: 1
 
+    architecture
     base
     units
     processors

{ezmsg_sigproc-2.6.0 → ezmsg_sigproc-2.8.0}/docs/source/guides/tutorials/signalprocessing.rst

@@ -132,7 +132,7 @@ Add the following import statements to the top of the `downsample.py` file:
     )
     import ezmsg.core as ez
 
-    from ezmsg.sigproc.base import (
+    from ezmsg.baseproc import (
         BaseStatefulTransformer,
         BaseTransformerUnit,
         processor_state,

ezmsg_sigproc-2.8.0/docs/source/index.md

@@ -0,0 +1,20 @@
+```{include} ../../README.md
+```
+
+## Documentation
+
+```{toctree}
+:maxdepth: 2
+:caption: Contents:
+
+guides/sigproc/content-sigproc
+guides/HybridBuffer
+guides/how-tos/signalprocessing/content-signalprocessing
+guides/tutorials/signalprocessing
+api/index
+```
+
+## Indices and tables
+
+- {ref}`genindex`
+- {ref}`modindex`

{ezmsg_sigproc-2.6.0 → ezmsg_sigproc-2.8.0}/pyproject.toml

@@ -13,7 +13,7 @@ requires-python = ">=3.10.15"
 dynamic = ["version"]
 dependencies = [
   "array-api-compat>=1.11.1",
-  "ezmsg-baseproc>=1.0.3",
+  "ezmsg-baseproc>=1.1.0",
   "ezmsg>=3.6.0",
   "numba>=0.61.0",
   "numpy>=1.26.0",

{ezmsg_sigproc-2.6.0 → ezmsg_sigproc-2.8.0}/src/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-2.6.0 → ezmsg_sigproc-2.8.0}/src/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-2.6.0 → ezmsg_sigproc-2.8.0}/src/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-2.6.0 → ezmsg_sigproc-2.8.0}/src/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-2.6.0 → ezmsg_sigproc-2.8.0}/src/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-2.6.0 → ezmsg_sigproc-2.8.0}/src/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-2.6.0 → ezmsg_sigproc-2.8.0}/src/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-2.8.0/src/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-2.6.0 → ezmsg_sigproc-2.8.0}/src/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-2.6.0 → ezmsg_sigproc-2.8.0}/src/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-2.6.0 → ezmsg_sigproc-2.8.0}/src/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-2.6.0 → ezmsg_sigproc-2.8.0}/src/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-2.6.0 → ezmsg_sigproc-2.8.0}/src/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):
     """