Merge pull request #119 from ezmsg-org/dev

Add coordinate spaces conversions and reorganize docs

Author: cboulay

README.md

@@ -1,55 +1,42 @@
-# ezmsg.sigproc
+# ezmsg-sigproc
 
-## Overview
+Signal processing primitives for the [ezmsg](https://www.ezmsg.org) message-passing framework.
 
-ezmsg-sigproc offers timeseries signal‑processing primitives built atop the ezmsg message‑passing framework. Core dependencies include ezmsg, numpy, scipy, pywavelets, and sparse; the project itself is managed through hatchling and uses VCS hooks to populate __version__.py.
+## Features
 
-## Installation
-
-Install the latest release from pypi with: `pip install ezmsg-sigproc` (or `uv add ...` or `poetry add ...`).
-
-You can install pre-release versions directly from GitHub:
+* **Filtering** - Chebyshev, comb filters, and more
+* **Spectral analysis** - Spectrogram, spectrum, and wavelet transforms
+* **Resampling** - Downsample, decimate, and resample operations
+* **Windowing** - Sliding windows and buffering utilities
+* **Math operations** - Arithmetic, log, abs, difference, and more
+* **Signal generation** - Synthetic signal generators
 
-* Using `pip`: `pip install git+https://github.com/ezmsg-org/ezmsg-sigproc.git@dev`
-* Using `uv`: `uv add git+https://github.com/ezmsg-org/ezmsg-sigproc --branch dev`
-* Using `poetry`: `poetry add "git+https://github.com/ezmsg-org/ezmsg-sigproc.git@dev"`
+All modules use `AxisArray` as the primary data structure for passing signals between components.
 
-> See the [Development](#development) section below for installing with the intention of developing.
-
-## Source layout & key modules
-* All source resides under src/ezmsg/sigproc, which contains a suite of processors (for example, filter.py, spectrogram.py, spectrum.py, sampler.py) and math and util subpackages.
-* The framework’s backbone is base.py, defining standard protocols—Processor, Producer, Consumer, and Transformer—that enable both stateless and stateful processing chains.
-* Filtering is implemented in filter.py, providing settings dataclasses and a stateful transformer that applies supplied coefficients to incoming data.
-* Spectral analysis uses a composite spectrogram transformer chaining windowing, spectrum computation, and axis adjustments.
+## Installation
 
-## Operating styles: Standalone processors vs. ezmsg pipelines
-While each processor is designed to be assembled into an ezmsg pipeline, the components are also well‑suited for offline, ad‑hoc analysis. You can instantiate processors directly in scripts or notebooks for quick prototyping or to validate results from other code. The companion Unit wrappers, however, are meant for assembling processors into a full ezmsg pipeline.
+Install from PyPI:
 
-A fully defined ezmsg pipeline shines in online streaming scenarios where message routing, scheduling, and latency handling are crucial. Nevertheless, you can run the same pipeline offline—say, within a Jupyter notebook—if your analysis benefits from ezmsg’s structured execution model. Deciding between a standalone processor and a full pipeline comes down to the trade‑off between simplicity and the operational overhead of the pipeline:
+```bash
+pip install ezmsg-sigproc
+```
 
-* Standalone processors: Low overhead, ideal for one‑off or exploratory offline tasks.
-* Pipeline + Unit wrappers: Additional setup cost but bring concurrency, standardized interfaces, and automatic message flow—useful when your offline experiment mirrors a live system or when you require fine‑grained pipeline behavior.
+Or install from GitHub for the latest development version:
 
-## Documentation & tests
-* `docs/ProcessorsBase.md` details the processor hierarchy and generic type patterns, providing a solid foundation for custom components.
-* Unit tests (e.g., `tests/unit/test_sampler.py`) offer concrete examples of usage, showcasing sampler generation, windowing, and message handling.
+```bash
+pip install git+https://github.com/ezmsg-org/ezmsg-sigproc.git@dev
+```
 
-## Where to learn next
-* Study docs/ProcessorsBase.md to master the processor architecture.
-* Explore unit tests for hands‑on examples of composing processors and Units.
-* Review the ezmsg framework in pyproject.toml to understand the surrounding ecosystem.
-* Experiment with the code—try running processors standalone and then integrate them into a small pipeline to observe the trade‑offs firsthand.
+## Documentation
 
-This approach equips newcomers to choose the right level of abstraction—raw processor, Unit wrapper, or full pipeline—based on the demands of their analysis or streaming application.
+Full documentation is available at [ezmsg.org](https://www.ezmsg.org).
 
 ## Development
 
-We use [`uv`](https://docs.astral.sh/uv/getting-started/installation/) for development. It is not strictly required, but if you intend to contribute to ezmsg-sigproc then using `uv` will lead to the smoothest collaboration.
+We use [`uv`](https://docs.astral.sh/uv/) for development.
 
-1. Install [`uv`](https://docs.astral.sh/uv/getting-started/installation/) if not already installed.
-2. Fork ezmsg-sigproc and clone your fork to your local computer.
-3. Open a terminal and `cd` to the cloned folder.
-4. `uv sync` to create a .venv and install dependencies.
-5. `uv run pre-commit install` to install pre-commit hooks to do linting and formatting.
-6. Run the test suite before finalizing your edits: `uv run pytest tests`
-7. Make a PR against the `dev` branch of the main repo.
+1. Fork and clone the repository
+2. `uv sync` to create a virtual environment and install dependencies
+3. `uv run pre-commit install` to set up linting and formatting hooks
+4. `uv run pytest tests` to run the test suite
+5. Submit a PR against the `dev` branch

docs/source/api/index.rst

@@ -1,157 +1,11 @@
 API Reference
 =============
 
-This page contains the complete API reference for ``ezmsg.sigproc``.
-
-.. contents:: Modules
-   :local:
-   :depth: 1
-
-Base Processors
----------------
-
-Core processor protocols and base classes.
-
-.. autosummary::
-   :toctree: generated
-   :recursive:
-
-   ezmsg.sigproc.base
-
-Filtering
----------
-
-Various filter implementations for signal processing.
-
-.. autosummary::
-   :toctree: generated
-   :recursive:
-
-   ezmsg.sigproc.filter
-   ezmsg.sigproc.butterworthfilter
-   ezmsg.sigproc.cheby
-   ezmsg.sigproc.combfilter
-   ezmsg.sigproc.adaptive_lattice_notch
-   ezmsg.sigproc.firfilter
-   ezmsg.sigproc.kaiser
-   ezmsg.sigproc.ewmfilter
-   ezmsg.sigproc.filterbank
-   ezmsg.sigproc.filterbankdesign
-   ezmsg.sigproc.gaussiansmoothing
-
-Spectral Analysis
------------------
-
-Spectral and frequency domain analysis tools.
-
-.. autosummary::
-   :toctree: generated
-   :recursive:
-
-   ezmsg.sigproc.spectral
-   ezmsg.sigproc.spectrogram
-   ezmsg.sigproc.spectrum
-   ezmsg.sigproc.wavelets
-   ezmsg.sigproc.bandpower
-   ezmsg.sigproc.fbcca
-
-Sampling & Resampling
----------------------
-
-Signal sampling, windowing, and resampling operations.
-
-.. autosummary::
-   :toctree: generated
-   :recursive:
-
-   ezmsg.sigproc.sampler
-   ezmsg.sigproc.window
-   ezmsg.sigproc.resample
-   ezmsg.sigproc.downsample
-   ezmsg.sigproc.decimate
-
-Signal Conditioning
--------------------
-
-Signal preprocessing and conditioning operations.
-
-.. autosummary::
-   :toctree: generated
-   :recursive:
-
-   ezmsg.sigproc.scaler
-   ezmsg.sigproc.detrend
-   ezmsg.sigproc.activation
-   ezmsg.sigproc.quantize
-   ezmsg.sigproc.ewma
-
-Transformations
----------------
-
-Geometric and structural transformations.
-
-.. autosummary::
-   :toctree: generated
-   :recursive:
-
-   ezmsg.sigproc.affinetransform
-   ezmsg.sigproc.transpose
-   ezmsg.sigproc.extract_axis
-   ezmsg.sigproc.slicer
-
-Signal Operations
------------------
-
-Aggregation, difference, and other signal operations.
-
-.. autosummary::
-   :toctree: generated
-   :recursive:
-
-   ezmsg.sigproc.aggregate
-   ezmsg.sigproc.diff
-
-Signal Generation
------------------
-
-Synthetic signal generators and injectors.
-
-.. autosummary::
-   :toctree: generated
-   :recursive:
-
-   ezmsg.sigproc.synth
-   ezmsg.sigproc.signalinjector
-
-Messages & Data Structures
----------------------------
-
-Message types and data structures.
-
-.. autosummary::
-   :toctree: generated
-   :recursive:
-
-   ezmsg.sigproc.messages
-
-Math Utilities
---------------
-
-Mathematical operations on signals.
-
-.. autosummary::
-   :toctree: generated
-   :recursive:
-
-   ezmsg.sigproc.math
-
-Utilities
----------
-
-Helper utilities for signal processing.
+This page contains auto-generated API reference documentation.
 
 .. autosummary::
    :toctree: generated
    :recursive:
+   :template: autosummary/module.rst
 
-   ezmsg.sigproc.util
+   ezmsg.sigproc

docs/source/guides/ProcessorsBase.md

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

docs/source/guides/sigproc/architecture.rst

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

docs/source/guides/sigproc/content-sigproc.rst

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