ezmsg-learn 1.0__tar.gz

ezmsg_learn-1.0/.github/workflows/python-publish-ezmsg-learn.yml

@@ -0,0 +1,26 @@
+name: Upload Python Package - ezmsg-learn
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: build and upload release to PyPI
+    runs-on: ubuntu-latest
+    environment: "release"
+    permissions:
+      id-token: write  # IMPORTANT: this permission is mandatory for trusted publishing
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Build Package
+        run: uv build
+
+      - name: Publish package distributions to PyPI
+        run: uv publish

ezmsg_learn-1.0/.github/workflows/python-tests.yml

@@ -0,0 +1,41 @@
+name: Test package
+
+on:
+  push:
+    branches:
+      - main
+      - dev
+  pull_request:
+    branches:
+      - main
+      - dev
+  workflow_dispatch:
+
+jobs:
+  build:
+    strategy:
+      matrix:
+        python-version: ["3.12"]
+        os:
+          - "ubuntu-latest"
+          - "windows-latest"
+          - "macos-latest"
+    runs-on: ${{matrix.os}}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install the project
+        run: uv sync
+
+      - name: Lint
+        run:
+          uv tool run ruff check --output-format=github src
+
+      - name: Run tests
+        run: uv run pytest tests

ezmsg_learn-1.0/.gitignore

@@ -0,0 +1,174 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+
+# PyPI configuration file
+.pypirc
+
+src/ezmsg/learn/__version__.py
+uv.lock

ezmsg_learn-1.0/.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  rev: v0.11.12
+  hooks:
+    - id: ruff
+      args: [ --fix ]
+    - id: ruff-format

ezmsg_learn-1.0/PKG-INFO

@@ -0,0 +1,34 @@
+Metadata-Version: 2.4
+Name: ezmsg-learn
+Version: 1.0
+Summary: ezmsg namespace package for machine learning
+Author-email: Chadwick Boulay <chadwick.boulay@gmail.com>
+License-Expression: MIT
+Requires-Python: >=3.10.15
+Requires-Dist: ezmsg-sigproc
+Requires-Dist: river>=0.22.0
+Requires-Dist: scikit-learn>=1.6.0
+Requires-Dist: torch>=2.6.0
+Description-Content-Type: text/markdown
+
+# ezmsg-learn
+
+This repository contains a Python package with modules for machine learning (ML)-related processing in the [`ezmsg`](https://www.ezmsg.org) framework. As ezmsg is intended primarily for processing unbounded streaming signals, so are the modules in this repo.
+
+> If you are only interested in offline analysis without concern for reproducibility in online applications, then you should probably look elsewhere.
+
+Processing units include dimensionality reduction, linear regression, and classification that can be initialized with known weights, or adapted on-the-fly with incoming (labeled) data. Machine-learning code depends on `river`, `scikit-learn`, `numpy`, and `torch`.
+
+## Getting Started
+
+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
+```

ezmsg_learn-1.0/README.md

@@ -0,0 +1,21 @@
+# ezmsg-learn
+
+This repository contains a Python package with modules for machine learning (ML)-related processing in the [`ezmsg`](https://www.ezmsg.org) framework. As ezmsg is intended primarily for processing unbounded streaming signals, so are the modules in this repo.
+
+> If you are only interested in offline analysis without concern for reproducibility in online applications, then you should probably look elsewhere.
+
+Processing units include dimensionality reduction, linear regression, and classification that can be initialized with known weights, or adapted on-the-fly with incoming (labeled) data. Machine-learning code depends on `river`, `scikit-learn`, `numpy`, and `torch`.
+
+## Getting Started
+
+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
+```

ezmsg_learn-1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[project]
+name = "ezmsg-learn"
+description = "ezmsg namespace package for machine learning"
+readme = "README.md"
+authors = [
+    { name = "Chadwick Boulay", email = "chadwick.boulay@gmail.com" }
+]
+license = "MIT"
+requires-python = ">=3.10.15"
+dynamic = ["version"]
+dependencies = [
+    "ezmsg-sigproc",
+    "river>=0.22.0",
+    "scikit-learn>=1.6.0",
+    "torch>=2.6.0",
+]
+
+[dependency-groups]
+dev = [
+  {include-group = "lint"},
+  {include-group = "test"},
+  "pre-commit>=4.3.0",
+]
+lint = [
+    "ruff>=0.12.9",
+]
+test = [
+    "hmmlearn>=0.3.3",
+    "pytest>=8.4.1",
+]
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.hooks.vcs]
+version-file = "src/ezmsg/learn/__version__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ezmsg"]
+
+[tool.pytest.ini_options]
+pythonpath = [
+    "src",
+    ".",
+]

ezmsg_learn-1.0/src/ezmsg/learn/__init__.py

@@ -0,0 +1,2 @@
+def hello() -> str:
+    return "Hello from ezmsg-learn!"

ezmsg_learn-1.0/src/ezmsg/learn/__version__.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '1.0'
+__version_tuple__ = version_tuple = (1, 0)
+
+__commit_id__ = commit_id = None

ezmsg_learn-1.0/src/ezmsg/learn/dim_reduce/adaptive_decomp.py

@@ -0,0 +1,284 @@
+import typing
+
+from sklearn.decomposition import IncrementalPCA, MiniBatchNMF
+import numpy as np
+import ezmsg.core as ez
+from ezmsg.sigproc.base import (
+    processor_state,
+    BaseAdaptiveTransformer,
+    BaseAdaptiveTransformerUnit,
+)
+from ezmsg.util.messages.axisarray import AxisArray, replace
+
+
+class AdaptiveDecompSettings(ez.Settings):
+    axis: str = "!time"
+    n_components: int = 2
+
+
+@processor_state
+class AdaptiveDecompState:
+    template: AxisArray | None = None
+    axis_groups: tuple[str, list[str], list[str]] | None = None
+    estimator: typing.Any = None
+
+
+EstimatorType = typing.TypeVar(
+    "EstimatorType", bound=typing.Union[IncrementalPCA, MiniBatchNMF]
+)
+
+
+class AdaptiveDecompTransformer(
+    BaseAdaptiveTransformer[
+        AdaptiveDecompSettings, AxisArray, AxisArray, AdaptiveDecompState
+    ],
+    typing.Generic[EstimatorType],
+):
+    """
+    Base class for adaptive decomposition transformers. See IncrementalPCATransformer and MiniBatchNMFTransformer
+    for concrete implementations.
+
+    Note that for these classes, adaptation is not automatic. The user must call partial_fit on the transformer.
+    For automated adaptation, see IncrementalDecompTransformer.
+    """
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._state.estimator = self._create_estimator()
+
+    @classmethod
+    def get_message_type(cls, dir: str) -> typing.Type[AxisArray]:
+        # Override because we don't reuse the generic types.
+        return AxisArray
+
+    @classmethod
+    def get_estimator_type(cls) -> typing.Type[EstimatorType]:
+        return typing.get_args(cls.__orig_bases__[0])[0]
+
+    def _create_estimator(self) -> EstimatorType:
+        estimator_klass = self.get_estimator_type()
+        estimator_settings = self.settings.__dict__.copy()
+        estimator_settings.pop("axis")
+        return estimator_klass(**estimator_settings)
+
+    def _calculate_axis_groups(self, message: AxisArray):
+        if self.settings.axis.startswith("!"):
+            # Iterate over the !axis and collapse all other axes
+            iter_axis = self.settings.axis[1:]
+            it_ax_ix = message.get_axis_idx(iter_axis)
+            targ_axes = message.dims[:it_ax_ix] + message.dims[it_ax_ix + 1 :]
+            off_targ_axes = []
+        else:
+            # Do PCA on the parameterized axis
+            targ_axes = [self.settings.axis]
+            # Iterate over streaming axis
+            iter_axis = "win" if "win" in message.dims else "time"
+            if iter_axis == self.settings.axis:
+                raise ValueError(
+                    f"Iterating axis ({iter_axis}) cannot be the same as the target axis ({self.settings.axis})"
+                )
+            it_ax_ix = message.get_axis_idx(iter_axis)
+            # Remaining axes are to be treated independently
+            off_targ_axes = [
+                _
+                for _ in (message.dims[:it_ax_ix] + message.dims[it_ax_ix + 1 :])
+                if _ != self.settings.axis
+            ]
+        self._state.axis_groups = iter_axis, targ_axes, off_targ_axes
+
+    def _hash_message(self, message: AxisArray) -> int:
+        iter_axis = (
+            self.settings.axis[1:]
+            if self.settings.axis.startswith("!")
+            else ("win" if "win" in message.dims else "time")
+        )
+        ax_idx = message.get_axis_idx(iter_axis)
+        sample_shape = message.data.shape[:ax_idx] + message.data.shape[ax_idx + 1 :]
+        return hash((sample_shape, message.key))
+
+    def _reset_state(self, message: AxisArray) -> None:
+        """Reset state"""
+        self._calculate_axis_groups(message)
+        iter_axis, targ_axes, off_targ_axes = self._state.axis_groups
+
+        # Template
+        out_dims = [iter_axis] + off_targ_axes
+        out_axes = {
+            iter_axis: message.axes[iter_axis],
+            **{k: message.axes[k] for k in off_targ_axes},
+        }
+        if len(targ_axes) == 1:
+            targ_ax_name = targ_axes[0]
+        else:
+            targ_ax_name = "components"
+        out_dims += [targ_ax_name]
+        out_axes[targ_ax_name] = AxisArray.CoordinateAxis(
+            data=np.arange(self.settings.n_components).astype(str),
+            dims=[targ_ax_name],
+            unit="component",
+        )
+        out_shape = [message.data.shape[message.get_axis_idx(_)] for _ in off_targ_axes]
+        out_shape = (0,) + tuple(out_shape) + (self.settings.n_components,)
+        self._state.template = replace(
+            message,
+            data=np.zeros(out_shape, dtype=float),
+            dims=out_dims,
+            axes=out_axes,
+        )
+
+    def _process(self, message: AxisArray) -> AxisArray:
+        iter_axis, targ_axes, off_targ_axes = self._state.axis_groups
+        ax_idx = message.get_axis_idx(iter_axis)
+        in_dat = message.data
+
+        if in_dat.shape[ax_idx] == 0:
+            return self._state.template
+
+        # Re-order axes
+        sorted_dims_exp = [iter_axis] + off_targ_axes + targ_axes
+        if message.dims != sorted_dims_exp:
+            # TODO: Implement axes transposition if needed
+            # re_order = [ax_idx] + off_targ_inds + targ_inds
+            # np.transpose(in_dat, re_order)
+            pass
+
+        # fold [iter_axis] + off_targ_axes together and fold targ_axes together
+        d2 = np.prod(in_dat.shape[len(off_targ_axes) + 1 :])
+        in_dat = in_dat.reshape((-1, d2))
+
+        replace_kwargs = {
+            "axes": {**self._state.template.axes, iter_axis: message.axes[iter_axis]},
+        }
+
+        # Transform data
+        if hasattr(self._state.estimator, "components_"):
+            decomp_dat = self._state.estimator.transform(in_dat).reshape(
+                (-1,) + self._state.template.data.shape[1:]
+            )
+            replace_kwargs["data"] = decomp_dat
+
+        return replace(self._state.template, **replace_kwargs)
+
+    def partial_fit(self, message: AxisArray) -> None:
+        # Check if we need to reset state
+        msg_hash = self._hash_message(message)
+        if self._hash != msg_hash:
+            self._reset_state(message)
+            self._hash = msg_hash
+
+        iter_axis, targ_axes, off_targ_axes = self._state.axis_groups
+        ax_idx = message.get_axis_idx(iter_axis)
+        in_dat = message.data
+
+        if in_dat.shape[ax_idx] == 0:
+            return
+
+        # Re-order axes if needed
+        sorted_dims_exp = [iter_axis] + off_targ_axes + targ_axes
+        if message.dims != sorted_dims_exp:
+            # TODO: Implement axes transposition if needed
+            pass
+
+        # fold [iter_axis] + off_targ_axes together and fold targ_axes together
+        d2 = np.prod(in_dat.shape[len(off_targ_axes) + 1 :])
+        in_dat = in_dat.reshape((-1, d2))
+
+        # Fit the estimator
+        self._state.estimator.partial_fit(in_dat)
+
+
+class IncrementalPCASettings(AdaptiveDecompSettings):
+    # Additional settings specific to PCA
+    whiten: bool = False
+    batch_size: typing.Optional[int] = None
+
+
+class IncrementalPCATransformer(AdaptiveDecompTransformer[IncrementalPCA]):
+    pass
+
+
+class MiniBatchNMFSettings(AdaptiveDecompSettings):
+    # Additional settings specific to NMF
+    init: typing.Optional[str] = "random"
+    """
+    'random', 'nndsvd', 'nndsvda', 'nndsvdar', 'custom', or None
+    """
+
+    batch_size: int = 1024
+    """
+    batch_size is used only when doing a full fit (i.e., a reset),
+    or as the exponent to forget_factor, where a very small batch_size
+    will cause the model to update more slowly.
+    It is better to set batch_size to a larger number than the expected
+    chunk size and instead use forget_factor to control the learning rate.
+    """
+
+    beta_loss: typing.Union[str, float] = "frobenius"
+    """
+    'frobenius', 'kullback-leibler', 'itakura-saito'
+    Note that values different from 'frobenius'
+        (or 2) and 'kullback-leibler' (or 1) lead to significantly slower
+        fits. Note that for `beta_loss <= 0` (or 'itakura-saito'), the input
+        matrix `X` cannot contain zeros.
+    """
+
+    tol: float = 1e-4
+
+    max_no_improvement: typing.Optional[int] = None
+
+    max_iter: int = 200
+
+    alpha_W: float = 0.0
+
+    alpha_H: typing.Union[float, str] = "same"
+
+    l1_ratio: float = 0.0
+
+    forget_factor: float = 0.7
+
+
+class MiniBatchNMFTransformer(AdaptiveDecompTransformer[MiniBatchNMF]):
+    pass
+
+
+SettingsType = typing.TypeVar(
+    "SettingsType", bound=typing.Union[IncrementalPCASettings, MiniBatchNMFSettings]
+)
+TransformerType = typing.TypeVar(
+    "TransformerType",
+    bound=typing.Union[IncrementalPCATransformer, MiniBatchNMFTransformer],
+)
+
+
+class BaseAdaptiveDecompUnit(
+    BaseAdaptiveTransformerUnit[
+        SettingsType,
+        AxisArray,
+        AxisArray,
+        TransformerType,
+    ],
+    typing.Generic[SettingsType, TransformerType],
+):
+    INPUT_SAMPLE = ez.InputStream(AxisArray)
+
+    @ez.subscriber(INPUT_SAMPLE)
+    async def on_sample(self, msg: AxisArray) -> None:
+        await self.processor.apartial_fit(msg)
+
+
+class IncrementalPCAUnit(
+    BaseAdaptiveDecompUnit[
+        IncrementalPCASettings,
+        IncrementalPCATransformer,
+    ]
+):
+    SETTINGS = IncrementalPCASettings
+
+
+class MiniBatchNMFUnit(
+    BaseAdaptiveDecompUnit[
+        MiniBatchNMFSettings,
+        MiniBatchNMFTransformer,
+    ]
+):
+    SETTINGS = MiniBatchNMFSettings