ezmsg-sigproc 1.8.1__py3-none-any.whl → 2.0.0__py3-none-any.whl

ezmsg/sigproc/affinetransform.py

@@ -1,112 +1,112 @@
 import os
 from pathlib import Path
-import typing
 
 import numpy as np
 import numpy.typing as npt
 import ezmsg.core as ez
 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
+from .base import (
+    BaseStatefulTransformer,
+    BaseTransformerUnit,
+    BaseTransformer,
+    processor_state,
+)
 
 
-@consumer
-def affine_transform(
-    weights: np.ndarray | str | Path,
-    axis: str | None = None,
-    right_multiply: bool = True,
-) -> typing.Generator[AxisArray, AxisArray, None]:
+class AffineTransformSettings(ez.Settings):
+    """
+    Settings for :obj:`AffineTransform`.
+    See :obj:`affine_transform` for argument details.
     """
-    Perform affine transformations on streaming data.
 
-    Args:
-        weights: An array of weights or a path to a file with weights compatible with np.loadtxt.
-        axis: The name of the axis to apply the transformation to. Defaults to the leading (0th) axis in the array.
-        right_multiply: Set False to transpose the weights before applying.
+    weights: np.ndarray | str | Path
+    """An array of weights or a path to a file with weights compatible with np.loadtxt."""
 
-    Returns:
-        A primed generator object that yields an :obj:`AxisArray` object for every
-        :obj:`AxisArray` it receives via `send`.
-    """
-    msg_out = AxisArray(np.array([]), dims=[""])
+    axis: str | None = None
+    """The name of the axis to apply the transformation to. Defaults to the leading (0th) axis in the array."""
 
-    # Check parameters
-    if isinstance(weights, str):
-        if weights == "passthrough":
-            weights = None
-        else:
-            weights = Path(os.path.abspath(os.path.expanduser(weights)))
-    if isinstance(weights, Path):
-        weights = np.loadtxt(weights, delimiter=",")
-    if not right_multiply:
-        weights = weights.T
-    if weights is not None:
-        weights = np.ascontiguousarray(weights)
-
-    # State variables
-    # New axis with transformed labels, if required
+    right_multiply: bool = True
+    """Set False to transpose the weights before applying."""
+
+
+@processor_state
+class AffineTransformState:
+    weights: npt.NDArray | None = None
     new_axis: AxisBase | None = None
 
-    # Reset if any of these change.
-    check_input = {"key": None}
-    # We assume key change catches labels change; we don't want to check labels every message
-    # We don't need to check if input size has changed because weights multiplication will fail if so.
-
-    while True:
-        msg_in: AxisArray = yield msg_out
-
-        if weights is None:
-            msg_out = msg_in
-            continue
-
-        axis = axis or msg_in.dims[-1]  # Note: Most nodes default do dim[0]
-        axis_idx = msg_in.get_axis_idx(axis)
-
-        b_reset = msg_in.key != check_input["key"]
-        if b_reset:
-            # First sample or key has changed. Reset the state.
-            check_input["key"] = msg_in.key
-            # Determine if we need to modify the transformed axis.
-            if (
-                axis in msg_in.axes
-                and hasattr(msg_in.axes[axis], "data")
-                and weights.shape[0] != weights.shape[1]
-            ):
-                in_labels = msg_in.axes[axis].data
-                new_labels = []
-                n_in, n_out = weights.shape
-                if len(in_labels) != n_in:
-                    # Something upstream did something it wasn't supposed to. We will drop the labels.
-                    ez.logger.warning(
-                        f"Received {len(in_labels)} for {n_in} inputs. Check upstream labels."
-                    )
-                else:
-                    b_filled_outputs = np.any(weights, axis=0)
-                    b_used_inputs = np.any(weights, axis=1)
-                    if np.all(b_used_inputs) and np.all(b_filled_outputs):
-                        # All inputs are used and all outputs are used, but n_in != n_out.
-                        # Mapping cannot be determined.
-                        new_labels = []
-                    elif np.all(b_used_inputs):
-                        # Strange scenario: New outputs are filled with empty data.
-                        in_ix = 0
-                        new_labels = []
-                        for out_ix in range(n_out):
-                            if b_filled_outputs[out_ix]:
-                                new_labels.append(in_labels[in_ix])
-                                in_ix += 1
-                            else:
-                                new_labels.append("")
-                    elif np.all(b_filled_outputs):
-                        # Transform is dropping some of the inputs.
-                        new_labels = np.array(in_labels)[b_used_inputs]
-                new_axis = replace(msg_in.axes[axis], data=np.array(new_labels))
-
-        data = msg_in.data
-
-        if data.shape[axis_idx] == (weights.shape[0] - 1):
+
+class AffineTransformTransformer(
+    BaseStatefulTransformer[
+        AffineTransformSettings, AxisArray, AxisArray, AffineTransformState
+    ]
+):
+    def __call__(self, message: AxisArray) -> AxisArray:
+        # Override __call__ so we can shortcut if weights are None.
+        if self.settings.weights is None or (
+            isinstance(self.settings.weights, str)
+            and self.settings.weights == "passthrough"
+        ):
+            return message
+        return super().__call__(message)
+
+    def _hash_message(self, message: AxisArray) -> int:
+        return hash(message.key)
+
+    def _reset_state(self, message: AxisArray) -> None:
+        weights = self.settings.weights
+        if isinstance(weights, str):
+            weights = Path(os.path.abspath(os.path.expanduser(weights)))
+        if isinstance(weights, Path):
+            weights = np.loadtxt(weights, delimiter=",")
+        if not self.settings.right_multiply:
+            weights = weights.T
+        if weights is not None:
+            weights = np.ascontiguousarray(weights)
+
+        self._state.weights = weights
+
+        axis = self.settings.axis or message.dims[-1]
+        if (
+            axis in message.axes
+            and hasattr(message.axes[axis], "data")
+            and weights.shape[0] != weights.shape[1]
+        ):
+            in_labels = message.axes[axis].data
+            new_labels = []
+            n_in, n_out = weights.shape
+            if len(in_labels) != n_in:
+                ez.logger.warning(
+                    f"Received {len(in_labels)} for {n_in} inputs. Check upstream labels."
+                )
+            else:
+                b_filled_outputs = np.any(weights, axis=0)
+                b_used_inputs = np.any(weights, axis=1)
+                if np.all(b_used_inputs) and np.all(b_filled_outputs):
+                    new_labels = []
+                elif np.all(b_used_inputs):
+                    in_ix = 0
+                    new_labels = []
+                    for out_ix in range(n_out):
+                        if b_filled_outputs[out_ix]:
+                            new_labels.append(in_labels[in_ix])
+                            in_ix += 1
+                        else:
+                            new_labels.append("")
+                elif np.all(b_filled_outputs):
+                    new_labels = np.array(in_labels)[b_used_inputs]
+
+            self._state.new_axis = replace(
+                message.axes[axis], data=np.array(new_labels)
+            )
+
+    def _process(self, message: AxisArray) -> AxisArray:
+        axis = self.settings.axis or message.dims[-1]
+        axis_idx = message.get_axis_idx(axis)
+        data = message.data
+
+        if data.shape[axis_idx] == (self._state.weights.shape[0] - 1):
             # The weights are stacked A|B where A is the transform and B is a single row
             #  in the equation y = Ax + B. This supports NeuroKey's weights matrices.
             sample_shape = data.shape[:axis_idx] + (1,) + data.shape[axis_idx + 1 :]
@@ -114,82 +114,87 @@ def affine_transform(
                 (data, np.ones(sample_shape).astype(data.dtype)), axis=axis_idx
             )
 
-        if axis_idx in [-1, len(msg_in.dims) - 1]:
-            data = np.matmul(data, weights)
+        if axis_idx in [-1, len(message.dims) - 1]:
+            data = np.matmul(data, self._state.weights)
         else:
             data = np.moveaxis(data, axis_idx, -1)
-            data = np.matmul(data, weights)
+            data = np.matmul(data, self._state.weights)
             data = np.moveaxis(data, -1, axis_idx)
 
         replace_kwargs = {"data": data}
-        if new_axis is not None:
-            replace_kwargs["axes"] = {**msg_in.axes, axis: new_axis}
-        msg_out = replace(msg_in, **replace_kwargs)
+        if self._state.new_axis is not None:
+            replace_kwargs["axes"] = {**message.axes, axis: self._state.new_axis}
 
+        return replace(message, **replace_kwargs)
 
-class AffineTransformSettings(ez.Settings):
-    """
-    Settings for :obj:`AffineTransform`.
-    See :obj:`affine_transform` for argument details.
-    """
 
-    weights: np.ndarray | str | Path
-    axis: str | None = None
-    right_multiply: bool = True
+class AffineTransform(
+    BaseTransformerUnit[
+        AffineTransformSettings, AxisArray, AxisArray, AffineTransformTransformer
+    ]
+):
+    SETTINGS = AffineTransformSettings
 
 
-class AffineTransform(GenAxisArray):
-    """:obj:`Unit` for :obj:`affine_transform`"""
+def affine_transform(
+    weights: np.ndarray | str | Path,
+    axis: str | None = None,
+    right_multiply: bool = True,
+) -> AffineTransformTransformer:
+    """
+    Perform affine transformations on streaming data.
 
-    SETTINGS = AffineTransformSettings
+    Args:
+        weights: An array of weights or a path to a file with weights compatible with np.loadtxt.
+        axis: The name of the axis to apply the transformation to. Defaults to the leading (0th) axis in the array.
+        right_multiply: Set False to transpose the weights before applying.
 
-    def construct_generator(self):
-        self.STATE.gen = affine_transform(
-            weights=self.SETTINGS.weights,
-            axis=self.SETTINGS.axis,
-            right_multiply=self.SETTINGS.right_multiply,
+    Returns:
+        :obj:`AffineTransformTransformer`.
+    """
+    return AffineTransformTransformer(
+        AffineTransformSettings(
+            weights=weights, axis=axis, right_multiply=right_multiply
         )
+    )
 
 
 def zeros_for_noop(data: npt.NDArray, **ignore_kwargs) -> npt.NDArray:
     return np.zeros_like(data)
 
 
-@consumer
-def common_rereference(
-    mode: str = "mean", axis: str | None = None, include_current: bool = True
-) -> typing.Generator[AxisArray, AxisArray, None]:
+class CommonRereferenceSettings(ez.Settings):
+    """
+    Settings for :obj:`CommonRereference`
     """
-    Perform common average referencing (CAR) on streaming data.
 
-    Args:
-        mode: The statistical mode to apply -- either "mean" or "median"
-        axis: The name of hte axis to apply the transformation to.
-        include_current: Set False to exclude each channel from participating in the calculation of its reference.
+    mode: str = "mean"
+    """The statistical mode to apply -- either "mean" or "median"."""
 
-    Returns:
-        A primed generator object that yields an :obj:`AxisArray` object
-        for every :obj:`AxisArray` it receives via `send`.
-    """
-    msg_out = AxisArray(np.array([]), dims=[""])
+    axis: str | None = None
+    """The name of the axis to apply the transformation to."""
 
-    if mode == "passthrough":
-        include_current = True
+    include_current: bool = True
+    """Set False to exclude each channel from participating in the calculation of its reference."""
 
-    func = {"mean": np.mean, "median": np.median, "passthrough": zeros_for_noop}[mode]
 
-    while True:
-        msg_in: AxisArray = yield msg_out
+class CommonRereferenceTransformer(
+    BaseTransformer[CommonRereferenceSettings, AxisArray, AxisArray]
+):
+    def _process(self, message: AxisArray) -> AxisArray:
+        if self.settings.mode == "passthrough":
+            return message
 
-        if axis is None:
-            axis = msg_in.dims[-1]
-            axis_idx = -1
-        else:
-            axis_idx = msg_in.get_axis_idx(axis)
+        axis = self.settings.axis or message.dims[-1]
+        axis_idx = message.get_axis_idx(axis)
+
+        func = {"mean": np.mean, "median": np.median, "passthrough": zeros_for_noop}[
+            self.settings.mode
+        ]
 
-        ref_data = func(msg_in.data, axis=axis_idx, keepdims=True)
+        ref_data = func(message.data, axis=axis_idx, keepdims=True)
 
-        if not include_current:
+        if not self.settings.include_current:
             # Typical `CAR = x[0]/N + x[1]/N + ... x[i-1]/N + x[i]/N + x[i+1]/N + ... + x[N-1]/N`
             # and is the same for all i, so it is calculated only once in `ref_data`.
             # However, if we had excluded the current channel,
@@ -200,34 +205,35 @@ def common_rereference(
             # from the current channel (i.e., `x[i] / (N-1)`)
             #  i.e., `CAR[i] = (N / (N-1)) * common_CAR - x[i]/(N-1)`
             # We can use broadcasting subtraction instead of looping over channels.
-            N = msg_in.data.shape[axis_idx]
-            ref_data = (N / (N - 1)) * ref_data - msg_in.data / (N - 1)
-            # Side note: I profiled using affine_transform and it's about 30x slower than this implementation.
+            N = message.data.shape[axis_idx]
+            ref_data = (N / (N - 1)) * ref_data - message.data / (N - 1)
+            # Note: I profiled using AffineTransformTransformer; it's ~30x slower than this implementation.
 
-        msg_out = replace(msg_in, data=msg_in.data - ref_data)
+        return replace(message, data=message.data - ref_data)
 
 
-class CommonRereferenceSettings(ez.Settings):
-    """
-    Settings for :obj:`CommonRereference`
-    See :obj:`common_rereference` for argument details.
-    """
-
-    mode: str = "mean"
-    axis: str | None = None
-    include_current: bool = True
+class CommonRereference(
+    BaseTransformerUnit[
+        CommonRereferenceSettings, AxisArray, AxisArray, CommonRereferenceTransformer
+    ]
+):
+    SETTINGS = CommonRereferenceSettings
 
 
-class CommonRereference(GenAxisArray):
-    """
-    :obj:`Unit` for :obj:`common_rereference`.
+def common_rereference(
+    mode: str = "mean", axis: str | None = None, include_current: bool = True
+) -> CommonRereferenceTransformer:
     """
+    Perform common average referencing (CAR) on streaming data.
 
-    SETTINGS = CommonRereferenceSettings
+    Args:
+        mode: The statistical mode to apply -- either "mean" or "median"
+        axis: The name of hte axis to apply the transformation to.
+        include_current: Set False to exclude each channel from participating in the calculation of its reference.
 
-    def construct_generator(self):
-        self.STATE.gen = common_rereference(
-            mode=self.SETTINGS.mode,
-            axis=self.SETTINGS.axis,
-            include_current=self.SETTINGS.include_current,
-        )
+    Returns:
+        :obj:`CommonRereferenceTransformer`
+    """
+    return CommonRereferenceTransformer(
+        CommonRereferenceSettings(mode=mode, axis=axis, include_current=include_current)
+    )

ezmsg/sigproc/aggregate.py

@@ -3,7 +3,6 @@ import typing
 import numpy as np
 import numpy.typing as npt
 import ezmsg.core as ez
-from ezmsg.util.generator import consumer
 from ezmsg.util.messages.axisarray import (
     AxisArray,
     slice_along_axis,
@@ -12,7 +11,11 @@ from ezmsg.util.messages.axisarray import (
 )
 
 from .spectral import OptionsEnum
-from .base import GenAxisArray
+from .base import (
+    BaseStatefulTransformer,
+    BaseTransformerUnit,
+    processor_state,
+)
 
 
 class AggregationFunction(OptionsEnum):
@@ -54,130 +57,142 @@ AGGREGATORS = {
 }
 
 
-@consumer
-def ranged_aggregate(
-    axis: str | None = None,
-    bands: list[tuple[float, float]] | None = None,
-    operation: AggregationFunction = AggregationFunction.MEAN,
-):
+class RangedAggregateSettings(ez.Settings):
+    """
+    Settings for ``RangedAggregate``.
     """
-    Apply an aggregation operation over one or more bands.
 
-    Args:
-        axis: The name of the axis along which to apply the bands.
-        bands: [(band1_min, band1_max), (band2_min, band2_max), ...]
-            If not set then this acts as a passthrough node.
-        operation: :obj:`AggregationFunction` to apply to each band.
+    axis: str | None = None
+    """The name of the axis along which to apply the bands."""
 
-    Returns:
-        A primed generator object ready to yield an :obj:`AxisArray` for each .send(axis_array)
+    bands: list[tuple[float, float]] | None = None
     """
-    msg_out = AxisArray(np.array([]), dims=[""])
+    [(band1_min, band1_max), (band2_min, band2_max), ...]
+    If not set then this acts as a passthrough node.
+    """
+
+    operation: AggregationFunction = AggregationFunction.MEAN
+    """:obj:`AggregationFunction` to apply to each band."""
 
-    # State variables
+
+@processor_state
+class RangedAggregateState:
     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}
 
-    while True:
-        msg_in: AxisArray = yield msg_out
-        if bands is None:
-            msg_out = msg_in
+class RangedAggregateTransformer(
+    BaseStatefulTransformer[
+        RangedAggregateSettings, AxisArray, AxisArray, RangedAggregateState
+    ]
+):
+    def __call__(self, message: AxisArray) -> AxisArray:
+        # Override for shortcut passthrough mode.
+        if self.settings.bands is None:
+            return message
+        return super().__call__(message)
+
+    def _hash_message(self, message: AxisArray) -> int:
+        axis = self.settings.axis or message.dims[0]
+        target_axis = message.get_axis(axis)
+
+        hash_components = (message.key,)
+        if hasattr(target_axis, "data"):
+            hash_components += (len(target_axis.data),)
+        elif isinstance(target_axis, AxisArray.LinearAxis):
+            hash_components += (target_axis.gain, target_axis.offset)
+        return hash(hash_components)
+
+    def _reset_state(self, message: AxisArray) -> None:
+        axis = self.settings.axis or message.dims[0]
+        target_axis = message.get_axis(axis)
+        ax_idx = message.get_axis_idx(axis)
+
+        if hasattr(target_axis, "data"):
+            self._state.ax_vec = target_axis.data
         else:
-            axis = axis or msg_in.dims[0]
-            target_axis = msg_in.get_axis(axis)
+            self._state.ax_vec = target_axis.value(
+                np.arange(message.data.shape[ax_idx])
+            )
 
-            # Check if we need to reset state
-            b_reset = msg_in.key != check_inputs["key"]
+        ax_dat = []
+        slices = []
+        for start, stop in self.settings.bands:
+            inds = np.where(
+                np.logical_and(self._state.ax_vec >= start, self._state.ax_vec <= stop)
+            )[0]
+            slices.append(np.s_[inds[0] : inds[-1] + 1])
             if hasattr(target_axis, "data"):
-                b_reset = b_reset or len(target_axis.data) != check_inputs["len"]
-            elif isinstance(target_axis, AxisArray.LinearAxis):
-                b_reset = b_reset or target_axis.gain != check_inputs["gain"]
-                b_reset = b_reset or target_axis.offset != check_inputs["offset"]
-
-            if b_reset:
-                # Update check variables
-                check_inputs["key"] = msg_in.key
-                if hasattr(target_axis, "data"):
-                    check_inputs["len"] = len(target_axis.data)
+                if self._state.ax_vec.dtype.type is np.str_:
+                    sl_dat = f"{self._state.ax_vec[start]} - {self._state.ax_vec[stop]}"
                 else:
-                    check_inputs["gain"] = target_axis.gain
-                    check_inputs["offset"] = target_axis.offset
+                    ax_dat.append(np.mean(self._state.ax_vec[inds]))
+            else:
+                sl_dat = target_axis.value(np.mean(inds))
+            ax_dat.append(sl_dat)
+
+        self._state.slices = slices
+        self._state.out_axis = AxisArray.CoordinateAxis(
+            data=np.array(ax_dat),
+            dims=[axis],
+            unit=target_axis.unit,
+        )
 
-                # If the axis we are operating on has changed (e.g., "time" or "win" axis always changes),
-                #  or the key has changed, then recalculate slices.
+    def _process(self, message: AxisArray) -> AxisArray:
+        axis = self.settings.axis or message.dims[0]
+        ax_idx = message.get_axis_idx(axis)
+        agg_func = AGGREGATORS[self.settings.operation]
 
-                ax_idx = msg_in.get_axis_idx(axis)
+        out_data = [
+            agg_func(slice_along_axis(message.data, sl, axis=ax_idx), axis=ax_idx)
+            for sl in self._state.slices
+        ]
 
-                if hasattr(target_axis, "data"):
-                    ax_vec = target_axis.data
-                else:
-                    ax_vec = target_axis.value(np.arange(msg_in.data.shape[ax_idx]))
-
-                slices = []
-                ax_dat = []
-                for start, stop in bands:
-                    inds = np.where(np.logical_and(ax_vec >= start, ax_vec <= stop))[0]
-                    slices.append(np.s_[inds[0] : inds[-1] + 1])
-                    if hasattr(target_axis, "data"):
-                        if ax_vec.dtype.type is np.str_:
-                            sl_dat = f"{ax_vec[start]} - {ax_vec[stop]}"
-                        else:
-                            sl_dat = ax_dat.append(np.mean(ax_vec[inds]))
-                    else:
-                        sl_dat = target_axis.value(np.mean(inds))
-                    ax_dat.append(sl_dat)
-
-                out_axis = AxisArray.CoordinateAxis(
-                    data=np.array(ax_dat),
-                    dims=[axis],
-                    unit=target_axis.unit,
-                )
-
-            agg_func = AGGREGATORS[operation]
-            out_data = [
-                agg_func(slice_along_axis(msg_in.data, sl, axis=ax_idx), axis=ax_idx)
-                for sl in slices
-            ]
-
-            msg_out = replace(
-                msg_in,
-                data=np.stack(out_data, axis=ax_idx),
-                axes={**msg_in.axes, axis: out_axis},
-            )
-            if operation in [AggregationFunction.ARGMIN, AggregationFunction.ARGMAX]:
-                # Convert indices returned by argmin/argmax into the value along the axis.
-                out_data = []
-                for sl_ix, sl in enumerate(slices):
-                    offsets = np.take(msg_out.data, [sl_ix], axis=ax_idx)
-                    out_data.append(ax_vec[sl][offsets])
-                msg_out.data = np.concatenate(out_data, axis=ax_idx)
+        msg_out = replace(
+            message,
+            data=np.stack(out_data, axis=ax_idx),
+            axes={**message.axes, axis: self._state.out_axis},
+        )
 
+        if self.settings.operation in [
+            AggregationFunction.ARGMIN,
+            AggregationFunction.ARGMAX,
+        ]:
+            out_data = []
+            for sl_ix, sl in enumerate(self._state.slices):
+                offsets = np.take(msg_out.data, [sl_ix], axis=ax_idx)
+                out_data.append(self._state.ax_vec[sl][offsets])
+            msg_out.data = np.concatenate(out_data, axis=ax_idx)
 
-class RangedAggregateSettings(ez.Settings):
-    """
-    Settings for ``RangedAggregate``.
-    See :obj:`ranged_aggregate` for details.
-    """
+        return msg_out
 
-    axis: str | None = None
-    bands: list[tuple[float, float]] | None = None
-    operation: AggregationFunction = AggregationFunction.MEAN
+
+class RangedAggregate(
+    BaseTransformerUnit[
+        RangedAggregateSettings, AxisArray, AxisArray, RangedAggregateTransformer
+    ]
+):
+    SETTINGS = RangedAggregateSettings
 
 
-class RangedAggregate(GenAxisArray):
-    """
-    Unit for :obj:`ranged_aggregate`
+def ranged_aggregate(
+    axis: str | None = None,
+    bands: list[tuple[float, float]] | None = None,
+    operation: AggregationFunction = AggregationFunction.MEAN,
+) -> RangedAggregateTransformer:
     """
+    Apply an aggregation operation over one or more bands.
 
-    SETTINGS = RangedAggregateSettings
+    Args:
+        axis: The name of the axis along which to apply the bands.
+        bands: [(band1_min, band1_max), (band2_min, band2_max), ...]
+            If not set then this acts as a passthrough node.
+        operation: :obj:`AggregationFunction` to apply to each band.
 
-    def construct_generator(self):
-        self.STATE.gen = ranged_aggregate(
-            axis=self.SETTINGS.axis,
-            bands=self.SETTINGS.bands,
-            operation=self.SETTINGS.operation,
-        )
+    Returns:
+        :obj:`RangedAggregateTransformer`
+    """
+    return RangedAggregateTransformer(
+        RangedAggregateSettings(axis=axis, bands=bands, operation=operation)
+    )