ezmsg-sigproc 2.7.0__tar.gz → 2.9.0__tar.gz

{ezmsg_sigproc-2.7.0 → ezmsg_sigproc-2.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ezmsg-sigproc
-Version: 2.7.0
+Version: 2.9.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

ezmsg_sigproc-2.9.0/docs/source/guides/explanations/array_api.rst

@@ -0,0 +1,156 @@
+Array API Support
+=================
+
+ezmsg-sigproc provides support for the `Python Array API standard
+<https://data-apis.org/array-api/>`_, enabling many transformers to work with
+arrays from different backends such as NumPy, CuPy, PyTorch, and JAX.
+
+What is the Array API?
+----------------------
+
+The Array API is a standardized interface for array operations across different
+Python array libraries. By coding to this standard, ezmsg-sigproc transformers
+can process data regardless of which array library created it, enabling:
+
+- **GPU acceleration** via CuPy or PyTorch tensors
+- **Framework interoperability** for integration with ML pipelines
+- **Hardware flexibility** without code changes
+
+How It Works
+------------
+
+Compatible transformers use `array-api-compat <https://github.com/data-apis/array-api-compat>`_
+to detect the input array's namespace and use the appropriate operations:
+
+.. code-block:: python
+
+    from array_api_compat import get_namespace
+
+    def _process(self, message: AxisArray) -> AxisArray:
+        xp = get_namespace(message.data)  # numpy, cupy, torch, etc.
+        result = xp.abs(message.data)     # Uses the correct backend
+        return replace(message, data=result)
+
+Usage Example
+-------------
+
+Using Array API compatible transformers with CuPy for GPU acceleration:
+
+.. code-block:: python
+
+    import cupy as cp
+    from ezmsg.util.messages.axisarray import AxisArray
+    from ezmsg.sigproc.math.abs import AbsTransformer
+    from ezmsg.sigproc.math.clip import ClipTransformer, ClipSettings
+
+    # Create data on GPU
+    gpu_data = cp.random.randn(1000, 64).astype(cp.float32)
+    message = AxisArray(gpu_data, dims=["time", "ch"])
+
+    # Process entirely on GPU - no data transfer!
+    abs_transformer = AbsTransformer()
+    clip_transformer = ClipTransformer(ClipSettings(min=0.0, max=1.0))
+
+    result = clip_transformer(abs_transformer(message))
+    # result.data is still a CuPy array on GPU
+
+Compatible Modules
+------------------
+
+The following transformers fully support the Array API standard:
+
+Math Operations
+^^^^^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Module
+     - Description
+   * - :mod:`ezmsg.sigproc.math.abs`
+     - Absolute value
+   * - :mod:`ezmsg.sigproc.math.clip`
+     - Clip values to a range
+   * - :mod:`ezmsg.sigproc.math.log`
+     - Logarithm with configurable base
+   * - :mod:`ezmsg.sigproc.math.scale`
+     - Multiply by a constant
+   * - :mod:`ezmsg.sigproc.math.invert`
+     - Compute 1/x
+   * - :mod:`ezmsg.sigproc.math.difference`
+     - Subtract a constant (ConstDifferenceTransformer)
+
+Signal Processing
+^^^^^^^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Module
+     - Description
+   * - :mod:`ezmsg.sigproc.diff`
+     - Compute differences along an axis
+   * - :mod:`ezmsg.sigproc.transpose`
+     - Transpose/permute array dimensions
+   * - :mod:`ezmsg.sigproc.linear`
+     - Per-channel linear transform (scale + offset)
+   * - :mod:`ezmsg.sigproc.aggregate`
+     - Aggregate operations (AggregateTransformer only)
+
+Coordinate Transforms
+^^^^^^^^^^^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Module
+     - Description
+   * - :mod:`ezmsg.sigproc.coordinatespaces`
+     - Cartesian/polar coordinate conversions
+
+Limitations
+-----------
+
+Some operations remain NumPy-only due to lack of Array API equivalents:
+
+- **Random number generation**: Modules using ``np.random`` (e.g., ``denormalize``)
+- **SciPy operations**: Filtering (``scipy.signal.lfilter``), FFT, wavelets
+- **Advanced indexing**: Some slicing operations for metadata handling
+- **Memory layout**: ``np.require`` for contiguous array optimization (NumPy only)
+
+Metadata arrays (axis labels, coordinates) typically remain as NumPy arrays
+since they are not performance-critical.
+
+Adding Array API Support
+------------------------
+
+When contributing new transformers, follow this pattern:
+
+.. code-block:: python
+
+    from array_api_compat import get_namespace
+    from ezmsg.baseproc import BaseTransformer
+    from ezmsg.util.messages.axisarray import AxisArray
+    from ezmsg.util.messages.util import replace
+
+    class MyTransformer(BaseTransformer[MySettings, AxisArray, AxisArray]):
+        def _process(self, message: AxisArray) -> AxisArray:
+            xp = get_namespace(message.data)
+
+            # Use xp instead of np for array operations
+            result = xp.sqrt(xp.abs(message.data))
+
+            return replace(message, data=result)
+
+Key guidelines:
+
+1. Call ``get_namespace(message.data)`` at the start of ``_process``
+2. Use ``xp.function_name`` instead of ``np.function_name``
+3. Note that some functions have different names:
+   - ``np.concatenate`` → ``xp.concat``
+   - ``np.transpose`` → ``xp.permute_dims``
+4. Keep metadata operations (axis labels, etc.) as NumPy
+5. Use in-place operations (``/=``, ``*=``) where possible for efficiency

{ezmsg_sigproc-2.7.0 → ezmsg_sigproc-2.9.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.7.0 → ezmsg_sigproc-2.9.0}/docs/source/guides/sigproc/content-sigproc.rst

@@ -4,7 +4,8 @@ ezmsg-sigproc
 Timeseries signal processing implementations in ezmsg, leveraging numpy and scipy.
 Most of the methods and classes in this extension are intended to be used in building signal processing pipelines.
 They use :class:`ezmsg.util.messages.axisarray.AxisArray` as the primary data structure for passing signals between components.
-The message's data are expected to be a numpy array.
+The message's data are typically NumPy arrays, though many transformers support the
+:doc:`Array API standard <../explanations/array_api>` for use with CuPy, PyTorch, and other backends.
 
 .. note:: Some generators might yield valid :class:`AxisArray` messages with ``.data`` size of 0.
 This may occur when the generator receives inadequate data to produce a valid output, such as when windowing or buffering.
@@ -21,3 +22,4 @@ This may occur when the generator receives inadequate data to produce a valid ou
     base
     units
     processors
+    ../explanations/array_api

{ezmsg_sigproc-2.7.0 → ezmsg_sigproc-2.9.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.7.0 → ezmsg_sigproc-2.9.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.7.0'
-__version_tuple__ = version_tuple = (2, 7, 0)
+__version__ = version = '2.9.0'
+__version_tuple__ = version_tuple = (2, 9, 0)
 
 __commit_id__ = commit_id = None

{ezmsg_sigproc-2.7.0 → ezmsg_sigproc-2.9.0}/src/ezmsg/sigproc/affinetransform.py

@@ -1,3 +1,13 @@
+"""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
 
@@ -17,7 +27,6 @@ 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
@@ -39,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.7.0 → ezmsg_sigproc-2.9.0}/src/ezmsg/sigproc/aggregate.py

@@ -1,3 +1,12 @@
+"""
+Aggregation operations over arrays.
+
+.. note::
+    :obj:`AggregateTransformer` supports the :doc:`Array API standard </guides/explanations/array_api>`,
+    enabling use with NumPy, CuPy, PyTorch, and other compatible array libraries.
+    :obj:`RangedAggregateTransformer` currently requires NumPy arrays.
+"""
+
 import typing
 
 import ezmsg.core as ez

{ezmsg_sigproc-2.7.0 → ezmsg_sigproc-2.9.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.7.0 → ezmsg_sigproc-2.9.0}/src/ezmsg/sigproc/coordinatespaces.py

@@ -3,6 +3,10 @@ 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.
+
+.. note::
+    This module supports the :doc:`Array API standard </guides/explanations/array_api>`,
+    enabling use with NumPy, CuPy, PyTorch, and other compatible array libraries.
 """
 
 from enum import Enum
@@ -11,6 +15,7 @@ from typing import Tuple
 import ezmsg.core as ez
 import numpy as np
 import numpy.typing as npt
+from array_api_compat import get_namespace, is_array_api_obj
 from ezmsg.baseproc import (
     BaseTransformer,
     BaseTransformerUnit,
@@ -20,14 +25,24 @@ from ezmsg.util.messages.axisarray import AxisArray, replace
 # -- Utility functions for coordinate transformations --
 
 
+def _get_namespace_or_numpy(*args: npt.ArrayLike):
+    """Get array namespace if any arg is an array, otherwise return numpy."""
+    for arg in args:
+        if is_array_api_obj(arg):
+            return get_namespace(arg)
+    return np
+
+
 def polar2z(r: npt.ArrayLike, theta: npt.ArrayLike) -> npt.ArrayLike:
     """Convert polar coordinates to complex number representation."""
-    return r * np.exp(1j * theta)
+    xp = _get_namespace_or_numpy(r, theta)
+    return r * xp.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)
+    xp = _get_namespace_or_numpy(z)
+    return xp.abs(z), xp.atan2(xp.imag(z), xp.real(z))
 
 
 def cart2z(x: npt.ArrayLike, y: npt.ArrayLike) -> npt.ArrayLike:
@@ -37,7 +52,8 @@ def cart2z(x: npt.ArrayLike, y: npt.ArrayLike) -> npt.ArrayLike:
 
 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)
+    xp = _get_namespace_or_numpy(z)
+    return xp.real(z), xp.imag(z)
 
 
 def cart2pol(x: npt.ArrayLike, y: npt.ArrayLike) -> Tuple[npt.ArrayLike, npt.ArrayLike]:
@@ -90,6 +106,7 @@ class CoordinateSpacesTransformer(BaseTransformer[CoordinateSpacesSettings, Axis
     """
 
     def _process(self, message: AxisArray) -> AxisArray:
+        xp = get_namespace(message.data)
         axis = self.settings.axis or message.dims[-1]
         axis_idx = message.get_axis_idx(axis)
 
@@ -116,9 +133,9 @@ class CoordinateSpacesTransformer(BaseTransformer[CoordinateSpacesSettings, Axis
             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)
+        result = xp.stack([out_a, out_b], axis=axis_idx)
 
-        # Update axis labels if present
+        # Update axis labels if present (use numpy for string labels)
         axes = message.axes
         if axis in axes and hasattr(axes[axis], "data"):
             if self.settings.mode == CoordinateMode.CART2POL:

{ezmsg_sigproc-2.7.0 → ezmsg_sigproc-2.9.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.7.0 → ezmsg_sigproc-2.9.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.7.0 → ezmsg_sigproc-2.9.0}/src/ezmsg/sigproc/diff.py

@@ -1,14 +1,22 @@
+"""
+Compute differences along an axis.
+
+.. note::
+    This module supports the :doc:`Array API standard </guides/explanations/array_api>`,
+    enabling use with NumPy, CuPy, PyTorch, and other compatible array libraries.
+"""
+
 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 array_api_compat import get_namespace
+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):
@@ -40,23 +48,25 @@ class DiffTransformer(BaseStatefulTransformer[DiffSettings, AxisArray, AxisArray
                     self.state.last_time = ax_info.data[0] - 0.001
 
     def _process(self, message: AxisArray) -> AxisArray:
+        xp = get_namespace(message.data)
         axis = self.settings.axis or message.dims[0]
         ax_idx = message.get_axis_idx(axis)
 
-        diffs = np.diff(
-            np.concatenate((self.state.last_dat, message.data), axis=ax_idx),
+        diffs = xp.diff(
+            xp.concat((self.state.last_dat, message.data), axis=ax_idx),
             axis=ax_idx,
         )
         # Prepare last_dat for next iteration
         self.state.last_dat = slice_along_axis(message.data, slice(-1, None), axis=ax_idx)
-        # Scale by fs if requested. This convers the diff to a derivative. e.g., diff of position becomes velocity.
+        # Scale by fs if requested. This converts the diff to a derivative. e.g., diff of position becomes velocity.
         if self.settings.scale_by_fs:
             ax_info = message.get_axis(axis)
             if hasattr(ax_info, "data"):
+                # ax_info.data is typically numpy for metadata, so use np.diff here
                 dt = np.diff(np.concatenate(([self.state.last_time], ax_info.data)))
                 # Expand dt dims to match diffs
                 exp_sl = (None,) * ax_idx + (Ellipsis,) + (None,) * (message.data.ndim - ax_idx - 1)
-                diffs /= dt[exp_sl]
+                diffs /= xp.asarray(dt[exp_sl])
                 self.state.last_time = ax_info.data[-1]  # For next iteration
             else:
                 diffs /= ax_info.gain

{ezmsg_sigproc-2.7.0 → ezmsg_sigproc-2.9.0}/src/ezmsg/sigproc/ewma.py

@@ -139,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:
@@ -166,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-2.7.0 → ezmsg_sigproc-2.9.0}/src/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-2.7.0 → ezmsg_sigproc-2.9.0}/src/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-2.7.0 → ezmsg_sigproc-2.9.0}/src/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,

ezmsg_sigproc-2.9.0/src/ezmsg/sigproc/linear.py

@@ -0,0 +1,120 @@
+"""
+Apply a linear transformation: output = scale * input + offset.
+
+Supports per-element scale and offset along a specified axis.
+For full matrix transformations, use :obj:`AffineTransformTransformer` instead.
+
+.. note::
+    This module supports the :doc:`Array API standard </guides/explanations/array_api>`,
+    enabling use with NumPy, CuPy, PyTorch, and other compatible array libraries.
+"""
+
+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, BaseTransformerUnit, processor_state
+from ezmsg.util.messages.axisarray import AxisArray
+from ezmsg.util.messages.util import replace
+
+
+class LinearTransformSettings(ez.Settings):
+    scale: float | list[float] | npt.ArrayLike = 1.0
+    """Scale factor(s). Can be a scalar (applied to all elements) or an array
+    matching the size of the specified axis for per-element scaling."""
+
+    offset: float | list[float] | npt.ArrayLike = 0.0
+    """Offset value(s). Can be a scalar (applied to all elements) or an array
+    matching the size of the specified axis for per-element offset."""
+
+    axis: str | None = None
+    """Axis along which to apply per-element scale/offset. If None, scalar
+    scale/offset are broadcast to all elements."""
+
+
+@processor_state
+class LinearTransformState:
+    scale: npt.NDArray = None
+    """Prepared scale array for broadcasting."""
+
+    offset: npt.NDArray = None
+    """Prepared offset array for broadcasting."""
+
+
+class LinearTransformTransformer(
+    BaseStatefulTransformer[LinearTransformSettings, AxisArray, AxisArray, LinearTransformState]
+):
+    """Apply linear transformation: output = scale * input + offset.
+
+    This transformer is optimized for element-wise linear operations with
+    optional per-channel (or per-axis) coefficients. For full matrix
+    transformations, use :obj:`AffineTransformTransformer` instead.
+
+    Examples:
+        # Uniform scaling and offset
+        >>> transformer = LinearTransformTransformer(LinearTransformSettings(scale=2.0, offset=1.0))
+
+        # Per-channel scaling (e.g., for 3-channel data along "ch" axis)
+        >>> transformer = LinearTransformTransformer(LinearTransformSettings(
+        ...     scale=[0.5, 1.0, 2.0],
+        ...     offset=[0.0, 0.1, 0.2],
+        ...     axis="ch"
+        ... ))
+    """
+
+    def _hash_message(self, message: AxisArray) -> int:
+        """Hash based on shape and axis to detect when broadcast shapes need recalculation."""
+        axis = self.settings.axis
+        if axis is not None:
+            axis_idx = message.get_axis_idx(axis)
+            return hash((message.data.ndim, axis_idx, message.data.shape[axis_idx]))
+        return hash(message.data.ndim)
+
+    def _reset_state(self, message: AxisArray) -> None:
+        """Prepare scale/offset arrays with proper broadcast shapes."""
+        xp = get_namespace(message.data)
+        ndim = message.data.ndim
+
+        scale = self.settings.scale
+        offset = self.settings.offset
+
+        # Convert settings to arrays
+        if isinstance(scale, (list, np.ndarray)):
+            scale = xp.asarray(scale, dtype=xp.float64)
+        else:
+            # Scalar: create a 0-d array
+            scale = xp.asarray(float(scale), dtype=xp.float64)
+
+        if isinstance(offset, (list, np.ndarray)):
+            offset = xp.asarray(offset, dtype=xp.float64)
+        else:
+            # Scalar: create a 0-d array
+            offset = xp.asarray(float(offset), dtype=xp.float64)
+
+        # If axis is specified and we have 1-d arrays, reshape for proper broadcasting
+        if self.settings.axis is not None and ndim > 0:
+            axis_idx = message.get_axis_idx(self.settings.axis)
+
+            if scale.ndim == 1:
+                # Create shape for broadcasting: all 1s except at axis_idx
+                broadcast_shape = [1] * ndim
+                broadcast_shape[axis_idx] = scale.shape[0]
+                scale = xp.reshape(scale, broadcast_shape)
+
+            if offset.ndim == 1:
+                broadcast_shape = [1] * ndim
+                broadcast_shape[axis_idx] = offset.shape[0]
+                offset = xp.reshape(offset, broadcast_shape)
+
+        self._state.scale = scale
+        self._state.offset = offset
+
+    def _process(self, message: AxisArray) -> AxisArray:
+        result = message.data * self._state.scale + self._state.offset
+        return replace(message, data=result)
+
+
+class LinearTransform(BaseTransformerUnit[LinearTransformSettings, AxisArray, AxisArray, LinearTransformTransformer]):
+    """Unit wrapper for LinearTransformTransformer."""
+
+    SETTINGS = LinearTransformSettings