ezmsg-baseproc 1.0.2__tar.gz → 1.1.0__tar.gz

{ezmsg_baseproc-1.0.2 → ezmsg_baseproc-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ezmsg-baseproc
-Version: 1.0.2
+Version: 1.1.0
 Summary: Base processor classes and protocols for ezmsg signal processing pipelines
 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
@@ -12,7 +12,7 @@ Description-Content-Type: text/markdown
 
 # ezmsg-baseproc
 
-Base processor classes and protocols for building signal processing pipelines in [ezmsg](https://github.com/ezmsg-org/ezmsg).
+Base processor classes and protocols for building message-processing components in [ezmsg](https://github.com/ezmsg-org/ezmsg).
 
 ## Installation
 
@@ -20,30 +20,26 @@ Base processor classes and protocols for building signal processing pipelines in
 pip install ezmsg-baseproc
 ```
 
-## Overview
+Or install the latest development version:
 
-This package provides the foundational processor architecture for ezmsg signal processing:
+```bash
+pip install git+https://github.com/ezmsg-org/ezmsg-baseproc@dev
+```
 
-- **Protocols** - Type definitions for processors, transformers, consumers, and producers
-- **Base Classes** - Abstract base classes for building stateless and stateful processors
-- **Composite Processors** - Classes for chaining processors into pipelines
-- **Unit Wrappers** - ezmsg Unit base classes that wrap processors for graph integration
+## Overview
 
-## Module Structure
+``ezmsg-baseproc`` provides abstract base classes for creating message processors that can be used both standalone and within ezmsg pipelines. The package offers a consistent pattern for building:
 
-```
-ezmsg.baseproc/
-├── protocols.py      # Protocol definitions and type variables
-├── processor.py      # Base non-stateful processors
-├── stateful.py       # Stateful processor base classes
-├── composite.py      # CompositeProcessor and CompositeProducer
-├── units.py          # ezmsg Unit wrappers
-└── util/
-    ├── asio.py           # Async/sync utilities
-    ├── message.py        # SampleMessage definitions
-    ├── profile.py        # Profiling decorators
-    └── typeresolution.py # Type resolution helpers
-```
+* **Protocols** - Type definitions for processors, transformers, consumers, and producers
+* **Processors** - Transform input messages to output messages
+* **Producers** - Generate output messages without requiring input
+* **Consumers** - Accept input messages without producing output
+* **Transformers** - A specific type of processor with typed input/output
+* **Stateful variants** - Processors that maintain state across invocations
+* **Adaptive transformers** - Transformers that can be trained via ``partial_fit``
+* **Composite processors** - Chain multiple processors together efficiently
+
+All base classes support both synchronous and asynchronous operation, making them suitable for offline analysis and real-time streaming applications.
 
 ## Usage
 
@@ -52,7 +48,7 @@ ezmsg.baseproc/
 ```python
 from dataclasses import dataclass
 from ezmsg.baseproc import BaseTransformer
-from ezmsg.util.messages.axisarray import AxisArray
+from ezmsg.util.messages.axisarray import AxisArray, replace
 
 @dataclass
 class MySettings:
@@ -60,7 +56,7 @@ class MySettings:
 
 class MyTransformer(BaseTransformer[MySettings, AxisArray, AxisArray]):
     def _process(self, message: AxisArray) -> AxisArray:
-        return message.replace(data=message.data * self.settings.scale)
+        return replace(message, data=message.data * self.settings.scale)
 ```
 
 ### Creating a Stateful Transformer
@@ -100,6 +96,7 @@ We use [`uv`](https://docs.astral.sh/uv/getting-started/installation/) for devel
 2. Clone and cd into the repository
 3. Run `uv sync` to create a `.venv` and install dependencies
 4. Run `uv run pytest tests` to run tests
+5. (Optional) Install pre-commit hooks: `uv run pre-commit install`
 
 ## License
 

{ezmsg_baseproc-1.0.2 → ezmsg_baseproc-1.1.0}/README.md

@@ -1,6 +1,6 @@
 # ezmsg-baseproc
 
-Base processor classes and protocols for building signal processing pipelines in [ezmsg](https://github.com/ezmsg-org/ezmsg).
+Base processor classes and protocols for building message-processing components in [ezmsg](https://github.com/ezmsg-org/ezmsg).
 
 ## Installation
 
@@ -8,30 +8,26 @@ Base processor classes and protocols for building signal processing pipelines in
 pip install ezmsg-baseproc
 ```
 
-## Overview
+Or install the latest development version:
 
-This package provides the foundational processor architecture for ezmsg signal processing:
+```bash
+pip install git+https://github.com/ezmsg-org/ezmsg-baseproc@dev
+```
 
-- **Protocols** - Type definitions for processors, transformers, consumers, and producers
-- **Base Classes** - Abstract base classes for building stateless and stateful processors
-- **Composite Processors** - Classes for chaining processors into pipelines
-- **Unit Wrappers** - ezmsg Unit base classes that wrap processors for graph integration
+## Overview
 
-## Module Structure
+``ezmsg-baseproc`` provides abstract base classes for creating message processors that can be used both standalone and within ezmsg pipelines. The package offers a consistent pattern for building:
 
-```
-ezmsg.baseproc/
-├── protocols.py      # Protocol definitions and type variables
-├── processor.py      # Base non-stateful processors
-├── stateful.py       # Stateful processor base classes
-├── composite.py      # CompositeProcessor and CompositeProducer
-├── units.py          # ezmsg Unit wrappers
-└── util/
-    ├── asio.py           # Async/sync utilities
-    ├── message.py        # SampleMessage definitions
-    ├── profile.py        # Profiling decorators
-    └── typeresolution.py # Type resolution helpers
-```
+* **Protocols** - Type definitions for processors, transformers, consumers, and producers
+* **Processors** - Transform input messages to output messages
+* **Producers** - Generate output messages without requiring input
+* **Consumers** - Accept input messages without producing output
+* **Transformers** - A specific type of processor with typed input/output
+* **Stateful variants** - Processors that maintain state across invocations
+* **Adaptive transformers** - Transformers that can be trained via ``partial_fit``
+* **Composite processors** - Chain multiple processors together efficiently
+
+All base classes support both synchronous and asynchronous operation, making them suitable for offline analysis and real-time streaming applications.
 
 ## Usage
 
@@ -40,7 +36,7 @@ ezmsg.baseproc/
 ```python
 from dataclasses import dataclass
 from ezmsg.baseproc import BaseTransformer
-from ezmsg.util.messages.axisarray import AxisArray
+from ezmsg.util.messages.axisarray import AxisArray, replace
 
 @dataclass
 class MySettings:
@@ -48,7 +44,7 @@ class MySettings:
 
 class MyTransformer(BaseTransformer[MySettings, AxisArray, AxisArray]):
     def _process(self, message: AxisArray) -> AxisArray:
-        return message.replace(data=message.data * self.settings.scale)
+        return replace(message, data=message.data * self.settings.scale)
 ```
 
 ### Creating a Stateful Transformer
@@ -88,6 +84,7 @@ We use [`uv`](https://docs.astral.sh/uv/getting-started/installation/) for devel
 2. Clone and cd into the repository
 3. Run `uv sync` to create a `.venv` and install dependencies
 4. Run `uv run pytest tests` to run tests
+5. (Optional) Install pre-commit hooks: `uv run pre-commit install`
 
 ## License
 

ezmsg_baseproc-1.1.0/docs/source/index.md

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

{ezmsg_baseproc-1.0.2 → ezmsg_baseproc-1.1.0}/src/ezmsg/baseproc/__init__.py

@@ -7,6 +7,14 @@ signal processing pipelines in ezmsg.
 
 from .__version__ import __version__ as __version__
 
+# Clock and Counter
+from .clock import (
+    Clock,
+    ClockProducer,
+    ClockSettings,
+    ClockState,
+)
+
 # Composite processor classes
 from .composite import (
     CompositeProcessor,
@@ -14,6 +22,12 @@ from .composite import (
     CompositeStateful,
     _get_processor_message_type,
 )
+from .counter import (
+    Counter,
+    CounterSettings,
+    CounterTransformer,
+    CounterTransformerState,
+)
 
 # Base processor classes (non-stateful)
 from .processor import (
@@ -152,4 +166,13 @@ __all__ = [
     # Type utilities
     "check_message_type_compatibility",
     "resolve_typevar",
+    # Clock and Counter
+    "Clock",
+    "ClockProducer",
+    "ClockSettings",
+    "ClockState",
+    "Counter",
+    "CounterSettings",
+    "CounterTransformer",
+    "CounterTransformerState",
 ]

{ezmsg_baseproc-1.0.2 → ezmsg_baseproc-1.1.0}/src/ezmsg/baseproc/__version__.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '1.0.2'
-__version_tuple__ = version_tuple = (1, 0, 2)
+__version__ = version = '1.1.0'
+__version_tuple__ = version_tuple = (1, 1, 0)
 
 __commit_id__ = commit_id = None

ezmsg_baseproc-1.1.0/src/ezmsg/baseproc/clock.py

@@ -0,0 +1,109 @@
+"""Clock generator for timing control."""
+
+import asyncio
+import math
+import time
+from dataclasses import field
+
+import ezmsg.core as ez
+from ezmsg.util.messages.axisarray import AxisArray
+
+from .protocols import processor_state
+from .stateful import BaseStatefulProducer
+from .units import BaseProducerUnit
+
+
+class ClockSettings(ez.Settings):
+    """Settings for :obj:`ClockProducer`."""
+
+    dispatch_rate: float = math.inf
+    """
+    Dispatch rate in Hz.
+    - Finite value (e.g., 100.0): Dispatch 100 times per second
+    - math.inf: Dispatch as fast as possible (no sleep)
+    """
+
+
+@processor_state
+class ClockState:
+    """State for :obj:`ClockProducer`."""
+
+    t_0: float = field(default_factory=time.monotonic)
+    """Start time (monotonic)."""
+
+    n_dispatch: int = 0
+    """Number of dispatches since reset."""
+
+
+class ClockProducer(BaseStatefulProducer[ClockSettings, AxisArray.LinearAxis, ClockState]):
+    """
+    Produces clock ticks at a specified rate.
+
+    Each tick outputs a :obj:`AxisArray.LinearAxis` containing:
+    - ``gain``: 1/dispatch_rate (seconds per tick), or 0.0 if dispatch_rate is infinite
+    - ``offset``: Wall clock timestamp (time.monotonic)
+
+    This output type allows downstream components (like Counter) to know both
+    the timing of the tick and the nominal dispatch rate.
+    """
+
+    def _reset_state(self) -> None:
+        """Reset internal state."""
+        self._state.t_0 = time.monotonic()
+        self._state.n_dispatch = 0
+
+    def _make_output(self, timestamp: float) -> AxisArray.LinearAxis:
+        """Create LinearAxis output with gain and offset."""
+        if math.isinf(self.settings.dispatch_rate):
+            gain = 0.0
+        else:
+            gain = 1.0 / self.settings.dispatch_rate
+        return AxisArray.LinearAxis(gain=gain, offset=timestamp)
+
+    def __call__(self) -> AxisArray.LinearAxis:
+        """Synchronous clock production."""
+        if self._hash == -1:
+            self._reset_state()
+            self._hash = 0
+
+        now = time.monotonic()
+        if math.isfinite(self.settings.dispatch_rate):
+            target_time = self.state.t_0 + (self.state.n_dispatch + 1) / self.settings.dispatch_rate
+            if target_time > now:
+                time.sleep(target_time - now)
+        else:
+            target_time = now
+
+        self.state.n_dispatch += 1
+        return self._make_output(target_time)
+
+    async def _produce(self) -> AxisArray.LinearAxis:
+        """Generate next clock tick."""
+        now = time.monotonic()
+        if math.isfinite(self.settings.dispatch_rate):
+            target_time = self.state.t_0 + (self.state.n_dispatch + 1) / self.settings.dispatch_rate
+            if target_time > now:
+                await asyncio.sleep(target_time - now)
+        else:
+            target_time = now
+
+        self.state.n_dispatch += 1
+        return self._make_output(target_time)
+
+
+class Clock(
+    BaseProducerUnit[
+        ClockSettings,
+        AxisArray.LinearAxis,
+        ClockProducer,
+    ]
+):
+    """
+    Clock unit that produces ticks at a specified rate.
+
+    Output is a :obj:`AxisArray.LinearAxis` with:
+    - ``gain``: 1/dispatch_rate (seconds per tick)
+    - ``offset``: Wall clock timestamp
+    """
+
+    SETTINGS = ClockSettings

ezmsg_baseproc-1.1.0/src/ezmsg/baseproc/counter.py

@@ -0,0 +1,128 @@
+"""Counter generator for sample counting and timing."""
+
+import ezmsg.core as ez
+import numpy as np
+from ezmsg.util.messages.axisarray import AxisArray, replace
+
+from .protocols import processor_state
+from .stateful import BaseStatefulTransformer
+from .units import BaseTransformerUnit
+
+
+class CounterSettings(ez.Settings):
+    """Settings for :obj:`Counter` and :obj:`CounterTransformer`."""
+
+    fs: float
+    """Sampling rate in Hz."""
+
+    n_time: int | None = None
+    """
+    Samples per block.
+    - If specified: fixed chunk size (clock gain is ignored)
+    - If None: derived from clock gain (fs * clock.gain), with fractional sample tracking
+    """
+
+    mod: int | None = None
+    """If set, counter values rollover at this modulus."""
+
+
+@processor_state
+class CounterTransformerState:
+    """State for :obj:`CounterTransformer`."""
+
+    counter: int = 0
+    """Current counter value (next sample index)."""
+
+    fractional_samples: float = 0.0
+    """Accumulated fractional samples for variable chunk mode."""
+
+    template: AxisArray | None = None
+
+
+class CounterTransformer(
+    BaseStatefulTransformer[CounterSettings, AxisArray.LinearAxis, AxisArray, CounterTransformerState]
+):
+    """
+    Transforms clock ticks (LinearAxis) into AxisArray counter values.
+
+    Each clock tick produces a block of counter values. The block size is either
+    fixed (n_time setting) or derived from the clock's gain (fs * gain).
+    """
+
+    def _reset_state(self, message: AxisArray.LinearAxis) -> None:
+        """Reset state - counter transformer state is simple, just reset values."""
+        self._state.counter = 0
+        self._state.fractional_samples = 0.0
+        self._state.template = AxisArray(
+            data=np.array([], dtype=int),
+            dims=["time"],
+            axes={
+                "time": AxisArray.TimeAxis(fs=self.settings.fs, offset=message.offset),
+            },
+            key="counter",
+        )
+
+    def _hash_message(self, message: AxisArray.LinearAxis) -> int:
+        # Return constant hash - counter state should never reset based on message content.
+        # The counter maintains continuity regardless of clock rate changes.
+        return 0
+
+    def _process(self, clock_tick: AxisArray.LinearAxis) -> AxisArray | None:
+        """Transform a clock tick into counter AxisArray."""
+        # Determine number of samples for this block
+        if self.settings.n_time is not None:
+            # Fixed chunk size mode
+            n_samples = self.settings.n_time
+            # Use wall clock or synthetic offset based on clock gain
+            if clock_tick.gain == 0.0:
+                # AFAP mode - synthetic offset
+                offset = self.state.counter / self.settings.fs
+            else:
+                # Use clock's timestamp
+                offset = clock_tick.offset
+        else:
+            # Variable chunk size mode - derive from clock gain
+            if clock_tick.gain == 0.0:
+                # AFAP with no fixed n_time - this is an error
+                raise ValueError("Cannot use clock with gain=0 (AFAP) without specifying n_time")
+
+            # Calculate samples including fractional accumulation
+            # Add small epsilon to avoid floating point truncation errors (e.g., 0.9999999 -> 0)
+            samples_float = self.settings.fs * clock_tick.gain + self.state.fractional_samples
+            n_samples = int(samples_float + 1e-9)
+            self.state.fractional_samples = samples_float - n_samples
+
+            if n_samples == 0:
+                # Not enough samples accumulated yet
+                # TODO: Return empty array. What should offset be?
+                return None
+
+            # Use clock's timestamp for offset
+            offset = clock_tick.offset
+
+        # Generate counter data
+        block_samp = np.arange(self.state.counter, self.state.counter + n_samples)
+        if self.settings.mod is not None:
+            block_samp = block_samp % self.settings.mod
+
+        # Create output AxisArray
+        result = replace(
+            self._state.template,
+            data=block_samp,
+            axes={"time": replace(self._state.template.axes["time"], offset=offset)},
+        )
+
+        # Update state
+        self.state.counter += n_samples
+
+        return result
+
+
+class Counter(BaseTransformerUnit[CounterSettings, AxisArray.LinearAxis, AxisArray, CounterTransformer]):
+    """
+    Transforms clock ticks into monotonically increasing counter values as AxisArray.
+
+    Receives timing from INPUT_SIGNAL (LinearAxis from Clock) and outputs AxisArray.
+    """
+
+    SETTINGS = CounterSettings

{ezmsg_baseproc-1.0.2 → ezmsg_baseproc-1.1.0}/src/ezmsg/baseproc/protocols.py

@@ -4,6 +4,8 @@ import functools
 import typing
 from dataclasses import dataclass
 
+import ezmsg.core as ez
+
 from .util.message import SampleMessage
 
 # --- Processor state decorator ---
@@ -12,7 +14,7 @@ processor_state = functools.partial(dataclass, unsafe_hash=True, frozen=False, i
 # --- Type variables for protocols and processors ---
 MessageInType = typing.TypeVar("MessageInType")
 MessageOutType = typing.TypeVar("MessageOutType")
-SettingsType = typing.TypeVar("SettingsType")
+SettingsType = typing.TypeVar("SettingsType", bound=ez.Settings)
 StateType = typing.TypeVar("StateType")
 
 

ezmsg_baseproc-1.1.0/tests/test_clock.py

@@ -0,0 +1,83 @@
+"""Unit tests for ezmsg.baseproc.clock module."""
+
+import math
+import time
+
+import numpy as np
+import pytest
+from ezmsg.util.messages.axisarray import AxisArray
+
+from ezmsg.baseproc import ClockProducer, ClockSettings
+
+
+@pytest.mark.parametrize("dispatch_rate", [math.inf, 1.0, 2.0, 5.0, 10.0, 20.0])
+def test_clock_producer_sync(dispatch_rate: float):
+    """Test synchronous ClockProducer via __call__."""
+    run_time = 1.0
+    n_target = 100 if math.isinf(dispatch_rate) else int(np.ceil(dispatch_rate * run_time))
+
+    producer = ClockProducer(ClockSettings(dispatch_rate=dispatch_rate))
+
+    results = []
+    t_start = time.monotonic()
+    while len(results) < n_target:
+        results.append(producer())
+    t_elapsed = time.monotonic() - t_start
+
+    # All results should be LinearAxis
+    assert all(isinstance(r, AxisArray.LinearAxis) for r in results)
+
+    # Check gain values
+    if math.isinf(dispatch_rate):
+        assert all(r.gain == 0.0 for r in results)
+    else:
+        expected_gain = 1.0 / dispatch_rate
+        assert all(abs(r.gain - expected_gain) < 1e-10 for r in results)
+
+    # Offsets (timestamps) should be monotonically increasing
+    offsets = [r.offset for r in results]
+    assert all(offsets[i] <= offsets[i + 1] for i in range(len(offsets) - 1))
+
+    # Check timing
+    if math.isfinite(dispatch_rate):
+        assert (run_time - 1 / dispatch_rate) < t_elapsed < (run_time + 0.2)
+    else:
+        # 100 usec per iteration is pretty generous for AFAP
+        assert t_elapsed < (n_target * 1e-4)
+
+
+@pytest.mark.parametrize("dispatch_rate", [math.inf, 2.0, 20.0])
+@pytest.mark.asyncio
+async def test_clock_producer_async(dispatch_rate: float):
+    """Test asynchronous ClockProducer via __acall__."""
+    run_time = 1.0
+    n_target = 100 if math.isinf(dispatch_rate) else int(np.ceil(dispatch_rate * run_time))
+
+    producer = ClockProducer(ClockSettings(dispatch_rate=dispatch_rate))
+
+    results = []
+    t_start = time.monotonic()
+    while len(results) < n_target:
+        results.append(await producer.__acall__())
+    t_elapsed = time.monotonic() - t_start
+
+    # All results should be LinearAxis
+    assert all(isinstance(r, AxisArray.LinearAxis) for r in results)
+
+    # Check gain values
+    if math.isinf(dispatch_rate):
+        assert all(r.gain == 0.0 for r in results)
+    else:
+        expected_gain = 1.0 / dispatch_rate
+        assert all(abs(r.gain - expected_gain) < 1e-10 for r in results)
+
+    # Offsets (timestamps) should be monotonically increasing
+    offsets = [r.offset for r in results]
+    assert all(offsets[i] <= offsets[i + 1] for i in range(len(offsets) - 1))
+
+    # Check timing
+    if math.isfinite(dispatch_rate):
+        assert (run_time - 1.1 / dispatch_rate) < t_elapsed < (run_time + 0.1)
+    else:
+        # 100 usec per iteration is pretty generous for AFAP
+        assert t_elapsed < (n_target * 1e-4)

ezmsg_baseproc-1.1.0/tests/test_counter.py

@@ -0,0 +1,180 @@
+"""Unit tests for ezmsg.baseproc.counter module."""
+
+import numpy as np
+import pytest
+from ezmsg.util.messages.axisarray import AxisArray
+
+from ezmsg.baseproc import (
+    CounterSettings,
+    CounterTransformer,
+)
+
+
+class TestCounterTransformer:
+    """Tests for CounterTransformer."""
+
+    def test_fixed_n_time_mode(self):
+        """Test transformer with fixed n_time."""
+        transformer = CounterTransformer(CounterSettings(fs=1000.0, n_time=100, mod=None))
+
+        # Create clock tick with gain = 0.1 (10 Hz dispatch rate)
+        clock_tick = AxisArray.LinearAxis(gain=0.1, offset=1.0)
+
+        result = transformer(clock_tick)
+
+        assert isinstance(result, AxisArray)
+        assert result.data.shape == (100,)
+        assert result.dims == ["time"]
+        # TimeAxis has gain = 1/fs
+        assert result.axes["time"].gain == 1 / 1000.0
+        assert result.axes["time"].offset == 1.0  # Uses clock's offset
+        np.testing.assert_array_equal(result.data, np.arange(100))
+
+    def test_fixed_n_time_with_afap_clock(self):
+        """Test transformer with fixed n_time and AFAP clock (gain=0)."""
+        transformer = CounterTransformer(CounterSettings(fs=1000.0, n_time=50, mod=None))
+
+        # AFAP clock has gain=0
+        clock_tick = AxisArray.LinearAxis(gain=0.0, offset=123.456)
+
+        result = transformer(clock_tick)
+
+        assert isinstance(result, AxisArray)
+        assert result.data.shape == (50,)
+        # With AFAP clock, offset is synthetic (counter / fs)
+        assert result.axes["time"].offset == 0.0  # First block starts at 0
+
+        # Second call
+        result2 = transformer(clock_tick)
+        assert result2.axes["time"].offset == 50 / 1000.0  # 0.05 seconds
+
+    def test_variable_n_time_mode(self):
+        """Test transformer with n_time derived from clock gain."""
+        transformer = CounterTransformer(CounterSettings(fs=1000.0, n_time=None, mod=None))
+
+        # Clock at 10 Hz with fs=1000 -> 100 samples per tick
+        clock_tick = AxisArray.LinearAxis(gain=0.1, offset=5.0)
+
+        result = transformer(clock_tick)
+
+        assert isinstance(result, AxisArray)
+        assert result.data.shape == (100,)  # 1000 * 0.1 = 100
+        assert result.axes["time"].offset == 5.0
+
+    def test_variable_n_time_fractional_accumulation(self):
+        """Test fractional sample accumulation in variable mode."""
+        transformer = CounterTransformer(CounterSettings(fs=1000.0, n_time=None, mod=None))
+
+        # Clock at 3 Hz with fs=1000 -> 333.33... samples per tick
+        # Over 3 ticks we should get exactly 1000 samples (333 + 333 + 334)
+        clock_tick = AxisArray.LinearAxis(gain=1.0 / 3.0, offset=0.0)
+
+        # First tick: 333.33 -> 333 samples, 0.33 fractional
+        result1 = transformer(clock_tick)
+        assert result1.data.shape == (333,)
+
+        # Second tick: 333.33 + 0.33 = 666.66 -> 333 samples, 0.66 fractional
+        result2 = transformer(clock_tick)
+        assert result2.data.shape == (333,)
+
+        # Third tick: 333.33 + 0.66 = 999.99... ≈ 1000 -> 334 samples
+        result3 = transformer(clock_tick)
+        assert result3.data.shape == (334,)
+
+        # Verify total is exactly 1000 (3 ticks * 333.33... = 1000)
+        total_samples = sum(r.data.shape[0] for r in [result1, result2, result3])
+        assert total_samples == 1000
+
+        # Fourth tick starts fresh cycle: 333 samples
+        result4 = transformer(clock_tick)
+        assert result4.data.shape == (333,)
+
+    def test_variable_n_time_returns_none_when_no_samples(self):
+        """Test that transformer returns None when not enough samples accumulated."""
+        transformer = CounterTransformer(
+            CounterSettings(fs=10.0, n_time=None, mod=None)  # Low fs
+        )
+
+        # Clock at 100 Hz with fs=10 -> 0.1 samples per tick
+        clock_tick = AxisArray.LinearAxis(gain=0.01, offset=0.0)
+
+        # Need 10 ticks to accumulate 1 sample
+        for _ in range(9):
+            result = transformer(clock_tick)
+            assert result is None
+
+        # 10th tick should produce 1 sample
+        result = transformer(clock_tick)
+        assert result is not None
+        assert result.data.shape == (1,)
+
+    def test_variable_n_time_afap_raises_error(self):
+        """Test that variable mode with AFAP clock raises error."""
+        transformer = CounterTransformer(CounterSettings(fs=1000.0, n_time=None, mod=None))
+
+        clock_tick = AxisArray.LinearAxis(gain=0.0, offset=0.0)
+
+        with pytest.raises(ValueError, match="Cannot use clock with gain=0"):
+            transformer(clock_tick)
+
+    def test_mod_rollover(self):
+        """Test counter rollover with mod."""
+        transformer = CounterTransformer(CounterSettings(fs=100.0, n_time=10, mod=8))
+
+        clock_tick = AxisArray.LinearAxis(gain=0.1, offset=0.0)
+
+        result = transformer(clock_tick)
+        np.testing.assert_array_equal(result.data, [0, 1, 2, 3, 4, 5, 6, 7, 0, 1])
+
+    def test_continuity_across_calls(self):
+        """Test counter continuity across multiple calls."""
+        transformer = CounterTransformer(CounterSettings(fs=100.0, n_time=5, mod=None))
+
+        clock_tick = AxisArray.LinearAxis(gain=0.05, offset=0.0)
+
+        results = [transformer(clock_tick) for _ in range(4)]
+        agg = AxisArray.concatenate(*results, dim="time")
+        np.testing.assert_array_equal(agg.data, np.arange(20))
+
+
+class TestCounterTransformerExternalClock:
+    """Tests for external clock mode patterns."""
+
+    def test_external_clock_with_fixed_n_time(self):
+        """Test external clock mode with fixed n_time."""
+        transformer = CounterTransformer(CounterSettings(fs=1000.0, n_time=100, mod=None))
+
+        # Simulate external clock ticks
+        timestamps = [1.0, 1.1, 1.2, 1.3, 1.4]
+        clock_ticks = [AxisArray.LinearAxis(gain=0.1, offset=ts) for ts in timestamps]
+
+        results = [transformer(tick) for tick in clock_ticks]
+
+        # Verify offsets match clock timestamps
+        offsets = [r.axes["time"].offset for r in results]
+        np.testing.assert_array_equal(offsets, timestamps)
+
+        # Verify data continuity
+        agg = AxisArray.concatenate(*results, dim="time")
+        np.testing.assert_array_equal(agg.data, np.arange(500))
+
+    def test_external_clock_variable_chunk_sizes(self):
+        """Test external clock mode with variable chunk sizes."""
+        transformer = CounterTransformer(CounterSettings(fs=1000.0, n_time=None, mod=None))
+
+        # Clock with varying rates
+        clock_ticks = [
+            AxisArray.LinearAxis(gain=0.1, offset=0.0),  # 100 samples
+            AxisArray.LinearAxis(gain=0.05, offset=0.1),  # 50 samples
+            AxisArray.LinearAxis(gain=0.2, offset=0.15),  # 200 samples
+        ]
+
+        results = [transformer(tick) for tick in clock_ticks]
+
+        assert results[0].data.shape == (100,)
+        assert results[1].data.shape == (50,)
+        assert results[2].data.shape == (200,)
+
+        # Verify data continuity
+        agg = AxisArray.concatenate(*results, dim="time")
+        np.testing.assert_array_equal(agg.data, np.arange(350))

ezmsg_baseproc-1.0.2/docs/source/index.rst

@@ -1,87 +0,0 @@
-ezmsg.baseproc
-==============
-
-Base processor classes and utilities for building message-processing components in the `ezmsg <https://www.ezmsg.org>`_ framework.
-
-Overview
---------
-
-``ezmsg-baseproc`` provides abstract base classes for creating message processors that can be used both standalone and within ezmsg pipelines. The package offers a consistent pattern for building:
-
-* **Processors** - Transform input messages to output messages
-* **Producers** - Generate output messages without requiring input
-* **Consumers** - Accept input messages without producing output
-* **Transformers** - A specific type of processor with typed input/output
-* **Stateful variants** - Processors that maintain state across invocations
-* **Adaptive transformers** - Transformers that can be trained via ``partial_fit``
-* **Composite processors** - Chain multiple processors together efficiently
-
-All base classes support both synchronous and asynchronous operation, making them suitable for offline analysis and real-time streaming applications.
-
-Installation
-------------
-
-Install from PyPI:
-
-.. code-block:: bash
-
-   pip install ezmsg-baseproc
-
-Or install the latest development version:
-
-.. code-block:: bash
-
-   pip install git+https://github.com/ezmsg-org/ezmsg-baseproc@main
-
-Dependencies
-^^^^^^^^^^^^
-
-Core dependencies:
-
-* ``ezmsg`` - Core messaging framework
-* ``typing-extensions`` - Extended typing support
-
-Quick Start
------------
-
-For general ezmsg tutorials and guides, visit `ezmsg.org <https://www.ezmsg.org>`_.
-
-Here's a simple example of creating a custom transformer:
-
-.. code-block:: python
-
-   import ezmsg.core as ez
-   from ezmsg.baseproc import BaseTransformer, BaseTransformerUnit
-
-   class MySettings(ez.Settings):
-       scale: float = 1.0
-
-   class MyTransformer(BaseTransformer[MySettings, float, float]):
-       def _process(self, message: float) -> float:
-           return message * self.settings.scale
-
-   # Use standalone
-   transformer = MyTransformer(scale=2.0)
-   result = transformer(5.0)  # Returns 10.0
-
-   # Or wrap in an ezmsg Unit
-   class MyUnit(BaseTransformerUnit[MySettings, float, float, MyTransformer]):
-       SETTINGS = MySettings
-
-Documentation
--------------
-
-.. toctree::
-   :maxdepth: 2
-   :caption: Contents:
-
-   guides/ProcessorsBase
-   guides/how-tos/processors/content-processors
-   api/index
-
-
-Indices and tables
-------------------
-
-* :ref:`genindex`
-* :ref:`modindex`

ezmsg_baseproc-1.0.2/examples/example.py

@@ -1,44 +0,0 @@
-"""Example usage of ezmsg-baseproc package."""
-
-import asyncio
-
-import ezmsg.core as ez
-
-# Import your units from the package
-# from ezmsg.baseproc import MyUnit
-
-
-class ExampleSettings(ez.Settings):
-    """Settings for ExampleUnit."""
-
-    message: str = "Hello from ezmsg-baseproc!"
-
-
-class ExampleUnit(ez.Unit):
-    """Example ezmsg Unit demonstrating basic patterns."""
-
-    SETTINGS = ExampleSettings
-
-    INPUT = ez.InputStream(str)
-    OUTPUT = ez.OutputStream(str)
-
-    @ez.subscriber(INPUT)
-    @ez.publisher(OUTPUT)
-    async def on_message(self, message: str) -> ez.AsyncGenerator:
-        """Process incoming messages."""
-        result = f"{self.SETTINGS.message} Received: {message}"
-        yield self.OUTPUT, result
-
-
-async def main():
-    """Run the example."""
-    print("ezmsg-baseproc loaded successfully!")
-    print(f"Version: {__import__('ezmsg.baseproc').__version__}")
-
-    # Example: Create and run a simple system
-    # system = ExampleSystem()
-    # await ez.run(SYSTEM=system)
-
-
-if __name__ == "__main__":
-    asyncio.run(main())