nucleuskit-toolkit 2.2.0__py3-none-any.whl

nucleuskit_toolkit/ui/realtime_shimmer_plot.py

@@ -0,0 +1,135 @@
+"""Real-time Shimmer wristband plot (PySide6 + pyqtgraph): IMU stack or single EDA/PPG."""
+
+from __future__ import annotations
+
+import os
+
+os.environ.setdefault("PYQTGRAPH_QT_LIB", "PySide6")
+
+import numpy as np
+import pyqtgraph as pg
+from PySide6.QtWidgets import QComboBox, QHBoxLayout, QLabel, QVBoxLayout, QWidget
+
+from nucleuskit_toolkit.shimmer.constants import ShimmerConstants
+from nucleuskit_toolkit.ui.plot_style import (
+    add_legend,
+    lock_view,
+    pen,
+    plot_colors,
+    set_label,
+    set_title,
+    style_plot,
+    style_view,
+)
+
+# Combo box display string (user-requested exact label)
+SHIMMER_COMBO_LABEL_IMU = "IMU (x,y,z)"
+
+
+class RealtimeShimmerPlot(QWidget):
+    """
+    Scrolls Shimmer streams: combo selects IMU (x,y,z with vertical offset), EDA, or PPG.
+    Y-axis autoscales to visible data.
+    """
+
+    def __init__(self, parent: QWidget | None = None, window_seconds: float = 5.0) -> None:
+        super().__init__(parent)
+        self._fs = float(ShimmerConstants.SAMPLING_RATE)
+        self._buf_len = max(32, int(self._fs * window_seconds))
+        self._imu_offsets = np.array([0.0, 100.0, 200.0], dtype=np.float64)
+
+        self._combo = QComboBox()
+        self._combo.addItems([SHIMMER_COMBO_LABEL_IMU, "EDA", "PPG"])
+        self._combo.currentIndexChanged.connect(self._on_mode_changed)
+
+        top = QHBoxLayout()
+        top.addWidget(QLabel("Display:"))
+        top.addWidget(self._combo, stretch=1)
+
+        self._win = pg.GraphicsLayoutWidget(title="Real-time Shimmer")
+        self._plot = self._win.addPlot()
+        lock_view(self._plot)
+        set_label(self._plot, "bottom", "Time", units="s")
+
+        self._legend = add_legend(self._plot)
+        self._curves_imu = [self._plot.plot(name=axis, antialias=True) for axis in "XYZ"]
+        self._curve_scalar = self._plot.plot(antialias=True)
+
+        self._buf_imu = [np.zeros(self._buf_len) for _ in range(3)]
+        self._buf_scalar = np.zeros(self._buf_len)
+        # Seconds before now of each buffer sample (the newest sample is at 0).
+        self._time = (np.arange(self._buf_len) - (self._buf_len - 1)) / self._fs
+        self.refresh_theme()
+
+        self._plot.enableAutoRange(axis="y", enable=True)
+
+        layout = QVBoxLayout(self)
+        layout.setContentsMargins(0, 0, 0, 0)
+        layout.addLayout(top)
+        layout.addWidget(self._win, stretch=1)
+
+        self._on_mode_changed(self._combo.currentIndex())
+
+    def refresh_theme(self) -> None:
+        """Re-apply the plot colours of the current theme."""
+        c = plot_colors()
+        style_view(self._win)
+        style_plot(self._plot)
+        for curve, color in zip(self._curves_imu, c.xyz):
+            curve.setPen(pen(color, 2))
+        self._curve_scalar.setPen(pen(c.accent, 2))
+
+    def _on_mode_changed(self, index: int) -> None:
+        if index == 0:
+            set_title(self._plot, SHIMMER_COMBO_LABEL_IMU)
+            set_label(self._plot, "left", "IMU (offset stacked)")
+            for c in self._curves_imu:
+                c.setVisible(True)
+            self._curve_scalar.setVisible(False)
+        elif index == 1:
+            set_title(self._plot, "EDA")
+            set_label(self._plot, "left", "EDA")
+            for c in self._curves_imu:
+                c.setVisible(False)
+            self._curve_scalar.setVisible(True)
+        else:
+            set_title(self._plot, "PPG")
+            set_label(self._plot, "left", "PPG")
+            for c in self._curves_imu:
+                c.setVisible(False)
+            self._curve_scalar.setVisible(True)
+        self._legend.setVisible(index == 0)
+        self._autorange_y()
+
+    def _autorange_y(self) -> None:
+        visible = [c for c in self._plot.listDataItems() if c.isVisible()]
+        if visible:
+            self._plot.enableAutoRange(axis="y", enable=True)
+            self._plot.autoRange(items=visible)
+
+    def clear_buffers(self) -> None:
+        for j in range(3):
+            self._buf_imu[j].fill(0.0)
+            self._curves_imu[j].setData(self._time, self._buf_imu[j] + self._imu_offsets[j])
+        self._buf_scalar.fill(0.0)
+        self._curve_scalar.setData(self._time, self._buf_scalar)
+        self._autorange_y()
+
+    def add_sample(self, imu_x: float, imu_y: float, imu_z: float, eda: float, ppg: float) -> None:
+        """Append one sample row (decoded numeric values)."""
+        mode = self._combo.currentIndex()
+
+        if mode == 0:
+            vals = (float(imu_x), float(imu_y), float(imu_z))
+            for j in range(3):
+                buf = self._buf_imu[j]
+                buf[:] = np.roll(buf, -1)
+                buf[-1] = vals[j]
+                self._curves_imu[j].setData(self._time, buf + self._imu_offsets[j])
+        else:
+            buf = self._buf_scalar
+            buf[:] = np.roll(buf, -1)
+            buf[-1] = float(eda if mode == 1 else ppg)
+            self._curve_scalar.setData(self._time, buf)
+
+        self._autorange_y()

nucleuskit_toolkit/ui/resources/__init__.py

@@ -0,0 +1 @@
+"""Static UI resources (images, etc.)."""

nucleuskit_toolkit/ui/resources/branding/__init__.py

@@ -0,0 +1 @@
+"""Branding assets shipped with the package."""

nucleuskit_toolkit/ui/session_inspect.py

@@ -0,0 +1,226 @@
+"""Read-only inspection of a session or dataset folder for the Process page (no Qt imports).
+
+The preflight functions of ``offline_job`` prepare the session folder (``ensure_rawdata_layout`` moves loose
+recording files into ``rawData/``), so they only run when processing starts. The inspection here only reads: it looks
+for the raw files in ``rawData/`` or, before the first run, at the top of the session folder, and reads the first and
+last rows of the recordings to estimate the duration without loading them.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+import numpy as np
+from reak_core.constants import EDA_FILES, EXG_FILENAMES, PPG_FILES
+from reak_core.io.session import RESERVED_DIRS
+from reak_core.io.timestamps import normalise_timestamps_to_seconds
+
+VIDEO_FILENAME = "video.mp4"
+_HEAD_ROWS = 64
+_TAIL_BYTES = 8192
+_EDA_NAMES = tuple(name for name, _ in EDA_FILES)
+_PPG_NAMES = tuple(name for name, _ in PPG_FILES)
+
+
+@dataclass(frozen=True)
+class SessionInfo:
+    path: str
+    name: str
+    duration_s: float | None
+    eeg: bool
+    eda: bool
+    ppg: bool
+    video: bool
+
+    @property
+    def missing(self) -> list[str]:
+        """Parts of a complete Nucleus-Kit recording that are absent."""
+        out = []
+        if not self.eeg:
+            out.append("EEG/fEMG")
+        if not (self.eda or self.ppg):
+            out.append("EDA/PPG")
+        if not self.video:
+            out.append("video")
+        return out
+
+    def modalities_text(self) -> str:
+        parts = []
+        if self.eeg:
+            parts.append("EEG/fEMG")
+        if self.eda and self.ppg:
+            parts.append("EDA/PPG")
+        elif self.eda:
+            parts.append("EDA")
+        elif self.ppg:
+            parts.append("PPG")
+        text = "/".join(parts) if parts else "no signals"
+        return text + (" + video" if self.video else "")
+
+    def summary(self) -> str:
+        """For example ``Session P07, 23 min, EEG/fEMG/EDA/PPG + video``."""
+        parts = (f"Session {self.name}", format_duration(self.duration_s), self.modalities_text())
+        return ", ".join(p for p in parts if p)
+
+
+@dataclass(frozen=True)
+class DatasetInfo:
+    path: str
+    sessions: tuple[SessionInfo, ...]
+
+    @property
+    def incomplete(self) -> list[SessionInfo]:
+        return [s for s in self.sessions if s.missing]
+
+    def summary(self) -> str:
+        """For example ``14 sessions found, 2 incomplete (missing video)``."""
+        n = len(self.sessions)
+        text = f"{n} session{'s' if n != 1 else ''} found"
+        incomplete = self.incomplete
+        if incomplete:
+            reasons: list[str] = []
+            for session in incomplete:
+                for part in session.missing:
+                    if part not in reasons:
+                        reasons.append(part)
+            text += f", {len(incomplete)} incomplete (missing {', '.join(reasons)})"
+        return text
+
+
+def format_duration(seconds: float | None) -> str:
+    if seconds is None or seconds <= 0:
+        return ""
+    if seconds < 60:
+        return f"{seconds:.0f} s"
+    minutes = int(round(seconds / 60))
+    if minutes < 60:
+        return f"{minutes} min"
+    return f"{minutes // 60} h {minutes % 60:02d} min"
+
+
+def _raw_dir(folder: str) -> str:
+    raw = os.path.join(folder, "rawData")
+    return raw if os.path.isdir(raw) else folder
+
+
+def _first_file(directory: str, names: tuple[str, ...]) -> str | None:
+    for name in names:
+        path = os.path.join(directory, name)
+        if os.path.isfile(path):
+            return path
+    return None
+
+
+def _first_value(line: str) -> float | None:
+    try:
+        return float(line.split(",", 1)[0].strip().strip("'\""))
+    except ValueError:
+        return None
+
+
+def file_duration_s(path: str) -> float | None:
+    """Duration of a recording from its first rows and its last row, without loading the whole file."""
+    try:
+        head: list[float] = []
+        with open(path, encoding="utf-8", errors="replace") as fh:
+            for line in fh:
+                value = _first_value(line)
+                if value is not None:
+                    head.append(value)
+                if len(head) >= _HEAD_ROWS:
+                    break
+        if len(head) < 2:
+            return None
+        with open(path, "rb") as fh:
+            fh.seek(0, os.SEEK_END)
+            size = fh.tell()
+            fh.seek(max(0, size - _TAIL_BYTES))
+            lines = fh.read().decode("utf-8", errors="replace").splitlines()
+        if size > _TAIL_BYTES:
+            lines = lines[1:]  # the first line read may be cut
+        last = None
+        for line in reversed(lines):
+            last = _first_value(line)
+            if last is not None:
+                break
+        if last is None:
+            return None
+        seconds = normalise_timestamps_to_seconds(np.asarray(head + [last], dtype=float))
+        duration = float(seconds[-1])
+        return duration if np.isfinite(duration) and duration > 0 else None
+    except OSError:
+        return None
+
+
+def inspect_session(folder: str, *, with_duration: bool = True) -> SessionInfo | None:
+    """What a session folder holds, or ``None`` when it has no Hermes or Shimmer recording. Moves nothing."""
+    folder = os.path.abspath(os.path.expanduser(folder))
+    if not os.path.isdir(folder):
+        return None
+    raw = _raw_dir(folder)
+    exg = _first_file(raw, EXG_FILENAMES)
+    eda = _first_file(raw, _EDA_NAMES)
+    ppg = _first_file(raw, _PPG_NAMES)
+    if not (exg or eda or ppg):
+        return None
+    duration = None
+    if with_duration:
+        durations = [d for d in (file_duration_s(p) for p in dict.fromkeys(p for p in (exg, eda, ppg) if p)) if d]
+        duration = max(durations) if durations else None
+    return SessionInfo(
+        path=folder,
+        name=os.path.basename(os.path.normpath(folder)),
+        duration_s=duration,
+        eeg=exg is not None,
+        eda=eda is not None,
+        ppg=ppg is not None,
+        video=os.path.isfile(os.path.join(raw, VIDEO_FILENAME)),
+    )
+
+
+def inspect_dataset(folder: str) -> DatasetInfo | None:
+    """Sessions found in the direct subfolders of ``folder``, or ``None`` when there is none. Moves nothing."""
+    folder = os.path.abspath(os.path.expanduser(folder))
+    if not os.path.isdir(folder):
+        return None
+    sessions = []
+    try:
+        entries = sorted(os.listdir(folder))
+    except OSError:
+        return None
+    for entry in entries:
+        candidate = os.path.join(folder, entry)
+        if entry in RESERVED_DIRS or not os.path.isdir(candidate):
+            continue
+        info = inspect_session(candidate, with_duration=False)
+        if info is not None:
+            sessions.append(info)
+    return DatasetInfo(folder, tuple(sessions)) if sessions else None
+
+
+def inspect_input(text: str, dataset: bool) -> tuple[SessionInfo | DatasetInfo | None, str | None]:
+    """``(result, error)`` for the Process page; ``(None, None)`` when no path is entered."""
+    text = text.strip()
+    if not text:
+        return None, None
+    path = os.path.abspath(os.path.expanduser(text))
+    if not os.path.isdir(path):
+        return None, "This folder does not exist."
+    if dataset:
+        info = inspect_dataset(path)
+        if info is not None:
+            return info, None
+        if inspect_session(path, with_duration=False) is not None:
+            return None, (
+                "This folder is a single session: choose Single session, or select the folder holding the sessions."
+            )
+        return None, "No sessions found: expected subfolders containing Hermes or Shimmer recordings."
+    session = inspect_session(path)
+    if session is not None:
+        return session, None
+    if inspect_dataset(path) is not None:
+        return None, "This folder holds several sessions: choose Dataset, or select one session folder."
+    return None, (
+        "No recording found: expected Hermes (EEG/fEMG) or Shimmer (EDA/PPG) files in the folder or its rawData/."
+    )