ezmsg-sigproc 2.2.0__tar.gz → 2.4.0__tar.gz

ezmsg_sigproc-2.4.0/.github/workflows/docs.yml

@@ -0,0 +1,65 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - 'v*'
+  pull_request:
+    branches:
+      - dev
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Needed for hatch-vcs to determine version
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          python-version: "3.12"
+
+      - name: Install the project
+        run: uv sync --only-group docs
+
+      - name: Build documentation
+        run: |
+          cd docs
+          uv run make html
+
+      - name: Add .nojekyll file
+        run: touch docs/build/html/.nojekyll
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: 'docs/build/html'
+
+  deploy:
+    # Only deploy on push to main or release tags
+    if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v'))
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

{ezmsg_sigproc-2.2.0 → ezmsg_sigproc-2.4.0}/.gitignore

@@ -70,8 +70,10 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/build/
 docs/source/_build
 docs/source/generated
+docs/source/api/generated
 
 # PyBuilder
 .pybuilder/
@@ -144,3 +146,4 @@ cython_debug/
 
 src/ezmsg/sigproc/__version__.py
 uv.lock
+*.local.json

{ezmsg_sigproc-2.2.0 → ezmsg_sigproc-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ezmsg-sigproc
-Version: 2.2.0
+Version: 2.4.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>
 License-Expression: MIT

ezmsg_sigproc-2.4.0/docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

ezmsg_sigproc-2.4.0/docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

ezmsg_sigproc-2.4.0/docs/source/_templates/autosummary/module.rst

@@ -0,0 +1,64 @@
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: Module Attributes
+
+   .. autosummary::
+      :toctree:
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: Functions
+
+   {% for item in functions %}
+   .. autofunction:: {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: Classes
+
+   {% for item in classes %}
+   .. autoclass:: {{ item }}
+      :members:
+      :undoc-members:
+      :show-inheritance:
+      :special-members: __init__
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: Exceptions
+
+   {% for item in exceptions %}
+   .. autoexception:: {{ item }}
+      :members:
+      :show-inheritance:
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+{% block modules %}
+{% if modules %}
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+   :recursive:
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}

ezmsg_sigproc-2.4.0/docs/source/api/index.rst

@@ -0,0 +1,157 @@
+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.
+
+.. autosummary::
+   :toctree: generated
+   :recursive:
+
+   ezmsg.sigproc.util

ezmsg_sigproc-2.4.0/docs/source/conf.py

@@ -0,0 +1,127 @@
+# Configuration file for the Sphinx documentation builder.
+
+import os
+import sys
+
+# Add the source directory to the path
+sys.path.insert(0, os.path.abspath("../../src"))
+
+# -- Project information --------------------------
+
+project = "ezmsg.sigproc"
+copyright = "2024, ezmsg Contributors"
+author = "ezmsg Contributors"
+
+# The version is managed by hatch-vcs and stored in __version__.py
+try:
+    from ezmsg.sigproc.__version__ import version as release
+except ImportError:
+    release = "unknown"
+
+# For display purposes, extract the base version without git commit info
+version = release.split("+")[0] if release != "unknown" else release
+
+# -- General configuration --------------------------
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.duration",
+    # "sphinx_autodoc_typehints",  # Disabled due to compatibility issue
+    "sphinx_copybutton",
+    "myst_parser",  # For markdown files
+]
+
+templates_path = ["_templates"]
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# The toctree master document
+master_doc = "index"
+
+# -- Autodoc configuration ------------------------------
+
+# Auto-generate API docs
+autosummary_generate = True
+autosummary_imported_members = False
+autodoc_typehints = "description"
+autodoc_member_order = "bysource"
+autodoc_typehints_format = "short"
+python_use_unqualified_type_names = True
+autodoc_default_options = {
+    "members": True,
+    "member-order": "bysource",
+    "special-members": "__init__",
+    "undoc-members": True,
+    "show-inheritance": True,
+}
+
+# Don't show the full module path in the docs
+add_module_names = False
+
+# -- Intersphinx configuration --------------------------
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3/", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "scipy": ("https://scipy.org/doc/scipy/", None),
+    "ezmsg": ("https://www.ezmsg.org/ezmsg/", None),
+    "ezmsg.learn": ("https://www.ezmsg.org/ezmsg-learn/", None),
+    "ezmsg.event": ("https://www.ezmsg.org/ezmsg-event/", None),
+    "ezmsg.lsl": ("https://www.ezmsg.org/ezmsg-lsl/", None),
+    "ezmsg.blackrock": ("https://www.ezmsg.org/ezmsg-blackrock/", None),
+}
+intersphinx_disabled_domains = ["std"]
+
+# -- Options for HTML output -----------------------------
+
+html_theme = "pydata_sphinx_theme"
+html_static_path = ["_static"]
+
+# Set the base URL for the documentation
+html_baseurl = "https://www.ezmsg.org/ezmsg-sigproc/"
+
+html_theme_options = {
+    "logo": {
+        "text": f"ezmsg.sigproc {version}",
+        "link": "https://ezmsg.org",  # Link back to main site
+    },
+    "header_links_before_dropdown": 4,
+    "navbar_start": ["navbar-logo"],
+    "navbar_end": ["theme-switcher", "navbar-icon-links"],
+    "icon_links": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/ezmsg-org/ezmsg-sigproc",
+            "icon": "fa-brands fa-github",
+        },
+        {
+            "name": "ezmsg.org",
+            "url": "https://www.ezmsg.org",
+            "icon": "fa-solid fa-house",
+        },
+    ],
+}
+
+# Timestamp is inserted at every page bottom in this strftime format.
+html_last_updated_fmt = "%Y-%m-%d"
+
+# -- Options for linkcode -----------------------------
+
+branch = "main"
+code_url = f"https://github.com/ezmsg-org/ezmsg-sigproc/blob/{branch}/"
+
+
+def linkcode_resolve(domain, info):
+    if domain != "py":
+        return None
+    if not info["module"]:
+        return None
+    filename = info["module"].replace(".", "/")
+    return f"{code_url}src/{filename}.py"

ezmsg_sigproc-2.4.0/docs/source/guides/HybridBuffer.md

@@ -0,0 +1,87 @@
+## HybridBuffer
+
+The HybridBuffer is a stateful, FIFO buffer that combines a deque for fast appends with a contiguous circular buffer for efficient, advancing reads. The synchronization between the deque and the circular buffer can be immediate, upon threshold reaching, or on demand, allowing for flexible data management strategies.
+
+This buffer is designed to be agnostic to the array library used (e.g., NumPy, CuPy, PyTorch) via the Python Array API standard.
+
+### Basic Reading and Writing Behaviour
+
+The following diagram illustrates the states of the HybridBuffer across data writes and reads when `update_strategy="on_demand"`:
+
+![HybridBuffer Basic States](img/HybridBufferBasic.svg)
+
+**Figure 1**
+
+A. In the initial state, the buffer is empty, with no data in either the deque or the circular buffer.
+   * deq_len=0; available=0, tell=0
+
+B. After we `write()` 4 samples, the deque contains the new data, but the circular buffer is still empty.
+   * deq_len=4; available=4, tell=0
+
+C. After we `write()` 4 more samples, the deque now has 2 messages, each with 4 samples, and the circular buffer remains untouched.
+   * deq_len=8; available=8, tell=0
+
+D. Panels D-F depict a single call to `read(4)` which is implemented as calls to other methods. If we don't have 4 unread samples in the circular buffer, but we do have >= 4 samples 'available' (i.e., including the deque), then a `flush()` is performed: the entirety of the data in the deque are copied to the circular buffer and the deque is cleared.
+    * deq_len=0; available=8, tell=0
+    * TODO: Currently `flush()` copies the data twice, once from the deque to a contiguous array, and then from that contiguous array to the circular buffer. This should be optimized to copy directly from the deque to the circular buffer.
+
+E. Next we `peek(4)` which returns the first 4 samples from the circular buffer; the return value may be a view on the data if the data are contiguous in the circular buffer, or a copy if the data are not contiguous. Note that the tail (read pointer) does not advance with `peek()`.
+    * deq_len=0; available=8, tell=0
+
+F. Finally, we `seek(4)` to advance the tail.
+   * deq_len=0; available=4, tell=4
+
+G. We `write()` 4 more samples, which are appended to the deque, leaving the circular buffer unchanged from the previous step.
+   * deq_len=4; available=8, tell=4
+
+H. We then `read(4)` again. This time, a `flush()` is not triggered because we have enough unread samples in the circular buffer, but `peek(4)` and `seek(4)` are still called. The read pointer advances by 4, leaving 0 unread samples in the circular buffer and 4 in the deque.
+   * deq_len=4; available=0, tell=8
+
+Note: `peek(n)` and `seek(n)`, where `n` > `n_available` will raise an error. However, `peek(None)` will return all available samples without error, and `seek(None)` will advance the tail to the end of the available data.
+
+### Overflow Behaviour
+
+The criteria to trigger an overflow are as follows:
+* the deque has more data than there is space in the circular buffer, where space is the combination of previously read samples and unwritten samples in the circular buffer.
+* the caller triggers a flush either manually (`flush()`) or by requesting (via `read`, `peek`, or `seek`) more samples than are available in the circular buffer but not more than the total size of the available samples in the buffer + available samples in the deque.
+
+![HybridBuffer Overflow Behaviour](img/HybridBufferOverflow.svg)
+
+**Figure 2**
+
+A. We start with a circular buffer that has been running for a while (it has wrapped around several times). At this particular moment, we have more data in the deque (12) than we have room in the buffer (8). The remaining figures describe what happens when `flush()` is called with different overflow strategies. The samples are labeled to make it easier to follow the flow of data.
+   * deq_len=12; available=20, tell=1
+
+B. "warn-overwrite": If the overflow_strategy is set to 'warn-overwrite', the HybridBuffer will log a warning and overwrite the oldest data in the circular buffer with the new data from the deque. Here, samples 'a-d' are lost.
+   * deq_len=0; available=16, tell=0
+
+C. "drop": As much as possible of the data from the deque are copied into the circular buffer, but remaining data are dropped. In this case, samples 'q-t' are lost.
+   * deq_len=0; available=16, tell=0
+
+D. "grow": The HybridBuffer will attempt to grow the circular buffer to the lesser of double its current size or the size required to accommodate all read + unread + deque data. If the buffer cannot grow (e.g., due to memory constraints; default max_size is 1GB), it will raise an error.
+   * deq_len=0; available=20, tell=8
+
+Additionally, one can configure the HybridBuffer overflow_strategy to 'raise', which will raise an error if there is insufficient space (empty or read samples) in the buffer to perform the flush.
+
+There are a few mitigations to defer flushing to help prevent overflows:
+
+* If the requested number of samples to read, peek, or seek is less than the number of unread samples in the circular buffer, then no flush is performed.
+* Helper methods `peek_at(k, allow_flush=False)` (False is default), and `peek_last()` will retrieve the target sample from the buffer-OR-deque without flushing.
+  * Be cautious relying on repeated calls to `peek_at(k, allow_flush=False)` as it scans over the items in the deque which can be slow.
+* When calling `read(n)`, if a flush is necessary, and it will cause an overflow, and the overflow could be prevented with a pre-emptive read up to `n`, then it will do the read in 2 parts. First it will call `peek(n_unread_in_buffer)` and `seek(n_unread_in_buffer)` to read the unread samples in the circular buffer. Second, it will call `peek(n_remaining)` and `seek(n_remaining)` to trigger a flush -- which should no longer cause an overflow -- then read the remaining requested samples and stitch them together.
+
+### Advanced Pointer Manipulation
+
+The previous section describes how `read`, `peek`, `seek`, and `peek_at` function in normal use cases. It is also possible to call `seek` with a negative value, which will attempt to move the tail pointer backwards over previously-read (or previously sought-over) data by that many samples. `seek` returns the number of samples that were actually moved, which may be less than the requested value if there was insufficient room. Negative seeks can only rewind into previously read data, and positive seeks can only advance into unread data, possibly including data that gets flushed from the deque.
+
+## HybridAxisBuffer
+
+The `HybridAxisBuffer` carries the semantics of the `HybridBuffer` but it is designed to handle either a `LinearAxis` or a `CoordinateAxis`. Its `write` method expects an axis object and its `peek` and `read` methods return an axis, not just the data.
+
+For a `LinearAxis`, the `HybridAxisBuffer` simply maintains the `gain`, the `offset`, and the 'number of samples available'. Since this does not store actual data, it has no capacity. If this object is intended to be synchronized with another `HybridBuffer`-using object that does have a capacity, then the other object should be manipulated first and then the number of samples actually moved should be used to call the `HybridAxisBuffer`'s methods, otherwise these objects will be out of sync.
+
+For a `CoordinateAxis`, the `HybridAxisBuffer` maintains the `data` in a `HybridBuffer` and thus behaves like a `HybridBuffer` with respect to the capacity. The returned `CoordinateAxis` object might have its `.data` field as a view on the data in the buffer, so it should not be modified in place.
+
+## HybridAxisArrayBuffer
+
+This is a convenience class that combines the `HybridAxisBuffer` and `HybridBuffer` into a single object that can be used to manage both axis and data in a single object. This class is particularly useful when you need to manage both the axis information and the data samples together, as is the case for an `AxisArray` object. Its `write` method expects an `AxisArary` object and its `peek` and `read` methods return an `AxisArray` object. Note that the return object's `.data` field might be a view on the data in the buffer so it should not be modified in place. Similarly so for the `CoordinateAxis` data.