misleep 0.3.0__tar.gz → 0.3.2__tar.gz

{misleep-0.3.0 → misleep-0.3.2}/CHANGELOG.md

@@ -5,6 +5,74 @@ All notable changes to MiSleep are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.2] — 2026-08-24
+
+### Fixed
+
+- **Filtering broke on fractional sampling frequencies**: `MiData.add()` (used
+  by `MiData.filter()`) recomputed the duration with
+  `math.floor(len(signal) / sf)` from a signal that had already been
+  truncated to `int(duration * sf)` samples. When `sf` is a decimal (e.g.
+  `99.9927` Hz), that came out one second short, so filtering either raised a
+  spurious "new signal is shorter" error or produced a channel whose length /
+  duration did not match the original signal, which then failed the signal /
+  label consistency checks in the GUI. The check now compares sample counts
+  against `int(duration * sf)` directly, so filtering preserves the sample
+  count and duration for any positive `sf` while still rejecting genuinely
+  short signals.
+
+## [0.3.1] — 2026-08-18
+
+### Added
+
+- **Epoch / BIDS annotation import**: the CSV/TSV annotation loader now
+  understands `onset` / `duration` / `stage` (BIDS `events.tsv`),
+  headerless `[epoch index, epoch second, epoch label]` and
+  `[epoch second, epoch label]` tables (with or without a header row), on
+  top of the existing `start`/`end`/`state` and per-second layouts.
+
+### Changed
+
+- **Faster startup**: the one-time warm-up (scipy imports, matplotlib font
+  cache) now runs in a background thread so the window appears instantly,
+  and the redundant `SetProcessDpiAwareness` calls were removed (Qt6
+  manages its own per-monitor DPI context - the old call produced an
+  "Access is denied" warning).
+- **Hypnogram layout**: the initial hypnogram strip is shorter (drag the
+  splitter to resize), the figure now fills the whole strip even without
+  the confidence chart, and the axis margins were widened so the time
+  tick labels are always visible (no overflow below the panel).
+- **Auto-staging defaults**: the low-confidence rate now defaults to
+  **0.8** and the HMM temperature to **0.1**. The HMM decoding is
+  confidence-based: the LightGBM probabilities drive the emissions and
+  the learned transition matrix only constrains state transitions.
+
+- **LightGBM auto-staging rewritten on the benchmark models**
+  (`benchmark_models.pkl`, 6 channel-combo models). Every mouse age and
+  EEG site uses the same model; the dialog lets the user pick the EEG
+  channel, an optional EMG channel and an optional ACC channel (ACC
+  requires EMG), the EEG site, the age group, the HMM temperature and the
+  **low-confidence rate**. Predictions are decoded with a learned 3-state
+  HMM and cover the **whole recording** (the first window and the tail
+  take the nearest epoch). The per-epoch **confidence** is attached to the
+  annotation and drawn as a separate line chart below the hypnogram with a
+  dashed threshold line - static, so page flips stay fast and label edits
+  never recompute it. The *cover current* checkbox only fills the INIT
+  states, keeping already-scored labels.
+
+- **Python support**: the package now supports **Python 3.8 through 3.14**
+  (`requires-python >= 3.8`); annotations and resource loading were made
+  3.8-compatible, and the GUI extra pins the last 3.8-compatible PySide6
+  line on older Pythons.
+- **Dependencies**: the packaging metadata now reflects the complete set
+  of runtime prerequisites, and **PySide6 moved into the base
+  dependencies** - a plain `pip install misleep` installs the GUI and all
+  core packages automatically (no separate PySide6 install needed).
+  LightGBM / torch remain optional extras.
+- **Documentation**: bright theme with a light header (readable
+  black-on-transparent logo), full-width MiSleep banner on the home page,
+  single GUI preview screenshot.
+
 ## [0.3.0] — 2026-08-18
 
 ### Fixed

{misleep-0.3.0/src/misleep.egg-info → misleep-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.1
 Name: misleep
-Version: 0.3.0
+Version: 0.3.2
 Summary: MiSleep: Mice sleep EEG/EMG visualization, scoring, and analysis
 Author-email: Xueqiang Wang <swang9194@gmail.com>
 Maintainer-email: Xueqiang Wang <swang9194@gmail.com>
@@ -43,6 +43,7 @@ Classifier: Intended Audience :: Science/Research
 Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
 Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
@@ -53,7 +54,7 @@ Classifier: License :: OSI Approved :: BSD License
 Classifier: Operating System :: Microsoft :: Windows
 Classifier: Operating System :: POSIX :: Linux
 Classifier: Operating System :: MacOS
-Requires-Python: >=3.9
+Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: numpy>=1.20
@@ -65,19 +66,18 @@ Requires-Dist: mat73>=0.60
 Requires-Dist: openpyxl>=3.0
 Requires-Dist: joblib>=1.1
 Requires-Dist: scikit-learn>=1.0
+Requires-Dist: PySide6>=6.6; python_version >= "3.9"
+Requires-Dist: PySide6<6.6,>=6.4; python_version < "3.9"
 Provides-Extra: gui
-Requires-Dist: PySide6>=6.6; extra == "gui"
 Provides-Extra: analysis
 Requires-Dist: lightgbm>=3.3; extra == "analysis"
 Provides-Extra: transformer
 Requires-Dist: torch>=2.0; extra == "transformer"
 Provides-Extra: full
-Requires-Dist: PySide6>=6.6; extra == "full"
 Requires-Dist: lightgbm>=3.3; extra == "full"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
-Dynamic: license-file
 
 # MiSleep
 
@@ -122,19 +122,17 @@ The name *MiSleep* comes from "**Mi**ce **Sleep**" and sounds like
 ## Installation
 
 ```bash
-# Core package (data, I/O, preprocessing, analysis, visualization)
+# Base install - includes everything (data, I/O, preprocessing, analysis,
+# visualization AND the PySide6 GUI)
 pip install misleep
 
-# With the PySide6 GUI (recommended for most users)
-pip install "misleep[gui]"
-
-# With everything, including the LightGBM auto-staging model
+# With the LightGBM auto-staging model as well
 pip install "misleep[full]"
 
 # For development / contributing
 git clone https://github.com/BryanWang0702/MiSleep.git
 cd misleepv3
-pip install -e ".[gui,analysis,dev]"
+pip install -e ".[analysis,dev]"
 ```
 
 > **Note on PyTorch:** the causal-transformer auto-staging model requires

{misleep-0.3.0 → misleep-0.3.2}/README.md

@@ -41,19 +41,17 @@ The name *MiSleep* comes from "**Mi**ce **Sleep**" and sounds like
 ## Installation
 
 ```bash
-# Core package (data, I/O, preprocessing, analysis, visualization)
+# Base install - includes everything (data, I/O, preprocessing, analysis,
+# visualization AND the PySide6 GUI)
 pip install misleep
 
-# With the PySide6 GUI (recommended for most users)
-pip install "misleep[gui]"
-
-# With everything, including the LightGBM auto-staging model
+# With the LightGBM auto-staging model as well
 pip install "misleep[full]"
 
 # For development / contributing
 git clone https://github.com/BryanWang0702/MiSleep.git
 cd misleepv3
-pip install -e ".[gui,analysis,dev]"
+pip install -e ".[analysis,dev]"
 ```
 
 > **Note on PyTorch:** the causal-transformer auto-staging model requires

{misleep-0.3.0 → misleep-0.3.2}/docs/api_reference.md

@@ -119,12 +119,15 @@ Default state map: `{1: 'NREM', 2: 'REM', 3: 'Wake', 4: 'Init'}`.
 
 ### Automatic staging
 
-* `auto_stage_gbm(EEG, EMG, label, sf, EEG_channel='F', mouse_age='adult')`
-  → list of per-second states — LightGBM auto staging.
+* `auto_stage_gbm(EEG, EMG=None, label, sf, EEG_channel='F', mouse_age='adult',
+  ACC=None, return_probs=False)` → list of per-second states (plus per-epoch
+  confidence when `return_probs=True`) — LightGBM auto staging with the
+  benchmark models (all ages use the same model; EMG and ACC are optional,
+  ACC requires EMG).
 * `result_constraints(pred_prob)` → list — smooth/constrain raw model
   probabilities into state labels.
 * `model_path(mouse_age='adult', EEG_channel='F')` → Path — packaged
-  LightGBM model path.
+  benchmark model path.
 * `misleep.analysis.transformer.auto_stage_llm(EEG, EMG, label=None,
   config=None)` → list — transformer auto staging (requires torch).
 * `misleep.analysis.transformer.AutoStageConfig` — dataclass of

{misleep-0.3.0 → misleep-0.3.2}/docs/config_file.md

@@ -23,8 +23,8 @@ wipe your personal settings. Open the user file from the GUI via
 
 | key | default | meaning |
 |-----|---------|---------|
-| `version` | `v0.3.0` | displayed in the About dialog |
-| `updatetime` | `2025/01/01` | displayed in the About dialog |
+| `version` | `v0.3.2` | displayed in the About dialog |
+| `updatetime` | `2026/08/24` | displayed in the About dialog |
 | `marker` | `['half_signal', 'first REM', ...]` | marker label list (label picker) |
 | `startend` | `['high_theta', 'REM', ...]` | start-end label list (label picker) |
 | `statemap` | `{"1": "NREM", "2": "REM", "3": "Wake", "4": "INIT", ...}` | state code -> name mapping (JSON) |
@@ -48,8 +48,8 @@ wipe your personal settings. Open the user file from the GUI via
 
 ```ini
 [gui]
-version = v0.3.0
-updatetime = 2025/01/01
+version = v0.3.2
+updatetime = 2026/08/24
 marker = ['half_signal', 'first REM', 'WindEEG', 'W-R', 'maker']
 startend = ['high_theta', 'REM', 'Wake', 'Spindle', 'SWA', 'start end label', 'start end label']
 statemap = {"1": "NREM", "2": "REM", "3": "Wake", "4": "INIT", "5": "IS", "6": "MicroArousal"}

{misleep-0.3.0 → misleep-0.3.2}/docs/getting_started.md

@@ -14,19 +14,20 @@
 ## Installation
 
 ```bash
-# From PyPI
+# From PyPI - the base install already includes the PySide6 GUI and all
+# core dependencies
 pip install misleep
 
-# With the GUI
-pip install "misleep[gui]"
-
-# Everything for a full experience (GUI + LightGBM auto staging)
+# Everything for a full experience (adds LightGBM auto staging)
 pip install "misleep[full]"
 
+# Causal-transformer auto staging (PyTorch, not on all platforms)
+pip install "misleep[transformer]"
+
 # Development install from the repository
 git clone https://github.com/BryanWang0702/MiSleep.git
 cd misleepv3
-pip install -e ".[gui,analysis,dev]"
+pip install -e ".[analysis,dev]"
 ```
 
 > **Note for Apple Silicon (macOS):** `torch` and `lightgbm` ship official
@@ -56,9 +57,7 @@ on the right. A light and a dark theme are available
 (`Ctrl+Shift+T` to toggle, or Settings → General → Theme /
 Color scheme).
 
-![MiSleep main window (light theme)](imgs/gui/main_light.png)
-
-![MiSleep main window (dark theme)](imgs/gui/main_dark.png)
+![MiSleep main window](imgs/gui/main_light.png)
 
 ### Opening files from the command line
 

{misleep-0.3.0 → misleep-0.3.2}/docs/index.md

@@ -1,5 +1,9 @@
 # MiSleep documentation
 
+<p align="center">
+  <img src="imgs/entire_logo.png" alt="MiSleep" width="80%"/>
+</p>
+
 MiSleep is an open-source Python toolbox for **mice sleep EEG/EMG**
 visualization, scoring, and analysis. This documentation covers both the
 desktop GUI and the Python library.

{misleep-0.3.0 → misleep-0.3.2}/pyproject.toml

@@ -4,10 +4,10 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "misleep"
-version = "0.3.0"
+version = "0.3.2"
 description = "MiSleep: Mice sleep EEG/EMG visualization, scoring, and analysis"
 readme = "README.md"
-requires-python = ">=3.9"
+requires-python = ">=3.8"
 license = { file = "LICENSE" }
 authors = [
     { name = "Xueqiang Wang", email = "swang9194@gmail.com" },
@@ -25,6 +25,7 @@ classifiers = [
     "Topic :: Scientific/Engineering :: Bio-Informatics",
     "Topic :: Scientific/Engineering :: Medical Science Apps.",
     "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
     "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
@@ -46,13 +47,16 @@ dependencies = [
     "openpyxl>=3.0",
     "joblib>=1.1",
     "scikit-learn>=1.0",
+    # GUI toolkit - part of the base install so `pip install misleep` just
+    # works (PySide6 >= 6.6 needs Python 3.9+; 3.8 gets the 6.5 line)
+    "PySide6>=6.6; python_version >= '3.9'",
+    "PySide6>=6.4,<6.6; python_version < '3.9'",
 ]
 
 [project.optional-dependencies]
-# PySide6-based graphical user interface
-gui = [
-    "PySide6>=6.6",
-]
+# The GUI (PySide6) is now part of the base dependencies; this empty extra
+# is kept so existing `misleep[gui]` install commands keep working.
+gui = []
 # Automatic sleep staging with the LightGBM model
 analysis = [
     "lightgbm>=3.3",
@@ -63,7 +67,6 @@ transformer = [
 ]
 # Everything needed for a full MiSleep experience
 full = [
-    "PySide6>=6.6",
     "lightgbm>=3.3",
 ]
 # Tooling for developers / contributors
@@ -81,6 +84,10 @@ Documentation = "https://bryanwang.cn/MiSleep/"
 [project.scripts]
 misleep = "misleep.gui.app:main"
 
+# Windowless launcher (no console window) - creates misleepw.exe on Windows
+[project.gui-scripts]
+misleepw = "misleep.gui.app:main"
+
 [project.entry-points."misleep.signal_readers"]
 mat = "misleep.io.mat:load_mat"
 edf = "misleep.io.edf:load_edf"

{misleep-0.3.0 → misleep-0.3.2}/src/misleep/__init__.py

@@ -22,7 +22,7 @@ works without PySide6; import ``misleep.gui`` explicitly when needed.
 from importlib import import_module
 
 __author__ = "Xueqiang Wang <swang9194@gmail.com>"
-__version__ = "0.3.0"
+__version__ = "0.3.2"
 
 # Importing ``misleep`` used to import scipy, pandas, sklearn and matplotlib
 # immediately.  The GUI necessarily imports some of those later, but making

misleep-0.3.2/src/misleep/_compat.py

@@ -0,0 +1,36 @@
+# -*- coding: UTF-8 -*-
+"""Compatibility helpers so MiSleep runs on Python 3.8 through 3.14.
+
+Only packaging/resource helpers live here; there is no application logic.
+"""
+
+from pathlib import Path
+
+
+def resource_dir(package: str) -> Path:
+    """Return the filesystem directory of a package (3.8-compatible)."""
+    try:
+        from importlib.resources import files
+
+        return Path(str(files(package)))
+    except (ImportError, AttributeError):  # pragma: no cover - Python 3.8
+        import importlib
+
+        return Path(str(importlib.import_module(package).__path__[0]))
+
+
+def resource_path(package: str, name: str) -> Path:
+    """Return the filesystem path of a package resource file.
+
+    ``importlib.resources.files`` (Python 3.9+) is preferred; on Python
+    3.8 the older ``importlib.resources.path`` is used instead.
+    """
+    try:
+        from importlib.resources import files
+
+        return Path(str(files(package).joinpath(name)))
+    except (ImportError, AttributeError):  # pragma: no cover - Python 3.8
+        import importlib.resources
+
+        with importlib.resources.path(package, name) as path:
+            return Path(str(path))

misleep-0.3.2/src/misleep/analysis/auto_stage.py

@@ -0,0 +1,176 @@
+# -*- coding: UTF-8 -*-
+"""Automatic sleep staging with the benchmark LightGBM models.
+
+The packaged ``benchmark_models.pkl`` contains six LightGBM classifiers
+(one per channel combo: EEG site x optional EMG x optional ACC), each
+combined with a per-recording z-score normalisation, a learned 3-state HMM
+and class priors. **Every mouse age and EEG site use the same model file**;
+the age / site arguments are kept only for API compatibility.
+
+The pipeline (adapted from the rodent-autostage benchmark):
+
+1. feature extraction on 5 s epochs (STFT band powers + time-domain
+   features + EEG-EMG coherence, W = 10 s window at 1 s stride),
+2. per-recording z-score normalisation,
+3. LightGBM class probabilities,
+4. HMM / Viterbi decoding with a softmax temperature,
+5. physiologically constrained smoothing (Init -> Wake, REM never after
+   Wake, single-epoch flip removal),
+6. per-second expansion of the per-epoch states.
+
+Besides the per-second labels, the per-epoch probability of the predicted
+state is returned (the *confidence* used by the GUI to mark low-confidence
+regions in the hypnogram).
+"""
+
+from __future__ import annotations
+
+import copy
+from pathlib import Path
+
+import numpy as np
+
+from misleep._compat import resource_dir
+from misleep.logger import logger
+
+
+def _model_dir() -> Path:
+    """Return the directory containing the packaged LightGBM models."""
+    return resource_dir("misleep.analysis.models")
+
+
+def model_path(mouse_age="adult", EEG_channel="F") -> Path:
+    """Return the path of the packaged benchmark models.
+
+    A single model file serves every mouse age and EEG site, so
+    ``mouse_age`` and ``EEG_channel`` are accepted for API compatibility
+    only.
+
+    Parameters
+    ----------
+    mouse_age : str
+        Accepted for API compatibility (ignored).
+    EEG_channel : str
+        Accepted for API compatibility (ignored).
+
+    Returns
+    -------
+    Path
+    """
+    return _model_dir() / "benchmark_models.pkl"
+
+
+def result_constraints(pred_prob):
+    """Post-process raw model probabilities into smooth state labels.
+
+    Applies the following constraints:
+
+    1. A REM probability below 0.15 is overridden.
+    2. REM directly after Wake is set to NREM.
+    3. State 4 (Init) is set to Wake.
+    4. A single epoch between two identical states takes that state.
+
+    Parameters
+    ----------
+    pred_prob : ndarray
+        Model output probabilities, shape ``(n_windows, n_classes)``.
+
+    Returns
+    -------
+    list of int
+        Per-window predicted state codes (1-indexed).
+    """
+    pred_prob = copy.deepcopy(pred_prob)
+    pred_label = [each + 1 for each in np.argmax(pred_prob, axis=1)]
+    pred_label = [2 if each[1] > 0.15 else pred_label[idx]
+                  for idx, each in enumerate(pred_prob)]
+
+    for idx in range(1, len(pred_label) - 1):
+        label_ = pred_label[idx]
+
+        if label_ == 4:
+            pred_label[idx] = 3
+        if label_ == 3 and pred_label[idx + 1] == 2:  # REM after Wake
+            pred_label[idx + 1] = 1
+        if pred_label[idx - 1] == pred_label[idx + 1] and pred_label[idx] != 3:
+            pred_label[idx] = pred_label[idx - 1]
+
+    return pred_label
+
+
+def auto_stage_gbm(EEG, EMG, label, sf, EEG_channel="F", mouse_age="adult",
+                   ACC=None, return_probs=False, temperature=0.1):
+    """Auto-stage a recording with the benchmark LightGBM models.
+
+    All mouse ages use the same model; ``mouse_age`` is kept for API
+    compatibility. The channel combo (EEG site x EMG x ACC) selects which
+    of the six benchmark models is used - ACC requires EMG.
+
+    Parameters
+    ----------
+    EEG : ndarray
+        EEG signal.
+    EMG : ndarray or None
+        EMG signal (optional; pass ``None`` to run EEG-only).
+    label : list
+        Reference labels (kept for API compatibility; not used by the model).
+    sf : float
+        Sampling frequency of the signals.
+    EEG_channel : {'F', 'P'}
+        EEG electrode site (frontal or parietal). Default is ``'F'``.
+    mouse_age : str
+        Accepted for API compatibility (ignored - all ages use the same
+        model).
+    ACC : ndarray or None
+        ACC signal (optional; requires ``EMG``).
+    return_probs : bool
+        Also return the per-epoch confidence (probability of the predicted
+        state) as a numpy array.
+    temperature : float
+        HMM softmax temperature (lower sharpens the transition structure).
+
+    Returns
+    -------
+    list of int, or (list of int, ndarray) when ``return_probs`` is True.
+        Per-second predicted state codes (1 = NREM, 2 = REM, 3 = Wake),
+        plus the per-epoch confidence when requested. The prediction may
+        be a few seconds shorter than the recording (window drop).
+    """
+    from misleep.analysis.autostage import benchmark as _bm
+
+    if EEG is None or len(np.asarray(EEG)) / sf < _bm.W + _bm.EPOCH_S:
+        raise ValueError(
+            "Signal too short for auto staging (need at least "
+            f"{int(_bm.W + _bm.EPOCH_S)} s).")
+    if ACC is not None and EMG is None:
+        raise ValueError("ACC auto-staging requires an EMG channel as well.")
+
+    use_emg = EMG is not None
+    use_acc = ACC is not None
+    combo = _bm.model_combo(EEG_channel, use_emg, use_acc)
+
+    models = _bm.load_models()
+    if combo not in models:
+        # ACC without EMG is not part of the model set - fall back to the
+        # EEG+EMG (or EEG-only) model.
+        if use_acc and use_emg:
+            raise ValueError(
+                f"No model for combo '{combo}' in the packaged models.")
+        combo = _bm.model_combo(EEG_channel, use_emg, False)
+
+    sig_map = {"eeg": EEG, "emg": EMG, "acc": ACC}
+    res = _bm.predict_model(models[combo], sig_map, sf,
+                            site=EEG_channel, temperature=temperature)
+
+    # Full-length per-second labels (every second gets a label; the first
+    # W seconds and the tail take the nearest epoch) + per-epoch confidence
+    # (one value per 5 s epoch - small data).
+    pred_second = [int(x) for x in res["label_sec"]]
+    conf_epoch = np.asarray(res["prob"], dtype=float)
+    logger.info(
+        "Auto staging finished (combo=%s, %d epochs, %d seconds)",
+        combo, len(res["label"]), len(pred_second))
+
+    if return_probs:
+        return pred_second, conf_epoch
+    return pred_second

misleep-0.3.2/src/misleep/analysis/autostage/__init__.py

@@ -0,0 +1,24 @@
+# -*- coding: UTF-8 -*-
+"""Benchmark auto-staging pipeline for MiSleep (LightGBM + HMM).
+
+Vendored and adapted from the rodent-autostage benchmark models; see
+:mod:`misleep.analysis.autostage.benchmark` for the public API used by the
+LightGBM auto-staging dialog.
+"""
+
+from misleep.analysis.autostage.benchmark import (  # noqa: F401
+    EPOCH_S,
+    STRIDE,
+    W,
+    extract_recording,
+    load_models,
+    model_combo,
+    models_path,
+    predict_model,
+)
+
+__all__ = [
+    "EPOCH_S", "STRIDE", "W",
+    "extract_recording", "load_models", "model_combo", "models_path",
+    "predict_model",
+]