ezmsg-learn 1.0__tar.gz → 1.1.0__tar.gz

ezmsg_learn-1.1.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_learn-1.0/.github/workflows/python-publish-ezmsg-learn.yml → ezmsg_learn-1.1.0/.github/workflows/python-publish.yml

@@ -1,4 +1,4 @@
-name: Upload Python Package - ezmsg-learn
+name: Upload Python Package
 
 on:
   release:

{ezmsg_learn-1.0 → ezmsg_learn-1.1.0}/.github/workflows/python-tests.yml

@@ -15,7 +15,7 @@ jobs:
   build:
     strategy:
       matrix:
-        python-version: ["3.12"]
+        python-version: ["3.12", "3.13"]
         os:
           - "ubuntu-latest"
           - "windows-latest"
@@ -37,5 +37,10 @@ jobs:
         run:
           uv tool run ruff check --output-format=github src
 
-      - name: Run tests
-        run: uv run pytest tests
+      - name: Run unit tests
+        run: uv run pytest tests/unit tests/dim_reduce -v
+
+      - name: Run integration tests
+        run: uv run pytest tests/integration -v --tb=long
+        env:
+          PYTHONFAULTHANDLER: 1

{ezmsg_learn-1.0 → ezmsg_learn-1.1.0}/.gitignore

@@ -70,6 +70,8 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/build/
+docs/source/api/generated
 
 # PyBuilder
 .pybuilder/

ezmsg_learn-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ezmsg-org
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{ezmsg_learn-1.0 → ezmsg_learn-1.1.0}/PKG-INFO

@@ -1,11 +1,13 @@
 Metadata-Version: 2.4
 Name: ezmsg-learn
-Version: 1.0
+Version: 1.1.0
 Summary: ezmsg namespace package for machine learning
 Author-email: Chadwick Boulay <chadwick.boulay@gmail.com>
 License-Expression: MIT
+License-File: LICENSE
 Requires-Python: >=3.10.15
-Requires-Dist: ezmsg-sigproc
+Requires-Dist: ezmsg-baseproc>=1.0.2
+Requires-Dist: ezmsg-sigproc>=2.14.0
 Requires-Dist: river>=0.22.0
 Requires-Dist: scikit-learn>=1.6.0
 Requires-Dist: torch>=2.6.0
@@ -24,11 +26,5 @@ Processing units include dimensionality reduction, linear regression, and classi
 This ezmsg namespace package is still highly experimental and under active development. It is not yet available on PyPI, so you will need to install it from source. The easiest way to do this is to use the `pip` command to install the package directly from GitHub:
 
 ```bash
-pip install git+ssh://git@github.com/ezmsg-org/ezmsg-learn
-```
-
-Note that this package depends on a specific version of `ezmsg-sigproc` (specifically, [this branch]("70-use-protocols-for-axisarray-transformers")) that has yet to be merged and released. This may conflict with your project's separate dependency on ezmsg-sigproc. However, this specific version of ezmsg-sigproc should be backwards compatible with its main branch, so in your project you can modify the dependency on ezmsg-sigproc to point to the new branch. e.g.,
-
-```bash
-pip install git+ssh://git@github.com/ezmsg-org/ezmsg-sigproc@70-use-protocols-for-axisarray-transformers
+pip install git+https://github.com/ezmsg-org/ezmsg-learn
 ```

{ezmsg_learn-1.0 → ezmsg_learn-1.1.0}/README.md

@@ -11,11 +11,5 @@ Processing units include dimensionality reduction, linear regression, and classi
 This ezmsg namespace package is still highly experimental and under active development. It is not yet available on PyPI, so you will need to install it from source. The easiest way to do this is to use the `pip` command to install the package directly from GitHub:
 
 ```bash
-pip install git+ssh://git@github.com/ezmsg-org/ezmsg-learn
-```
-
-Note that this package depends on a specific version of `ezmsg-sigproc` (specifically, [this branch]("70-use-protocols-for-axisarray-transformers")) that has yet to be merged and released. This may conflict with your project's separate dependency on ezmsg-sigproc. However, this specific version of ezmsg-sigproc should be backwards compatible with its main branch, so in your project you can modify the dependency on ezmsg-sigproc to point to the new branch. e.g.,
-
-```bash
-pip install git+ssh://git@github.com/ezmsg-org/ezmsg-sigproc@70-use-protocols-for-axisarray-transformers
+pip install git+https://github.com/ezmsg-org/ezmsg-learn
 ```

ezmsg_learn-1.1.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_learn-1.1.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_learn-1.1.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_learn-1.1.0/docs/source/api/index.rst

@@ -0,0 +1,11 @@
+API Reference
+=============
+
+This page contains auto-generated API reference documentation.
+
+.. autosummary::
+   :toctree: generated
+   :recursive:
+   :template: autosummary/module.rst
+
+   ezmsg.learn

ezmsg_learn-1.1.0/docs/source/conf.py

@@ -0,0 +1,123 @@
+# 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.learn"
+copyright = "2024, ezmsg Contributors"
+author = "ezmsg Contributors"
+
+# The version is managed by hatch-vcs and stored in __version__.py
+try:
+    from ezmsg.learn.__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",
+    "sphinx_copybutton",
+]
+
+templates_path = ["_templates"]
+source_suffix = [".rst"]
+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),
+    "torch": ("https://pytorch.org/docs/stable/", None),
+    "sklearn": ("https://scikit-learn.org/stable/", None),
+    "ezmsg": ("https://www.ezmsg.org/ezmsg/", None),
+    "ezmsg.sigproc": ("https://www.ezmsg.org/ezmsg-sigproc/", None),
+    "ezmsg.event": ("https://www.ezmsg.org/ezmsg-event/", None),
+    "ezmsg.lsl": ("https://www.ezmsg.org/ezmsg-lsl/", 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-learn/"
+
+html_theme_options = {
+    "logo": {
+        "text": f"ezmsg.learn {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-learn",
+            "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-learn/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_learn-1.1.0/docs/source/guides/classification.rst

@@ -0,0 +1,267 @@
+Real-Time Classification
+========================
+
+This guide shows how to use ezmsg-learn for real-time classification in streaming pipelines.
+
+.. contents:: On this page
+   :local:
+   :depth: 2
+
+
+Overview
+--------
+
+ezmsg-learn provides machine learning components that integrate with ezmsg pipelines.
+Key features include:
+
+- **Pre-trained models**: Load and apply existing classifiers
+- **Online learning**: Update models incrementally with streaming data
+- **Flexible backends**: Support for scikit-learn, PyTorch, and River models
+
+
+Available Classifiers
+---------------------
+
+ezmsg-learn includes several classifier types:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 40 35
+
+   * - Classifier
+     - Description
+     - Use Case
+   * - ``SLDA``
+     - Shrinkage Linear Discriminant Analysis
+     - BCI, small datasets
+   * - ``SklearnModelUnit``
+     - Wrapper for any scikit-learn model
+     - General ML tasks
+   * - ``SGDClassifier``
+     - Stochastic Gradient Descent
+     - Online learning
+   * - ``MLPUnit``
+     - Multi-layer Perceptron (PyTorch)
+     - Complex patterns
+
+
+Using a Pre-Trained SLDA Classifier
+-----------------------------------
+
+The simplest approach is to use a pre-trained model:
+
+.. code-block:: python
+
+   from ezmsg.learn.process.slda import SLDA, SLDASettings
+
+   classifier = SLDA(
+       SLDASettings(
+           settings_path="path/to/trained_model.pkl",
+           axis="time",  # Axis containing samples
+       )
+   )
+
+**Input format**: ``AxisArray[time, features]`` where features are flattened from your pipeline.
+
+**Output format**: ``ClassifierMessage[time, classes]`` with class probabilities.
+
+Training an SLDA model (offline):
+
+.. code-block:: python
+
+   import pickle
+   from sklearn.discriminant_analysis import LinearDiscriminantAnalysis as LDA
+
+   # Train offline with your data
+   X_train = ...  # shape: (n_samples, n_features)
+   y_train = ...  # shape: (n_samples,)
+
+   lda = LDA(solver="lsqr", shrinkage="auto")
+   lda.fit(X_train, y_train)
+
+   # Save for use in ezmsg
+   with open("trained_model.pkl", "wb") as f:
+       pickle.dump(lda, f)
+
+
+Using Scikit-Learn Models
+-------------------------
+
+``SklearnModelUnit`` wraps any scikit-learn compatible model:
+
+.. code-block:: python
+
+   from ezmsg.learn.process.sklearn import SklearnModelUnit, SklearnModelSettings
+   import numpy as np
+
+   classifier = SklearnModelUnit(
+       SklearnModelSettings(
+           model_class="sklearn.linear_model.SGDClassifier",
+           model_kwargs={
+               "loss": "log_loss",  # For probability outputs
+               "warm_start": True,
+           },
+           partial_fit_classes=np.array([0, 1]),  # Required for online learning
+       )
+   )
+
+Loading a pre-trained model:
+
+.. code-block:: python
+
+   classifier = SklearnModelUnit(
+       SklearnModelSettings(
+           model_class="sklearn.linear_model.SGDClassifier",
+           checkpoint_path="path/to/saved_model.pkl",
+       )
+   )
+
+
+Online Learning
+---------------
+
+For models that support ``partial_fit``, you can update them during streaming:
+
+.. code-block:: python
+
+   from ezmsg.learn.process.sklearn import SklearnModelProcessor, SklearnModelSettings
+   from ezmsg.sigproc.sampler import SampleMessage
+
+   # Create processor with online learning support
+   processor = SklearnModelProcessor(
+       settings=SklearnModelSettings(
+           model_class="sklearn.linear_model.SGDClassifier",
+           model_kwargs={"loss": "log_loss"},
+           partial_fit_classes=np.array([0, 1]),
+       )
+   )
+
+   # Training with labeled samples
+   sample_msg = SampleMessage(
+       sample=feature_array,  # AxisArray with features
+       trigger=label_value,   # The class label
+   )
+   processor.partial_fit(sample_msg)
+
+   # Prediction (after training)
+   prediction = processor(input_features)
+
+
+Complete Pipeline Example
+-------------------------
+
+Here's a complete BCI classification pipeline:
+
+.. code-block:: python
+
+   import ezmsg.core as ez
+   from ezmsg.lsl.inlet import LSLInletUnit, LSLInletSettings, LSLInfo
+   from ezmsg.lsl.outlet import LSLOutletUnit, LSLOutletSettings
+   from ezmsg.sigproc.butterworthfilter import ButterworthFilter, ButterworthFilterSettings
+   from ezmsg.sigproc.window import Window, WindowSettings
+   from ezmsg.sigproc.spectrum import Spectrum, SpectrumSettings
+   from ezmsg.sigproc.aggregate import RangedAggregate, RangedAggregateSettings, AggregationFunction
+   from ezmsg.learn.process.slda import SLDA, SLDASettings
+
+   components = {
+       # Data acquisition
+       "LSL_IN": LSLInletUnit(
+           LSLInletSettings(info=LSLInfo(name="EEG", type="EEG"))
+       ),
+
+       # Signal processing
+       "FILTER": ButterworthFilter(
+           ButterworthFilterSettings(order=4, cuton=8.0, cutoff=30.0)
+       ),
+       "WINDOW": Window(
+           WindowSettings(window_dur=1.0, window_shift=0.5)
+       ),
+       "SPECTRUM": Spectrum(SpectrumSettings(window="hann")),
+       "BANDPOWER": RangedAggregate(
+           RangedAggregateSettings(
+               axis="freq",
+               bands=[(8.0, 12.0), (18.0, 25.0)],
+               operation=AggregationFunction.MEAN,
+           )
+       ),
+
+       # Classification
+       "CLASSIFIER": SLDA(
+           SLDASettings(settings_path="model.pkl", axis="time")
+       ),
+
+       # Output
+       "LSL_OUT": LSLOutletUnit(
+           LSLOutletSettings(stream_name="Predictions", stream_type="Markers")
+       ),
+   }
+
+   connections = (
+       (components["LSL_IN"].OUTPUT_SIGNAL, components["FILTER"].INPUT_SIGNAL),
+       (components["FILTER"].OUTPUT_SIGNAL, components["WINDOW"].INPUT_SIGNAL),
+       (components["WINDOW"].OUTPUT_SIGNAL, components["SPECTRUM"].INPUT_SIGNAL),
+       (components["SPECTRUM"].OUTPUT_SIGNAL, components["BANDPOWER"].INPUT_SIGNAL),
+       (components["BANDPOWER"].OUTPUT_SIGNAL, components["CLASSIFIER"].INPUT_SIGNAL),
+       (components["CLASSIFIER"].OUTPUT_SIGNAL, components["LSL_OUT"].INPUT_SIGNAL),
+   )
+
+   if __name__ == "__main__":
+       ez.run(components=components, connections=connections)
+
+
+Feature Preparation
+-------------------
+
+Classifiers expect flattened 2D input ``[samples, features]``. Multi-dimensional arrays
+are automatically flattened along the channel dimension.
+
+For example, if your bandpower output is ``[time=1, band=2, ch=8]``:
+
+- The classifier receives shape ``[1, 16]`` (2 bands × 8 channels)
+- Features are flattened in C-order (row-major)
+
+
+Output Format
+-------------
+
+Classification outputs use ``ClassifierMessage``, which extends ``AxisArray`` with:
+
+- **dims**: ``["time", "classes"]``
+- **data**: Probability scores for each class
+- **labels**: List of class names/identifiers
+
+Example output shape: ``[time=1, classes=2]`` with probabilities for each class.
+
+
+Tips for Better Performance
+---------------------------
+
+1. **Normalize features**: Use ``Scaler`` from ezmsg-sigproc before classification
+
+   .. code-block:: python
+
+      from ezmsg.sigproc.scaler import Scaler, ScalerSettings
+      scaler = Scaler(ScalerSettings(mode="zscore"))
+
+2. **Match training conditions**: Ensure online features match offline training preprocessing
+
+3. **Window size**: Larger windows give more stable features but higher latency
+
+4. **Feature selection**: Start with relevant frequency bands for your application
+
+
+Troubleshooting
+---------------
+
+**"Model has not been fit yet"**:
+   The model needs training data before prediction. Either:
+   - Provide a ``checkpoint_path`` with a pre-trained model
+   - Call ``fit()`` or ``partial_fit()`` before processing
+
+**Shape mismatch errors**:
+   - Verify input feature dimensions match trained model
+   - Check ``n_features_in_`` attribute of loaded models
+
+**NaN in predictions**:
+   - Ensure input features don't contain NaN values
+   - Check for numerical stability in preprocessing