misleep 0.3.0__py3-none-any.whl

misleep/config/__init__.py

@@ -0,0 +1,105 @@
+# -*- coding: UTF-8 -*-
+"""Configuration handling for MiSleep.
+
+MiSleep is configured through an INI file with two sections:
+
+* ``[gui]``  -- GUI behaviour (state map, state colors, markers, ...)
+* ``[spec]`` -- spectral analysis defaults (window length, nfft, smoothing)
+
+A default configuration is bundled with the package under
+``misleep/config/default_config.ini``. On first run a *user* configuration
+file is created at ``~/.misleep/misleep_config.ini`` and any user setting
+overrides the bundled default, so package upgrades never wipe personal
+settings.
+"""
+
+import configparser
+import shutil
+from pathlib import Path
+
+from misleep.logger import get_data_dir, logger
+
+#: Name of the per-user configuration file.
+USER_CONFIG_NAME = "misleep_config.ini"
+
+
+def default_config_path() -> Path:
+    """Return the path of the bundled default configuration file."""
+    import importlib.resources
+
+    return Path(str(importlib.resources.files(__name__).joinpath("default_config.ini")))
+
+
+def user_config_path() -> Path:
+    """Return the path of the per-user configuration file."""
+    return get_data_dir() / USER_CONFIG_NAME
+
+
+def _ensure_user_config() -> Path:
+    """Create the per-user configuration file on first use and return it."""
+    path = user_config_path()
+    if not path.exists():
+        try:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy(default_config_path(), path)
+            logger.info("Created user configuration at %s", path)
+        except OSError as exc:  # pragma: no cover
+            logger.warning("Could not create user config at %s: %s", path, exc)
+    return path
+
+
+def load_config(path: str | Path | None = None) -> configparser.ConfigParser:
+    """Load the effective MiSleep configuration.
+
+    The bundled defaults are loaded first and then overridden by the
+    per-user configuration file, so any key the user did not customize
+    keeps its default value.
+
+    Parameters
+    ----------
+    path : str | Path | None
+        Explicit path to a configuration file. When ``None`` (default),
+        the per-user configuration is used on top of the bundled default.
+
+    Returns
+    -------
+    configparser.ConfigParser
+        The merged configuration.
+    """
+    config = configparser.ConfigParser()
+    config.read(default_config_path(), encoding="utf-8")
+
+    default_user_path = path is None
+    if default_user_path:
+        path = _ensure_user_config()
+    if Path(path).exists():
+        config.read(path, encoding="utf-8")
+    elif not default_user_path:
+        logger.warning("Configuration file %s does not exist, using defaults", path)
+
+    return config
+
+
+def save_config(config: configparser.ConfigParser, path: str | Path | None = None) -> Path:
+    """Persist a configuration back to disk.
+
+    Parameters
+    ----------
+    config : configparser.ConfigParser
+        The configuration to save.
+    path : str | Path | None
+        Destination file. Defaults to the per-user configuration file.
+
+    Returns
+    -------
+    Path
+        The file the configuration was written to.
+    """
+    if path is None:
+        path = _ensure_user_config()
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "w", encoding="utf-8") as f:
+        config.write(f)
+    logger.info("Configuration saved to %s", path)
+    return path

misleep/config/default_config.ini

@@ -0,0 +1,38 @@
+# ============================================================
+# MiSleep default configuration
+# ============================================================
+# This file ships with the package and is merged with the user
+# configuration stored at:
+#   Windows : %USERPROFILE%\.misleep\misleep_config.ini
+#   macOS   : ~/.misleep/misleep_config.ini
+#   Linux   : ~/.misleep/misleep_config.ini
+#
+# The GUI offers "Config" under the Help menu to open the USER
+# configuration file with your system editor. Copy any section
+# you want to customize from here and restart MiSleep.
+#
+# DO NOT edit this bundled file directly -- your changes would be
+# overwritten on the next package update.
+
+[gui]
+version = v0.3.0
+updatetime = 2026/08/18
+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"}
+statecolor = {"1": "orange", "2": "skyblue", "3": "red", "4": "#ececec"}
+startendcolor = {"NREM": "orange", "REM": "skyblue", "Wake": "red"}
+statecolorbgalpha = 0.1
+hypnogramstatealpha = 0.55
+markerlinecolor = "red"
+startendlinecolor = "blue"
+freq_range = [0.5, 30]
+openpath = .
+theme = light
+color_tone = black
+spectrogram_cmap = jet
+
+[spec]
+win_length_sec = 10.0
+nfft_sec = 10.0
+gaussian_sigma = 1.0

misleep/data/__init__.py

@@ -0,0 +1,13 @@
+# -*- coding: UTF-8 -*-
+"""Data model module.
+
+This module contains the in-memory data containers used across MiSleep:
+
+* :class:`misleep.data.midata.MiData` -- raw signal recordings
+* :class:`misleep.data.annotation.MiAnnotation` -- sleep scoring/annotation
+"""
+
+from .midata import MiData
+from .annotation import MiAnnotation
+
+__all__ = ["MiData", "MiAnnotation"]

misleep/data/annotation.py

@@ -0,0 +1,114 @@
+# -*- coding: UTF-8 -*-
+"""Core annotation container :class:`MiAnnotation`.
+
+A :class:`MiAnnotation` stores everything the user scores for one
+recording:
+
+* the per-second **sleep state** sequence (1 = NREM, 2 = REM, 3 = Wake,
+  4 = Init by default, but fully configurable through ``state_map``),
+* single time-point **markers** (e.g. ``[30.5, 'injection']``),
+* **start-end** events (e.g. ``[1, 20, 'spindle']``).
+"""
+
+
+class MiAnnotation:
+    """MiSleep annotation class.
+
+    Default state mapping::
+
+        1 -- NREM
+        2 -- REM
+        3 -- Wake
+        4 -- Init
+
+    Parameters
+    ----------
+    sleep_state : list
+        Per-second sleep state labels. The length of ``sleep_state`` equals
+        the total duration (in seconds) of the recording. Every element must
+        be a key of ``state_map``.
+    marker : list, optional
+        Single time-point events, e.g. ``[[1, 'injection'], [30, 'injection']]``.
+    start_end : list, optional
+        Start-end events, e.g. ``[[1, 20, 'spindle'], [30, 50, 'SWA']]``.
+    state_map : dict, optional
+        Mapping from state code to its meaning. Defaults to
+        ``{1: 'NREM', 2: 'REM', 3: 'Wake', 4: 'Init'}``.
+    """
+
+    def __init__(self, sleep_state, marker=None, start_end=None, state_map=None):
+        if not isinstance(sleep_state, list):
+            raise TypeError(f"'sleep_state' should be a list, got {type(sleep_state)}")
+
+        if state_map is None:
+            self._state_map = {1: "NREM", 2: "REM", 3: "Wake", 4: "Init"}
+        else:
+            self._state_map = state_map
+
+        for each in sleep_state:
+            if each not in self._state_map.keys():
+                raise ValueError(f"Content {each} in the 'sleep_state' does not exist in {self._state_map}")
+
+        self._sleep_state = sleep_state
+        self._anno_length = len(sleep_state)
+
+        if marker is not None:
+            if not isinstance(marker, list):
+                raise TypeError(f"'marker' should be a list, got {type(marker)}")
+        self._marker = marker if marker is not None else []
+
+        if start_end is not None:
+            if not isinstance(start_end, list):
+                raise TypeError(f"'start_end' should be a list, got {type(start_end)}")
+        self._start_end = start_end if start_end is not None else []
+
+    # ------------------------------------------------------------------
+    # Properties
+    # ------------------------------------------------------------------
+    @property
+    def sleep_state(self, time_period=None):
+        """Per-second sleep state labels.
+
+        Parameters
+        ----------
+        time_period : list of two ints, optional
+            Crop the returned sequence to ``[start, end]`` seconds.
+        """
+        if time_period is None:
+            return self._sleep_state
+        return self._sleep_state[time_period[0]: time_period[1]]
+
+    @property
+    def marker(self, time_period=None):
+        """Marker events, optionally restricted to a time window."""
+        if time_period is None:
+            return self._marker
+        return [each for each in self._marker if time_period[0] <= each[0] <= time_period[1]]
+
+    @property
+    def start_end(self, time_period=None):
+        """Start-end events, optionally restricted to a time window."""
+        if time_period is None:
+            return self._start_end
+        return [each for each in self._start_end if time_period[0] <= each[0] and each[1] <= time_period[1]]
+
+    @property
+    def anno_length(self):
+        """Length of the annotation in seconds."""
+        return self._anno_length
+
+    @property
+    def state_map(self):
+        """Mapping from state code to state name."""
+        return self._state_map
+
+    @property
+    def state_names(self):
+        """Sorted list of state names used in this annotation."""
+        return [self._state_map[k] for k in sorted(self._state_map)]
+
+    def __repr__(self):
+        return (f"MiAnnotation(length={self._anno_length}s, "
+                f"markers={len(self._marker)}, "
+                f"start_end={len(self._start_end)}, "
+                f"state_map={self._state_map})")

misleep/data/midata.py

@@ -0,0 +1,387 @@
+# -*- coding: UTF-8 -*-
+"""Core signal data container :class:`MiData`.
+
+``MiData`` is the primary in-memory representation of a polysomnographic
+recording inside MiSleep. It stores, for every channel:
+
+* the signal samples (1-D numpy arrays),
+* the channel name,
+* the sampling frequency of the channel.
+
+It also stores the recording start time and an optional free-text
+description, and exposes a small set of in-place or copy-on-write
+operations (filter, differential, crop, pick, rename, add, delete).
+
+All channels of a :class:`MiData` object share the same integer duration
+in seconds (the minimum integer duration across channels); longer
+channels are truncated accordingly.
+"""
+
+import math
+
+import numpy as np
+
+
+def _unique_name(name, existing):
+    """Return ``name`` or the next available ``name_N`` variant."""
+    if name not in existing:
+        return name
+    index = 1
+    while f"{name}_{index}" in existing:
+        index += 1
+    return f"{name}_{index}"
+
+
+class MiData:
+    """MiSleep signal data format.
+
+    Parameters
+    ----------
+    signals : list or ndarray
+        List of 1-D arrays, one per channel.
+    channels : list of str
+        Channel name for each signal channel, e.g. ``['EEG_F', 'EEG_P', 'EMG']``.
+    sf : list of float
+        Sampling frequency of each signal channel, e.g. ``[256., 256., 256.]``.
+    time : str
+        Recording start time in string format, e.g. ``'20240228-19:45:00'``.
+    describe : str, optional
+        Free-text description of the data. Defaults to ``''``.
+    """
+
+    def __init__(self, signals, channels, sf, time, describe=None):
+        self._validate_inputs(signals, channels, sf, describe)
+
+        self._describe = "" if describe is None else describe
+        self._time = time
+
+        # Avoid duplicated channel names: append "_1", "_2", ...
+        temp_channel = []
+        for each in channels:
+            temp_channel.append(_unique_name(each, temp_channel))
+        channels = temp_channel
+
+        # All channels are truncated to the same integer duration in seconds
+        temp_duration = [math.floor(len(signals[idx]) / each) for idx, each in enumerate(sf)]
+        self._duration = min(temp_duration)
+
+        self._signals = [signals[idx][: int(self._duration * each)] for idx, each in enumerate(sf)]
+        self._channels = channels
+        self._n_channels = len(self._channels)
+        self._sf = sf
+
+    # ------------------------------------------------------------------
+    # Validation helpers
+    # ------------------------------------------------------------------
+    @staticmethod
+    def _validate_inputs(signals, channels, sf, describe):
+        if not isinstance(signals, (list, np.ndarray)):
+            raise TypeError(f"Signals should be a list of arrays or ndarray, got {type(signals)}")
+        if len(signals) == 0:
+            raise ValueError("At least one signal channel is required")
+        for each in signals:
+            if not isinstance(each, np.ndarray):
+                raise TypeError(f"Signals should be a list of arrays or ndarray, got {type(each)}")
+            if each.ndim != 1:
+                raise ValueError(f"Each signal must be a 1-D array, got shape {each.shape}")
+
+        if not isinstance(channels, list):
+            raise TypeError(f"Channels should be a list of strings, got {type(channels)}")
+        if len(channels) != len(signals):
+            raise ValueError(
+                f"Length of channels ({len(channels)}) does not match the length of signals ({len(signals)})"
+            )
+        for each in channels:
+            if not isinstance(each, str):
+                raise TypeError(f"Channels should be a list of strings, got {type(each)}")
+
+        if not isinstance(sf, list):
+            raise TypeError(f"Sample frequency should be a list of int or float, got {type(sf)}")
+        if len(sf) != len(signals):
+            raise ValueError(
+                f"Length of sample frequency ({len(sf)}) does not match the length of signals ({len(signals)})"
+            )
+        for each in sf:
+            if not isinstance(each, (int, float)):
+                raise TypeError(f"Sample frequency should be a list of int or float, got {type(each)}")
+            if not math.isfinite(each) or each <= 0:
+                raise ValueError(f"Sample frequencies must be finite and positive, got {each}")
+
+        if describe is not None and not isinstance(describe, str):
+            raise TypeError(f"'describe' should be a string for data description, got {type(describe)}")
+
+    # ------------------------------------------------------------------
+    # In-place operations
+    # ------------------------------------------------------------------
+    def differential(self, chan1=None, chan2=None):
+        """Compute the differential signal ``chan1 - chan2`` and add it as a new channel.
+
+        Parameters
+        ----------
+        chan1 : str
+            Name of the first channel.
+        chan2 : str
+            Name of the second channel.
+        """
+        if chan1 is None or chan2 is None:
+            raise ValueError("Specify two channel names to do differential")
+
+        if chan1 not in self._channels:
+            raise IndexError(f"{chan1} is not in the channel names ({self._channels})")
+        if chan2 not in self._channels:
+            raise IndexError(f"{chan2} is not in the channel names ({self._channels})")
+
+        chan1_idx = self._channels.index(chan1)
+        chan2_idx = self._channels.index(chan2)
+        if self._signals[chan1_idx].shape[0] != self._signals[chan2_idx].shape[0]:
+            raise ValueError(
+                f"Channel {chan1} and channel {chan2} have different lengths to do differential "
+                f"({self._signals[chan1_idx].shape} and {self._signals[chan2_idx].shape})"
+            )
+        self.add(self._signals[chan1_idx] - self._signals[chan2_idx],
+                 f"{chan1}_{chan2}_DIFF", self._sf[chan1_idx])
+
+    def rename_channels(self, mapping):
+        """Rename channels in place with a mapping.
+
+        Parameters
+        ----------
+        mapping : dict
+            Map old channel name to a new channel name.
+        """
+        if not isinstance(mapping, dict):
+            raise TypeError(f"Mapping should be a dict which maps old channel name to a new one, got {type(mapping)}")
+
+        for each in mapping.keys():
+            if each not in self._channels:
+                raise IndexError(f"{each} is not in the signal channel list ({self._channels})")
+            new_name = mapping[each]
+            if not isinstance(new_name, str) or not new_name.strip():
+                raise ValueError("New channel names must be non-empty strings")
+            index = self._channels.index(each)
+            existing = self._channels[:index] + self._channels[index + 1:]
+            self._channels[index] = _unique_name(new_name.strip(), existing)
+
+    def filter(self, chans=None, btype="bandpass", low=0.5, high=30):
+        """Filter the specified channel(s) and add the result as new channel(s).
+
+        Parameters
+        ----------
+        chans : list of str
+            Channels to be filtered.
+        btype : {'bandpass', 'lowpass', 'highpass', 'bandstop'}, optional
+            The type of filter. Default is ``'bandpass'``.
+        low : float
+            Lower cutoff frequency in Hz.
+        high : float
+            Higher cutoff frequency in Hz.
+        """
+        from misleep.preprocessing.filtering import signal_filter
+
+        if chans is None or not isinstance(chans, list):
+            raise TypeError(f"'chans' should be a list of channel names, got {type(chans)}")
+
+        for chan in chans:
+            if chan in self._channels:
+                chan_idx = self._channels.index(chan)
+                filtered_data, fname = signal_filter(
+                    data=self._signals[chan_idx],
+                    btype=btype, sf=self._sf[chan_idx], low=low, high=high)
+                self.add(filtered_data, f"{chan}_{fname}", self._sf[chan_idx])
+            else:
+                raise IndexError(f"{chan} channel is not in the signal channels ({self._channels})")
+
+    def add(self, signal, channel, sf):
+        """Add a new signal channel to the data.
+
+        Parameters
+        ----------
+        signal : ndarray
+            The signal samples.
+        channel : str
+            Channel name.
+        sf : float
+            Sampling frequency of the new channel.
+        """
+        if not isinstance(signal, np.ndarray) or signal.ndim != 1 or signal.size == 0:
+            raise ValueError("The new signal must be a non-empty 1-D numpy array")
+        if not isinstance(channel, str):
+            raise TypeError(f"Channel name should be a string, got {type(channel)}")
+        if not isinstance(sf, (int, float)) or not math.isfinite(sf) or sf <= 0:
+            raise TypeError(f"Sample frequency should be a float, got {type(sf)}")
+
+        _duration = math.floor(len(signal) / sf)
+        if _duration < self._duration:
+            raise ValueError(
+                f"The new signal is shorter ({_duration}s) than the existing data "
+                f"({self._duration}s)")
+
+        channel = _unique_name(channel, self.channels)
+
+        self._signals.append(signal[:int(self._duration * sf)])
+        self._channels.append(channel)
+        self._n_channels = len(self._channels)
+        self._sf.append(sf)
+
+    def delete(self, channel=None):
+        """Delete a channel by name.
+
+        Parameters
+        ----------
+        channel : str
+            Name of the channel to delete.
+        """
+        if not isinstance(channel, str):
+            raise TypeError(f"Channel name should be a string, got {type(channel)}")
+        if channel not in self._channels:
+            raise IndexError(f"Channel name {channel} is not in the signal channels ({self._channels})")
+        if len(self._channels) == 1:
+            raise ValueError(f"Channel {channel} is the last channel of signal data, you can't delete it")
+        chan_idx = self._channels.index(channel)
+        self._signals.pop(chan_idx)
+        self._channels.pop(chan_idx)
+        self._sf.pop(chan_idx)
+        self._n_channels = len(self._channels)
+
+    # ------------------------------------------------------------------
+    # Copy-on-write operations
+    # ------------------------------------------------------------------
+    def crop(self, time_period):
+        """Return a new :class:`MiData` cropped to ``[start, end]`` seconds.
+
+        Parameters
+        ----------
+        time_period : list of two ints
+            Start and end second of the crop.
+
+        Returns
+        -------
+        MiData
+            Cropped data (all channels).
+        """
+        if not isinstance(time_period, list) or len(time_period) != 2:
+            raise TypeError(f"'time_period' should be a list of two positive integers, got {time_period}")
+
+        if time_period[0] < 0 or time_period[1] < 0 or \
+                not isinstance(time_period[0], int) or not isinstance(time_period[1], int):
+            raise TypeError(
+                f"'time_period' should be a list of two positive integers, "
+                f"got {type(time_period[0])} and {type(time_period[1])}")
+
+        if time_period[0] >= time_period[1]:
+            raise ValueError(
+                f"End time (got {time_period[1]}) of 'time_period' should be larger than start time (got {time_period[0]})")
+
+        start, end = time_period
+        end = min(end, self._duration)
+
+        signals = [self.signals[idx][int(start * each): int(end * each)]
+                   for idx, each in enumerate(self.sf)]
+        return MiData(signals=signals, channels=self.channels, sf=self.sf,
+                      time=self.time, describe=self.describe)
+
+    def pick_chs(self, ch_names):
+        """Return a new :class:`MiData` with only the requested channels.
+
+        Parameters
+        ----------
+        ch_names : list of str
+            Channels to keep.
+
+        Returns
+        -------
+        MiData
+            Data restricted to the selected channels.
+        """
+        if ch_names is None or ch_names == []:
+            ch_names = self.channels
+
+        if not isinstance(ch_names, list):
+            raise TypeError(f"'ch_names' should be a list, got {type(ch_names)}")
+
+        signals, sf, channels = [], [], []
+        for chan in ch_names:
+            if chan in self.channels:
+                chan_idx = self.channels.index(chan)
+                signals.append(self.signals[chan_idx])
+                sf.append(self.sf[chan_idx])
+                channels.append(chan)
+            else:
+                raise IndexError(f"{chan} channel is not in the signal channels ({self.channels})")
+
+        return MiData(signals=signals, channels=channels, sf=sf,
+                      time=self.time, describe=self.describe)
+
+    def reorder_channels(self, new_order):
+        """Reorder the channels in place.
+
+        Parameters
+        ----------
+        new_order : list of str
+            Channel names in the desired order (must be a permutation of
+            the current channel names).
+        """
+        if sorted(new_order) != sorted(self._channels):
+            raise ValueError(
+                f"'new_order' must be a permutation of the channel names "
+                f"({self._channels}), got {new_order}")
+
+        order_idx = [self._channels.index(name) for name in new_order]
+        self._signals = [self._signals[i] for i in order_idx]
+        self._channels = [self._channels[i] for i in order_idx]
+        self._sf = [self._sf[i] for i in order_idx]
+        self._n_channels = len(self._channels)
+
+    # ------------------------------------------------------------------
+    # Properties
+    # ------------------------------------------------------------------
+    @property
+    def duration(self):
+        """Duration of the recording in integer seconds."""
+        return self._duration
+
+    @property
+    def signals(self):
+        """List of signal arrays (one per channel)."""
+        return self._signals
+
+    @property
+    def channels(self, idx=None):
+        """Channel names (all, or the one at index ``idx``)."""
+        if idx is None:
+            return self._channels
+        if idx >= self._n_channels:
+            raise IndexError(f"Index {idx} can't be larger than the signal channels number {self._n_channels}")
+        return self._channels[idx]
+
+    @property
+    def sf(self, idx=None):
+        """Sampling frequencies (all, or the one at index ``idx``)."""
+        if idx is None:
+            return self._sf
+        if idx >= self._n_channels:
+            raise IndexError(f"Index {idx} can't be larger than the signal channels number {self._n_channels}")
+        return self._sf[idx]
+
+    @property
+    def time(self):
+        """Recording start time as a string."""
+        return self._time
+
+    @property
+    def describe(self):
+        """Free-text description of the data."""
+        return self._describe
+
+    @property
+    def n_channels(self):
+        """Number of channels."""
+        return self._n_channels
+
+    def get_channel_index(self, channel):
+        """Return the index of a channel by name."""
+        return self._channels.index(channel)
+
+    def __repr__(self):
+        summary = ", ".join(f"{ch}@{sf:.0f}Hz" for ch, sf in zip(self._channels, self._sf))
+        return f"MiData(duration={self._duration}s, channels=[{summary}], time='{self._time}')"

misleep/gui/__init__.py

@@ -0,0 +1,23 @@
+# -*- coding: UTF-8 -*-
+"""PySide6 graphical user interface for MiSleep.
+
+Launch the GUI with::
+
+    python -m misleep
+
+or from Python::
+
+    from misleep.gui import show
+    show()
+
+The GUI is built on **PySide6** (Qt6), which works on Windows, macOS and
+Linux. Before importing anything from this module, make sure PySide6 is
+installed (``pip install 'misleep[gui]'``) and that the ``QT_API``
+environment variable is set to ``pyside6`` for matplotlib integration
+(handled automatically by :mod:`misleep.gui.app`).
+"""
+
+from misleep.gui import resources as _resources  # noqa: F401  (register Qt resources)
+from .app import main, show
+
+__all__ = ["main", "show"]