ezmsg-tools 0.3.2__tar.gz → 0.5.0__tar.gz

{ezmsg_tools-0.3.2 → ezmsg_tools-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ezmsg-tools
-Version: 0.3.2
+Version: 0.5.0
 Summary: ezmsg namespace package containing tools for working with ezmsg graphs.
 Author-email: Chadwick Boulay <chadwick.boulay@gmail.com>
 License-Expression: MIT
@@ -21,13 +21,13 @@ Requires-Dist: typer>=0.15.1; extra == 'perfmon'
 Provides-Extra: sigmon
 Requires-Dist: ezmsg-qt>=0.2.1; extra == 'sigmon'
 Requires-Dist: pandas; extra == 'sigmon'
-Requires-Dist: phosphor>=0.5.0; extra == 'sigmon'
+Requires-Dist: phosphor>=0.8.0; extra == 'sigmon'
 Requires-Dist: pygraphviz>=1.14; extra == 'sigmon'
 Requires-Dist: pyside6>=6.7; extra == 'sigmon'
 Requires-Dist: typer>=0.15.1; extra == 'sigmon'
 Provides-Extra: viewer
 Requires-Dist: ezmsg-qt>=0.2.1; extra == 'viewer'
-Requires-Dist: phosphor>=0.5.0; extra == 'viewer'
+Requires-Dist: phosphor>=0.8.0; extra == 'viewer'
 Requires-Dist: pyside6>=6.7; extra == 'viewer'
 Requires-Dist: typer>=0.15.1; extra == 'viewer'
 Description-Content-Type: text/markdown

{ezmsg_tools-0.3.2 → ezmsg_tools-0.5.0}/pyproject.toml

@@ -18,8 +18,8 @@ dependencies = [
 dev = [
     "pre-commit>=4.0.0",
     "scipy>=1.14.1",
-    "ezmsg-sigproc>=2.18.0",
-    "ezmsg-simbiophys>=1.4.1",
+    "ezmsg-sigproc>=2.36.0",
+    "ezmsg-simbiophys>=1.8.0",
     {include-group = "lint"},
     {include-group = "test"},
 ]
@@ -54,19 +54,19 @@ sigmon = [
     "pygraphviz>=1.14",
     "typer>=0.15.1",
     "ezmsg-qt>=0.2.1",
-    "phosphor>=0.5.0",
+    "phosphor>=0.8.0",
     "pandas",
 ]
 viewer = [
     "PySide6>=6.7",
     "typer>=0.15.1",
     "ezmsg-qt>=0.2.1",
-    "phosphor>=0.5.0",
+    "phosphor>=0.8.0",
 ]
 
 [project.scripts]
-ezmsg-performance-monitor = "ezmsg.tools.perfmon.cli:main"
-ezmsg-signal-monitor = "ezmsg.tools.sigmon.cli:main"
+ezmsg-performance-monitor = "ezmsg.tools.perfmon:main"
+ezmsg-signal-monitor = "ezmsg.tools.sigmon:main"
 
 [build-system]
 requires = ["hatchling", "hatch-vcs"]
@@ -99,5 +99,10 @@ known-first-party = ["ezmsg.tools"]
 known-third-party = ["ezmsg"]
 
 [tool.uv.sources]
+# Local path sources are a developer convenience and must not be committed: CI
+# has no sibling checkouts, so a path here fails resolution for every job,
+# including ones that never touch the package (`uv sync --only-group docs`).
+# Add them locally with `uv add ../phosphor --editable --frozen` and drop the
+# change before committing.
 # Uncomment to use development version of ezmsg from git
 #ezmsg = { git = "https://github.com/ezmsg-org/ezmsg.git", branch = "dev" }

ezmsg_tools-0.5.0/src/ezmsg/tools/__version__.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.5.0'
+__version_tuple__ = version_tuple = (0, 5, 0)
+
+__commit_id__ = commit_id = None

ezmsg_tools-0.5.0/src/ezmsg/tools/_entry.py

@@ -0,0 +1,42 @@
+"""Launching a console script whose dependencies live in an optional extra.
+
+Console scripts are installed unconditionally -- ``[project.scripts]`` has no
+notion of extras -- so ``pip install ezmsg-tools`` puts commands on the PATH
+whose imports are not satisfied. Run one and you get a bare
+``ModuleNotFoundError: dash`` with no hint that an extra exists or what it is
+called.
+
+The alternative would be promoting those dependencies to the core install, so
+that a Dash web app drags in Qt and a GPU stack for everyone. A clear message
+is the cheaper fix.
+"""
+
+import importlib
+import os
+import sys
+import typing
+
+__all__ = ["run_cli"]
+
+
+def run_cli(module: str, extra: str) -> typing.NoReturn:
+    """Import ``module`` and call its ``main()``, or explain what is missing.
+
+    :param module: Dotted path of the CLI module to run.
+    :param extra: The extra that declares this command's dependencies.
+    """
+    try:
+        cli = importlib.import_module(module)
+    except ImportError as exc:
+        command = os.path.basename(sys.argv[0]) or module
+        missing = getattr(exc, "name", None)
+        # Name the module that was actually missing rather than assuming the
+        # extra is the whole story: an ImportError from inside the CLI is a
+        # different problem, and saying which one it was keeps this honest.
+        detail = f" (could not import {missing!r})" if missing else ""
+        raise SystemExit(
+            f"{command} needs the optional '{extra}' dependencies{detail}.\n"
+            f"Install them with:\n\n"
+            f"    pip install 'ezmsg-tools[{extra}]'\n"
+        ) from exc
+    sys.exit(cli.main())

ezmsg_tools-0.5.0/src/ezmsg/tools/chmeta.py

@@ -0,0 +1,87 @@
+"""Turning a structured ``ch`` coordinate axis into per-channel display names.
+
+An AxisArray's ``ch`` axis usually carries a structured array with one row per
+channel. What is *in* those rows depends on the acquisition system: an LSL or
+NWB source typically offers a ``label``; a Blackrock source additionally offers
+``bank`` and ``elec``, which is what its users actually read off the front panel.
+A plot needs one string per channel, so something has to choose.
+
+This module makes that choice explicit and configurable rather than hard-coding
+one system's convention. ``label`` is the default because it is the field most
+sources populate and the one most likely to be meaningful to whoever recorded
+the data; a GUI that knows better can ask for other fields.
+"""
+
+import typing
+
+import numpy as np
+
+__all__ = ["available_fields", "channel_names"]
+
+
+def available_fields(ch_axis_data: typing.Optional[np.ndarray]) -> typing.List[str]:
+    """Field names present on a structured ``ch`` axis, for building a chooser."""
+    if ch_axis_data is None:
+        return []
+    return list((ch_axis_data.dtype.fields or {}).keys())
+
+
+def _field_text(row_value: typing.Any) -> str:
+    """One field of one channel as display text, or "" if it carries nothing.
+
+    Numeric fields use 0 as their "unset" value -- a Blackrock ``elec`` of 0
+    means no electrode, not electrode zero -- so it is treated as absent. Bytes
+    arrive from numpy ``S`` dtypes and are decoded leniently: a mangled label is
+    still more use than an exception.
+    """
+    if isinstance(row_value, bytes):
+        row_value = row_value.decode("utf8", errors="replace")
+    if isinstance(row_value, np.generic):
+        row_value = row_value.item()
+        if isinstance(row_value, bytes):
+            row_value = row_value.decode("utf8", errors="replace")
+    if isinstance(row_value, (int, float)) and not isinstance(row_value, bool):
+        return "" if row_value == 0 else f"{row_value:g}"
+    return str(row_value).strip()
+
+
+def channel_names(
+    ch_axis_data: typing.Optional[np.ndarray],
+    n_ch: typing.Optional[int] = None,
+    *,
+    fields: typing.Sequence[str] = ("label",),
+    sep: str = "-",
+    fallback: str = "ch{index}",
+) -> typing.List[str]:
+    """Per-channel display names from a structured ``ch`` axis.
+
+    :param ch_axis_data: The axis's structured array, or None if the source
+        provided no ``ch`` axis.
+    :param n_ch: Channel count, used only when ``ch_axis_data`` is None or
+        unstructured. Otherwise the axis's own length governs.
+    :param fields: Field names to join, in order. Fields absent from the dtype
+        are skipped; fields present but empty for a given channel are skipped for
+        that channel only, so a partially-populated column degrades per-row
+        rather than for the whole array.
+    :param sep: Joins the field values, e.g. ``("bank", "elec")`` -> ``"A-1"``.
+    :param fallback: Format string used when no requested field yields anything
+        for a channel. ``{index}`` is the channel's index.
+
+    :return: One name per channel. Never empty strings, so a caller can render
+        the result without further guarding.
+    """
+    if ch_axis_data is None or ch_axis_data.dtype.fields is None:
+        n = int(n_ch or 0) if ch_axis_data is None else int(ch_axis_data.shape[0])
+        return [fallback.format(index=i) for i in range(n)]
+
+    present = [f for f in fields if f in ch_axis_data.dtype.fields]
+    n = int(ch_axis_data.shape[0])
+    if not present:
+        return [fallback.format(index=i) for i in range(n)]
+
+    columns = [ch_axis_data[f] for f in present]
+    names = []
+    for i in range(n):
+        parts = [t for t in (_field_text(col[i]) for col in columns) if t]
+        names.append(sep.join(parts) if parts else fallback.format(index=i))
+    return names

ezmsg_tools-0.5.0/src/ezmsg/tools/perfmon/__init__.py

@@ -0,0 +1,12 @@
+"""Performance monitor: a Dash app over ezmsg's profiler output.
+
+The console script points here rather than at :mod:`.cli` so that a missing
+``perfmon`` extra produces an explanation instead of a traceback -- see
+:mod:`ezmsg.tools._entry`.
+"""
+
+from .._entry import run_cli
+
+
+def main() -> None:
+    run_cli("ezmsg.tools.perfmon.cli", "perfmon")

ezmsg_tools-0.5.0/src/ezmsg/tools/plot/__init__.py

@@ -0,0 +1,56 @@
+"""Putting ezmsg streams onto phosphor plots.
+
+:mod:`.describe` is the pure half -- given dims, axes and attrs, work out what
+is being plotted -- and imports neither Qt nor phosphor, so it is usable from a
+topic subscriber, a shared-memory mirror, or a test with neither.
+:mod:`.shmem_sweep` is the Qt widget built on it, and needs the ``viewer`` or
+``sigmon`` extra.
+
+``ShmemSweepWidget`` is resolved lazily so that importing this package, or
+anything under it, does not pull in Qt. Eagerly importing it here would make
+``from ezmsg.tools.plot.describe import ...`` fail without phosphor installed,
+since importing a submodule runs its parent's ``__init__`` first -- which would
+put a GPU stack behind a module that deliberately has no rendering dependency
+at all.
+"""
+
+import typing
+
+from .describe import (
+    METRIC_KINDS,
+    SWEEP_RENDERABLE_METRICS,
+    MetricSpec,
+    StreamShape,
+    UnsupportedMetricError,
+    describe_axisarray,
+    describe_mirror,
+    flatten_for_plot,
+    metric_axis,
+    require_sweep_renderable,
+)
+
+if typing.TYPE_CHECKING:  # pragma: no cover - import for type checkers only
+    from .shmem_sweep import ShmemSweepWidget
+
+__all__ = [
+    "METRIC_KINDS",
+    "SWEEP_RENDERABLE_METRICS",
+    "MetricSpec",
+    "ShmemSweepWidget",
+    "StreamShape",
+    "UnsupportedMetricError",
+    "describe_axisarray",
+    "describe_mirror",
+    "flatten_for_plot",
+    "metric_axis",
+    "require_sweep_renderable",
+]
+
+
+def __getattr__(name: str) -> typing.Any:
+    """Resolve the Qt widget on first use (PEP 562)."""
+    if name == "ShmemSweepWidget":
+        from .shmem_sweep import ShmemSweepWidget
+
+        return ShmemSweepWidget
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

ezmsg_tools-0.5.0/src/ezmsg/tools/plot/describe.py

@@ -0,0 +1,277 @@
+"""Reading a stream's shape well enough to plot it.
+
+Every consumer that puts ezmsg data on a phosphor widget has to answer the same
+questions -- how many channels, at what rate, what are they called, and is this
+a signal or an envelope -- and each has been answering them slightly
+differently. This module answers them once.
+
+It deliberately does not import phosphor or Qt: the inputs are dims, axes and
+attrs, and the outputs are plain numbers and arrays. That keeps it usable from a
+topic subscriber, from a shared-memory mirror, and from a test with neither.
+"""
+
+from __future__ import annotations
+
+import typing
+
+import numpy as np
+
+from ..chmeta import channel_names
+
+__all__ = [
+    "METRIC_AXIS_CANDIDATES",
+    "METRIC_KINDS",
+    "SWEEP_RENDERABLE_METRICS",
+    "MetricSpec",
+    "StreamShape",
+    "UnsupportedMetricError",
+    "describe_axisarray",
+    "describe_mirror",
+    "flatten_for_plot",
+    "metric_axis",
+    "require_sweep_renderable",
+]
+
+# Axis names an upstream aggregator might use for its per-sample tuple.
+# ezmsg-sigproc's BinnedAggregate calls it "metric" by default but the name is a
+# setting, so recognising a couple of obvious alternatives costs nothing.
+METRIC_AXIS_CANDIDATES = ("metric", "minmax", "bound", "stat")
+
+# Label tuples we recognise, and what to call the thing they describe. Keyed on
+# labels rather than width because width says nothing: (min, max) and
+# (mean, std) are both 2-wide and mean entirely different things, and drawing
+# one as the other is silently wrong rather than visibly broken.
+#
+# Adding a kind here is the cheap half. The expensive half is teaching a
+# renderer to draw it -- see SWEEP_RENDERABLE_METRICS.
+METRIC_KINDS: dict[tuple[str, ...], str] = {
+    ("min", "max"): "minmax",
+    ("mean", "std"): "mean_std",
+    ("mean", "sem"): "mean_sem",
+}
+
+# What a sweep plot can actually draw today.
+#
+# "minmax" maps onto phosphor's envelope input directly: the pair *is* the band,
+# so the existing column reduction (min of mins, max of maxes) is correct.
+#
+# A dispersion pair like "mean_std" needs different drawing -- a semi-transparent
+# band from mean-std to mean+std with an opaque line at the mean -- and
+# different column reduction, since averaging a mean is not the same as taking
+# extremes. Recognised here so it fails with an explanation instead of being
+# drawn as if it were an envelope.
+SWEEP_RENDERABLE_METRICS = frozenset({"minmax"})
+
+
+class MetricSpec(typing.NamedTuple):
+    """A trailing per-sample tuple: what it is called and what it holds."""
+
+    axis: str
+    """Name of the trailing axis."""
+
+    labels: tuple[str, ...]
+    """Its coordinate values, lowercased, in order."""
+
+    kind: str
+    """The entry in :data:`METRIC_KINDS` these labels matched."""
+
+
+class UnsupportedMetricError(NotImplementedError):
+    """A recognised metric axis that no renderer here can draw yet."""
+
+
+class StreamShape(typing.NamedTuple):
+    """What a plot needs to know about an incoming stream."""
+
+    n_channels: int
+    """Channels, excluding any envelope axis."""
+
+    srate: float
+    """Samples per second of the *pushed* stream. For an envelope this is the
+    bucket rate, not the rate before decimation -- which is what a sweep buffer
+    must be sized with, or its ring is longer than the data arriving to fill
+    it."""
+
+    channel_labels: list[str] | None
+    """One name per channel, or None if the stream does not say."""
+
+    metric: MetricSpec | None
+    """The trailing per-sample tuple, if the stream carries one."""
+
+    unit: str | None
+    """The signal's amplitude unit, if it declares one."""
+
+    @property
+    def envelope(self) -> bool:
+        """Whether each sample carries a (min, max) pair -- phosphor's envelope."""
+        return self.metric is not None and self.metric.kind == "minmax"
+
+
+def metric_axis(dims: typing.Sequence[str], axes: typing.Mapping[str, typing.Any]) -> MetricSpec | None:
+    """Describe the trailing per-sample tuple, or None if there is not one.
+
+    Recognised by *labels*, not by name or width. The name only narrows the
+    search; the labels are what distinguish a (min, max) envelope from a
+    (mean, std) dispersion pair, which is the same shape and must not be drawn
+    the same way.
+
+    Returns a spec for any tuple in :data:`METRIC_KINDS`, including ones no
+    renderer here supports yet -- describing a stream is not the same as being
+    able to draw it, and a caller that only wants to know what arrived should
+    not have to catch an exception. See :func:`require_sweep_renderable` for
+    the capability check.
+    """
+    if not dims:
+        return None
+    name = dims[-1]
+    if name not in METRIC_AXIS_CANDIDATES:
+        return None
+    data = _axis_data(axes.get(name))
+    if data is None:
+        return None
+    labels = tuple(str(v).lower() for v in data)
+    kind = METRIC_KINDS.get(labels)
+    return None if kind is None else MetricSpec(axis=name, labels=labels, kind=kind)
+
+
+def require_sweep_renderable(shape: StreamShape) -> None:
+    """Raise if a sweep plot cannot draw this stream's metric axis.
+
+    :raises UnsupportedMetricError: for a recognised metric a sweep cannot draw.
+    """
+    metric = shape.metric
+    if metric is None or metric.kind in SWEEP_RENDERABLE_METRICS:
+        return
+    raise UnsupportedMetricError(
+        f"stream carries a {metric.kind!r} metric axis {metric.labels} on {metric.axis!r}, "
+        f"which a sweep plot cannot draw yet (supported: {sorted(SWEEP_RENDERABLE_METRICS)}). "
+        "Aggregate the stream differently upstream, or add rendering for it."
+    )
+
+
+def _axis_data(axis: typing.Any) -> np.ndarray | None:
+    """Coordinate values of an axis given either as a dict or an ezmsg object."""
+    if axis is None:
+        return None
+    if isinstance(axis, dict):
+        data = axis.get("data")
+    else:
+        data = getattr(axis, "data", None)
+    return None if data is None else np.asarray(data)
+
+
+def _axis_gain(axis: typing.Any) -> float | None:
+    if axis is None:
+        return None
+    gain = axis.get("gain") if isinstance(axis, dict) else getattr(axis, "gain", None)
+    return None if gain in (None, 0) else float(gain)
+
+
+def _describe(
+    dims: typing.Sequence[str],
+    axes: typing.Mapping[str, typing.Any],
+    attrs: typing.Mapping[str, typing.Any],
+    shape: typing.Sequence[int],
+    srate: float | None,
+    *,
+    time_axis: str = "time",
+    label_fields: typing.Sequence[str] = ("label",),
+) -> StreamShape:
+    dims = list(dims)
+    metric = metric_axis(dims, axes)
+    metric_name = metric.axis if metric is not None else None
+
+    # Channel count is everything that is neither time nor the metric tuple.
+    n_channels = 1
+    for name, size in zip(dims, shape):
+        if name in (time_axis, metric_name):
+            continue
+        n_channels *= int(size)
+
+    if srate is None:
+        gain = _axis_gain(axes.get(time_axis))
+        srate = 1.0 / gain if gain else 0.0
+
+    ch_data = _axis_data(axes.get("ch"))
+    labels = None
+    if ch_data is not None and ch_data.dtype.fields is not None:
+        labels = channel_names(ch_data, n_channels, fields=label_fields)
+
+    unit = attrs.get("unit") if attrs else None
+    return StreamShape(
+        n_channels=max(1, n_channels),
+        srate=float(srate or 0.0),
+        channel_labels=labels,
+        metric=metric,
+        unit=None if unit is None else str(unit),
+    )
+
+
+def describe_axisarray(
+    msg: typing.Any,
+    *,
+    time_axis: str = "time",
+    label_fields: typing.Sequence[str] = ("label",),
+) -> StreamShape:
+    """Describe a stream from one of its ``AxisArray`` messages."""
+    return _describe(
+        msg.dims,
+        msg.axes,
+        getattr(msg, "attrs", None) or {},
+        msg.data.shape,
+        None,
+        time_axis=time_axis,
+        label_fields=label_fields,
+    )
+
+
+def describe_mirror(
+    mirror: typing.Any,
+    *,
+    time_axis: str = "time",
+    label_fields: typing.Sequence[str] = ("label",),
+) -> StreamShape | None:
+    """Describe a stream from a connected :class:`EZShmMirror`.
+
+    Returns None until the writer has published both a valid buffer header and
+    its metadata -- the two arrive independently, and a description built from
+    only one of them would be missing either the shape or the names.
+    """
+    meta = mirror.meta
+    if meta is None or not meta.bvalid or meta.ndim < 2:
+        return None
+    axes = mirror.axes
+    if axes is None:
+        return None
+    shape = tuple(int(v) for v in meta.shape[: meta.ndim])
+    # dims and meta.shape describe the same ordering -- the sink records the
+    # order the ring actually holds, not the order the message arrived in.
+    return _describe(
+        list(mirror.dims or []),
+        axes,
+        mirror.attrs or {},
+        shape,
+        float(meta.srate),
+        time_axis=time_axis,
+        label_fields=label_fields,
+    )
+
+
+def flatten_for_plot(data: np.ndarray, shape: StreamShape) -> np.ndarray:
+    """Reshape a block to what a plot's ``push_data`` expects.
+
+    ``(n_samples, n_channels, k)`` when the stream carries a k-wide metric
+    tuple, ``(n_samples, n_channels)`` otherwise, with any other dimensions
+    folded into channels.
+
+    The metric case is the reason this exists. Folding a ``(time, ch, 2)``
+    block into ``(time, ch * 2)`` -- which is what a naive ``reshape`` does --
+    renders as twice as many traces, alternating the two metrics, with every
+    channel label off by a factor of two. It looks like data, so nothing
+    complains.
+    """
+    width = len(shape.metric.labels) if shape.metric is not None else None
+    tail = (shape.n_channels,) if width is None else (shape.n_channels, width)
+    if data.size == 0:
+        return data.reshape((0,) + tail)
+    return data.reshape((data.shape[0],) + tail)