ezmsg-baseproc 1.0.3__py3-none-any.whl → 1.1.0__py3-none-any.whl

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/__version__.py

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

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/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.3.dist-info → ezmsg_baseproc-1.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ezmsg-baseproc
-Version: 1.0.3
+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
 
@@ -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.3.dist-info → ezmsg_baseproc-1.1.0.dist-info}/RECORD

@@ -1,6 +1,8 @@
-ezmsg/baseproc/__init__.py,sha256=zmhdrRTnj3-ilBitu6zBniV04HJXc_fM_tKYiapFGko,3830
-ezmsg/baseproc/__version__.py,sha256=l8k828IdTfzXAlmx4oT8GsiIf2eeMAlFDALjoYk-jrU,704
+ezmsg/baseproc/__init__.py,sha256=OLpOqiGBjQSrLPjAtWEHdCS8Sm_2tJ55I7bpCtXntYY,4243
+ezmsg/baseproc/__version__.py,sha256=ePNVzJOkxR8FY5bezqKQ_fgBRbzH1G7QTaRDHvGQRAY,704
+ezmsg/baseproc/clock.py,sha256=jRJGxaWWBek503OcGRYsW4Qc7Lt4m-tVl1wn_v-qCIk,3254
 ezmsg/baseproc/composite.py,sha256=Lin4K_rmS2Tnxt-m8daP-PUyeeqL4id5JkVh-AUNrQw,14901
+ezmsg/baseproc/counter.py,sha256=3JR4AQ_wwZhdjKQdPlLhjhNVLHE5fj9ggwUPtJhWDS4,4601
 ezmsg/baseproc/processor.py,sha256=Ir9FtNuVG4yc-frwNxoYrlld99ff1mXwwGWaHxEJ6tY,8056
 ezmsg/baseproc/protocols.py,sha256=O3Qp0ymE9Ovlmh8t22v-lMmFzuWK0D93REAYMnJV3xA,5106
 ezmsg/baseproc/stateful.py,sha256=-jjAZIyJA5eiTECi1fSfazfqgv__RtyqPp1ZvLFFIDI,11424
@@ -10,7 +12,7 @@ ezmsg/baseproc/util/asio.py,sha256=0sF5oDc58DSLlcEgoUpNiqjjcbqnZhjSpQrXn6IdosM,4
 ezmsg/baseproc/util/message.py,sha256=l_b1b6bXX8N6VF9RbUELzsHs73cKkDURBdIr0lt3CY0,909
 ezmsg/baseproc/util/profile.py,sha256=MOQDsFsW6ddXT0uAOgytW3aK_AZW5ieA16Pz2hWuE2o,6189
 ezmsg/baseproc/util/typeresolution.py,sha256=WCHHYIrMMZ1CfwJWVlJPQgFyY2gnGRNFJVQynAsee7Y,3113
-ezmsg_baseproc-1.0.3.dist-info/METADATA,sha256=nOK4zkV08Nx1azdXd7js_OT0kQqomMq0Z2s8AoPSPd4,3320
-ezmsg_baseproc-1.0.3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-ezmsg_baseproc-1.0.3.dist-info/licenses/LICENSE,sha256=BDD8rfac1Ur7mp0_3izEdr6fHgSA3Or6U1Kb0ZAWsow,1066
-ezmsg_baseproc-1.0.3.dist-info/RECORD,,
+ezmsg_baseproc-1.1.0.dist-info/METADATA,sha256=zv5si0HBsR2t8lzzmwzeuLiik4SeanZvmV-JNWqOnKg,3415
+ezmsg_baseproc-1.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+ezmsg_baseproc-1.1.0.dist-info/licenses/LICENSE,sha256=BDD8rfac1Ur7mp0_3izEdr6fHgSA3Or6U1Kb0ZAWsow,1066
+ezmsg_baseproc-1.1.0.dist-info/RECORD,,