misleep 0.3.0__py3-none-any.whl

misleep/io/base.py

@@ -0,0 +1,174 @@
+# -*- coding: UTF-8 -*-
+"""Input/output module: loading and saving signals and annotations.
+
+The module is organised around two light-weight registries (readers and
+writers) that map file extensions to callables. Third-party code can
+register new formats either programmatically
+
+.. code-block:: python
+
+    from misleep.io.base import register_signal_reader
+    register_signal_reader(".xyz", my_xyz_reader)
+
+or declaratively through the ``misleep.signal_readers`` / ``misleep.signal_writers``
+entry-point groups (see the project's ``pyproject.toml``).
+"""
+
+import importlib.metadata
+from pathlib import Path
+from collections.abc import Callable
+
+from misleep.data import MiData, MiAnnotation  # backward-compatible re-export
+
+__all__ = [
+    "MiData",
+    "MiAnnotation",
+    "register_signal_reader",
+    "register_signal_writer",
+    "load_signal",
+    "write_signal",
+    "available_readers",
+    "available_writers",
+]
+
+#: Built-in readers/writers: extension (lower-case, with dot) -> callable.
+_BUILTIN_READERS: dict[str, Callable] = {}
+_BUILTIN_WRITERS: dict[str, Callable] = {}
+_ENTRYPOINT_READERS: dict[str, Callable] | None = None
+_ENTRYPOINT_WRITERS: dict[str, Callable] | None = None
+
+
+def _normalise_extension(extension: str) -> str:
+    """Return a lower-case extension with a leading dot.
+
+    Entry-point names cannot conveniently be written with a leading dot in
+    every packaging tool, while programmatic registrations traditionally use
+    one.  Normalising both forms fixes third-party readers named ``xyz`` not
+    being found for a ``.xyz`` file.
+    """
+    if not isinstance(extension, str) or not extension.strip():
+        raise ValueError("A non-empty file extension is required")
+    extension = extension.strip().lower()
+    return extension if extension.startswith(".") else f".{extension}"
+
+
+def register_signal_reader(extension: str, func: Callable) -> None:
+    """Register a callable that loads a :class:`MiData` from ``extension`` files.
+
+    Parameters
+    ----------
+    extension : str
+        File extension including the dot, e.g. ``".mat"``. Matching is
+        case-insensitive.
+    func : callable
+        ``func(path: str) -> MiData``.
+    """
+    if not callable(func):
+        raise TypeError("Signal reader must be callable")
+    _BUILTIN_READERS[_normalise_extension(extension)] = func
+
+
+def register_signal_writer(extension: str, func: Callable) -> None:
+    """Register a callable that saves a :class:`MiData` to ``extension`` files.
+
+    Parameters
+    ----------
+    extension : str
+        File extension including the dot, e.g. ``".edf"``.
+    func : callable
+        ``func(signals, channels, sf, time, file_path) -> None``.
+    """
+    if not callable(func):
+        raise TypeError("Signal writer must be callable")
+    _BUILTIN_WRITERS[_normalise_extension(extension)] = func
+
+
+def _load_entry_points(group: str) -> dict[str, Callable]:
+    """Load third-party entry points for a given group (best effort)."""
+    registry: dict[str, Callable] = {}
+    try:
+        eps = importlib.metadata.entry_points()
+        if hasattr(eps, "select"):
+            matches = eps.select(group=group)
+        else:  # pragma: no cover - Python < 3.10
+            matches = eps.get(group, [])
+        for ep in matches:
+            try:
+                func = ep.load()
+                registry[_normalise_extension(ep.name)] = func
+            except Exception:
+                continue
+    except Exception:
+        pass
+    return registry
+
+
+def _all_readers() -> dict[str, callable]:
+    global _ENTRYPOINT_READERS
+    if _ENTRYPOINT_READERS is None:
+        _ENTRYPOINT_READERS = _load_entry_points("misleep.signal_readers")
+    return {**_ENTRYPOINT_READERS, **_BUILTIN_READERS}
+
+
+def _all_writers() -> dict[str, callable]:
+    global _ENTRYPOINT_WRITERS
+    if _ENTRYPOINT_WRITERS is None:
+        _ENTRYPOINT_WRITERS = _load_entry_points("misleep.signal_writers")
+    return {**_ENTRYPOINT_WRITERS, **_BUILTIN_WRITERS}
+
+
+def available_readers() -> list[str]:
+    """List the registered file extensions that can be loaded."""
+    return sorted(_all_readers().keys())
+
+
+def available_writers() -> list[str]:
+    """List the registered file extensions that can be saved."""
+    return sorted(_all_writers().keys())
+
+
+def load_signal(data_path: str | Path):
+    """Load a signal file by dispatching on its extension.
+
+    Parameters
+    ----------
+    data_path : str or Path
+        Path of the file to load (``.mat``, ``.edf`` or any registered
+        extension).
+
+    Returns
+    -------
+    MiData
+        The loaded data.
+    """
+    path = Path(data_path)
+    if not path.is_file():
+        raise FileNotFoundError(f"Signal file not found: {path}")
+    suffix = path.suffix.lower()
+    readers = _all_readers()
+    if suffix not in readers:
+        raise ValueError(
+            f"Unsupported file extension '{suffix}'. "
+            f"Registered readers: {sorted(readers)}"
+        )
+    return readers[suffix](str(data_path))
+
+
+def write_signal(midata, file_path: str | Path) -> None:
+    """Save a :class:`MiData` by dispatching on the target extension.
+
+    Parameters
+    ----------
+    midata : MiData
+        Data to save.
+    file_path : str or Path
+        Destination file (``.mat``, ``.edf`` or any registered extension).
+    """
+    suffix = Path(file_path).suffix.lower()
+    writers = _all_writers()
+    if suffix not in writers:
+        raise ValueError(
+            f"Unsupported file extension '{suffix}'. "
+            f"Registered writers: {sorted(writers)}"
+        )
+    writers[suffix](midata.signals, midata.channels, midata.sf, midata.time, str(file_path))

misleep/io/edf.py

@@ -0,0 +1,109 @@
+# -*- coding: UTF-8 -*-
+"""EDF (European Data Format) file reader/writer.
+
+Uses the ``pyedflib`` package for both reading and writing.
+"""
+
+import datetime
+
+from misleep.data import MiData
+from misleep.io.base import register_signal_reader, register_signal_writer
+from misleep.logger import logger
+
+_TIME_FORMAT = "%Y%m%d-%H:%M:%S"
+
+
+def load_edf(data_path):
+    """Load an EDF/EDF+ file into a :class:`MiData`.
+
+    Parameters
+    ----------
+    data_path : str
+        Path of the ``.edf`` file.
+
+    Returns
+    -------
+    MiData
+        The loaded data.
+    """
+    import pyedflib
+
+    signals, signal_headers, meta = pyedflib.highlevel.read_edf(edf_file=data_path)
+
+    return MiData(
+        signals=signals,
+        channels=[each["label"] for each in signal_headers],
+        sf=[each["sample_frequency"] for each in signal_headers],
+        time=meta["startdate"].strftime(_TIME_FORMAT),
+    )
+
+
+def write_edf(signals, channels, sf, time, edf_file=None):
+    """Write signal data to an EDF file.
+
+    Parameters
+    ----------
+    signals : list of ndarray
+        Signal data, one array per channel.
+    channels : list of str
+        Channel names.
+    sf : list of float
+        Sampling frequencies.
+    time : str
+        Acquisition time in ``YYYYMMDD-HH:MM:SS`` format.
+    edf_file : str, optional
+        Destination path. Defaults to a timestamped file in the current
+        directory.
+
+    Returns
+    -------
+    None
+    """
+    import pyedflib
+
+    if edf_file is None:
+        edf_file = f"./{datetime.datetime.now().strftime('%Y%m%d_%H%M%S')}_saved.edf"
+
+    header = {
+        "technician": "",
+        "recording_additional": "",
+        "patientname": "MiSleep",
+        "patient_additional": "",
+        "patientcode": "",
+        "equipment": "",
+        "admincode": "",
+        "sex": "",
+        "startdate": datetime.datetime.strptime(time, _TIME_FORMAT),
+        "birthdate": "",
+    }
+
+    signal_headers = [
+        {
+            "label": each,
+            "dimension": "uV",
+            "sample_frequency": sf[idx],
+            "physical_max": 10417.0,
+            "physical_min": -10417.0,
+            "digital_max": 32767,
+            "digital_min": -32768,
+            "prefilter": "",
+            "transducer": "",
+        }
+        for idx, each in enumerate(channels)
+    ]
+
+    try:
+        with pyedflib.EdfWriter(edf_file, len(signals)) as edf_writer:
+            edf_writer.setHeader(header)
+            for i, signal in enumerate(signals):
+                edf_writer.setSignalHeader(i, signal_headers[i])
+            edf_writer.writeSamples(signals)
+        logger.info("Data written to %s", edf_file)
+    except Exception as e:
+        logger.error(f"Write data ERROR: {e}")
+
+
+register_signal_reader(".edf", load_edf)
+# pyedflib's high-level reader handles BioSemi BDF/BDF+ as well.
+register_signal_reader(".bdf", load_edf)
+register_signal_writer(".edf", write_edf)

misleep/io/mat.py

@@ -0,0 +1,189 @@
+# -*- coding: UTF-8 -*-
+"""MATLAB ``.mat`` file reader/writer.
+
+Supports all three common MAT variants:
+
+* v5 / v7  -- loaded with :func:`scipy.io.loadmat`
+* v7.3     -- loaded with the pure-python ``mat73`` package
+* python-saved MiSleep files (identified by a ``save = 'python'`` entry)
+
+Writing always produces a v5 ``.mat`` file compatible with MATLAB R14+.
+"""
+
+import datetime
+import re
+
+import numpy as np
+
+from misleep.data import MiData
+from misleep.logger import logger
+from misleep.io.base import register_signal_reader, register_signal_writer
+
+#: Regex for the MiSleep acquisition-time format ``YYYYMMDD-HH:MM:SS``
+_TIME_FORMAT = "%Y%m%d-%H:%M:%S"
+
+
+def _load_scipy(raw_data):
+    """Parse a dict produced by scipy.io.loadmat into a MiData."""
+    names = raw_data.dtype.names
+
+    # Old version misleep data: raw 2-D numeric array without structure
+    if names is None:
+        if raw_data.shape[0] > raw_data.shape[1]:
+            signals = raw_data.T
+        else:
+            signals = raw_data
+        channels = [f"ch{each + 1}" for each in range(signals.shape[0])]
+        sf = [305.0 for _ in range(signals.shape[0])]
+        time = datetime.datetime.now().strftime(_TIME_FORMAT)
+        return MiData(signals=signals, channels=channels, sf=sf, time=time)
+
+    raw_data = raw_data[0][0]
+
+    # Saved by python: channels listed first, then metadata fields
+    if "save" in names:
+        channels = list(names[:-4])
+        sf = [float(each) for each in raw_data["sf"][0]]
+        signals = [raw_data[each][0] for each in channels]
+        time = raw_data["time"][0]
+        return MiData(signals=signals, channels=channels, sf=sf, time=time)
+
+    # Saved by matlab
+    channels = [each for item in raw_data["channels"][0] for each in item]
+    sf = [float(each[0]) for item in raw_data["sf"][0] for each in item]
+    signals = []
+    for each in channels:
+        signal_ = raw_data[each]
+        if signal_.shape[0] > signal_.shape[1]:
+            signals.append(signal_.T[0])
+        if signal_.shape[0] < signal_.shape[1]:
+            signals.append(signal_[0])
+
+    try:
+        time = raw_data["time"][0][0][0]
+        datetime.datetime.strptime(time, _TIME_FORMAT)
+    except (ValueError, TypeError):
+        time = raw_data["time"][0]
+
+    return MiData(signals=signals, channels=channels, sf=sf, time=time)
+
+
+def _load_mat73(raw_data):
+    """Parse a dict produced by mat73.loadmat into a MiData."""
+    try:
+        _ = raw_data["channels"]
+    except (KeyError, TypeError):
+        # Old version misleep data: raw numeric array
+        if raw_data.shape[0] > raw_data.shape[1]:
+            signals = raw_data.T
+        else:
+            signals = raw_data
+        channels = [f"ch{each + 1}" for each in range(signals.shape[0])]
+        sf = [305.0 for _ in range(signals.shape[0])]
+        time = datetime.datetime.now().strftime(_TIME_FORMAT)
+        return MiData(signals=signals, channels=channels, sf=sf, time=time)
+
+    channels = list(raw_data["channels"])
+    sf = [float(each) for each in raw_data["sf"]]
+    time = raw_data["time"][0]
+
+    signals = []
+    for each in channels:
+        signal_ = raw_data[each]
+        if signal_.shape[0] > 1:
+            signals.append(signal_)
+        if signal_.shape[0] == 1:
+            signals.append(signal_.T)
+
+    return MiData(signals=signals, channels=channels, sf=sf, time=time)
+
+
+def load_mat(data_path):
+    """Load a ``.mat`` file into a :class:`MiData`.
+
+    The loader automatically detects the MAT version (v5, v7 or v7.3) and
+    the origin of the file (MATLAB vs. MiSleep/python saved).
+
+    Parameters
+    ----------
+    data_path : str
+        Path of the ``.mat`` file.
+
+    Returns
+    -------
+    MiData or None
+        The loaded data, or ``None`` when the file could not be parsed.
+    """
+    from scipy.io import loadmat as scipy_loadmat
+
+    try:
+        raw_data = list(scipy_loadmat(data_path).values())[-1]
+        return _load_scipy(raw_data)
+    except NotImplementedError:
+        # v7.3 file -> use mat73
+        try:
+            from mat73 import loadmat as mat73_loadmat
+
+            raw_data = list(mat73_loadmat(data_path).values())[-1]
+            return _load_mat73(raw_data)
+        except Exception as e:
+            logger.error(f"Load data ERROR: {e}")
+            return None
+    except Exception as e:
+        logger.error(f"Load data ERROR: {e}")
+        return None
+
+
+def write_mat(signals, channels, sf, time, mat_file=None):
+    """Write signal data to a v5 ``.mat`` file.
+
+    Parameters
+    ----------
+    signals : list of ndarray
+        Signal data, one array per channel.
+    channels : list of str
+        Channel names.
+    sf : list of float
+        Sampling frequencies.
+    time : str
+        Acquisition time in ``YYYYMMDD-HH:MM:SS`` format.
+    mat_file : str, optional
+        Destination path. Defaults to a timestamped file in the current
+        directory.
+
+    Returns
+    -------
+    None
+    """
+    from scipy.io import savemat
+
+    if mat_file is None:
+        mat_file = f"./{datetime.datetime.now().strftime('%Y%m%d_%H%M%S')}_saved.mat"
+
+    mdict = {"data": dict(zip(channels, signals))}
+    mdict["data"]["save"] = "python"
+    mdict["data"]["channels"] = channels
+    mdict["data"]["sf"] = sf
+    mdict["data"]["time"] = time
+
+    savemat(file_name=mat_file, mdict=mdict, format="5", oned_as="row")
+    logger.info("Data written to %s", mat_file)
+
+
+register_signal_reader(".mat", load_mat)
+register_signal_writer(".mat", write_mat)
+
+
+def _legacy_time_to_seconds(time_str: str) -> int:
+    """Convert a MiSleep time string to seconds since the day start."""
+    parts = [int(x) for x in time_str.split("-")[-1].split(":")]
+    return ((parts[0] * 60) + parts[1]) * 60 + parts[2]
+
+
+def get_start_second(acquisition_time_str: str) -> int:
+    """Return the second-of-day of an acquisition time (helper for exports)."""
+    m = re.match(r"(\d{4})(\d{2})(\d{2})-(\d{2}):(\d{2}):(\d{2})", acquisition_time_str)
+    if not m:
+        raise ValueError(f"Invalid acquisition time: {acquisition_time_str!r}")
+    _, _, _, hh, mm, ss = (int(g) for g in m.groups())
+    return hh * 3600 + mm * 60 + ss

misleep/logger.py

@@ -0,0 +1,79 @@
+# -*- coding: UTF-8 -*-
+"""Logging setup for MiSleep.
+
+MiSleep uses a single module-level :data:`logger` instance so that every
+sub-module can simply do ``from misleep.logger import logger`` and log to
+the same destination.
+
+The log is written both to the console (stdout) and to a rotating log file
+stored under the per-user MiSleep data directory (see :func:`get_data_dir`).
+"""
+
+import logging
+import os
+import sys
+from logging.handlers import RotatingFileHandler
+from pathlib import Path
+
+
+def get_data_dir() -> Path:
+    """Return the per-user MiSleep data directory.
+
+    The directory is created on first use. On all platforms it defaults to
+    ``~/.misleep``, which keeps things simple and cross-platform friendly.
+
+    Returns
+    -------
+    Path
+        Absolute path of the data directory.
+    """
+    override = os.environ.get("MISLEEP_DATA_DIR")
+    data_dir = Path(override).expanduser() if override else Path.home() / ".misleep"
+    data_dir.mkdir(parents=True, exist_ok=True)
+    return data_dir
+
+
+def _setup_logger() -> logging.Logger:
+    """Create and configure the MiSleep root logger."""
+    logger = logging.getLogger("misleep")
+    logger.setLevel(logging.INFO)
+    logger.propagate = False
+
+    # Avoid double handlers when the module is reloaded
+    if logger.handlers:
+        return logger
+
+    formatter = logging.Formatter(
+        "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+    )
+
+    # Console handler (skipped when launched with pythonw, where both
+    # stdout and stderr are None)
+    console_stream = sys.stderr if sys.stderr is not None else sys.stdout
+    if console_stream is not None:
+        stream_handler = logging.StreamHandler(console_stream)
+        stream_handler.setLevel(logging.INFO)
+        stream_handler.setFormatter(formatter)
+        logger.addHandler(stream_handler)
+
+    # Rotating file handler under the user data directory
+    try:
+        log_dir = get_data_dir() / "logs"
+        log_dir.mkdir(parents=True, exist_ok=True)
+        file_handler = RotatingFileHandler(
+            log_dir / "misleep.log",
+            maxBytes=5 * 1024 * 1024,
+            backupCount=3,
+            encoding="utf-8",
+        )
+        file_handler.setLevel(logging.INFO)
+        file_handler.setFormatter(formatter)
+        logger.addHandler(file_handler)
+    except OSError:  # pragma: no cover - e.g. read-only home directory
+        pass
+
+    return logger
+
+
+#: The shared logger instance used across the package.
+logger = _setup_logger()

misleep/preprocessing/__init__.py

@@ -0,0 +1,23 @@
+# -*- coding: UTF-8 -*-
+"""Signal preprocessing module.
+
+* :mod:`misleep.preprocessing.filtering` -- filtering (Butterworth, mains noise)
+* :mod:`misleep.preprocessing.artifacts` -- artifact rejection
+* :mod:`misleep.preprocessing.spectral`  -- spectrum / spectrogram / band power
+"""
+
+from .filtering import signal_filter, filter_power_line_noise
+from .artifacts import z_score, reject_artifact
+from .spectral import spectrum, spectrogram, band_power
+from .segment import crop_state_data
+
+__all__ = [
+    "signal_filter",
+    "filter_power_line_noise",
+    "z_score",
+    "reject_artifact",
+    "spectrum",
+    "spectrogram",
+    "band_power",
+    "crop_state_data",
+]

misleep/preprocessing/artifacts.py

@@ -0,0 +1,76 @@
+# -*- coding: UTF-8 -*-
+"""Artifact rejection.
+
+The current implementation rejects 5-second epochs whose standard
+deviation deviates strongly from the average epoch standard deviation
+(:func:`reject_artifact`).
+"""
+
+import numpy as np
+
+
+def z_score(signal):
+    """Standardize a signal: ``(x - mean) / std``.
+
+    Parameters
+    ----------
+    signal : ndarray
+        Signal data.
+
+    Returns
+    -------
+    ndarray
+        Z-scored signal.
+    """
+    lst_mean = np.mean(signal, axis=0)
+    lst_std = np.std(signal, axis=0)
+    normalized_data = (signal - lst_mean) / lst_std
+    return normalized_data
+
+
+def reject_artifact(signal, sf=None, threshold=2):
+    """Reject artifact epochs based on per-epoch standard deviation.
+
+    The signal is split into 5-second epochs; every epoch whose standard
+    deviation is ``threshold`` times larger than the mean epoch standard
+    deviation is removed, and the remaining samples are concatenated.
+
+    Parameters
+    ----------
+    signal : ndarray
+        Signal data.
+    sf : float, optional
+        Sampling frequency. When ``None`` the epoch length defaults to
+        1/5th of the signal.
+    threshold : float
+        Relative standard-deviation threshold. Default is 2.
+
+    Returns
+    -------
+    ndarray
+        The cleaned signal (may be shorter than the input).
+    """
+    signal_z_score = z_score(signal)
+    # get epoch data (5 second windows)
+    if sf is None:
+        sf = signal_z_score.shape[0] / 5
+    signal_z_score = [
+        signal_z_score[int(each): int(each + 5 * sf)]
+        for each in range(0, signal_z_score.shape[0], int(5 * sf))
+    ]
+    signal_SD_lst = [np.std(each) for each in signal_z_score]
+    ave_signal_sd = np.mean(signal_SD_lst)
+    artifacts_idx = []
+
+    for each in signal_SD_lst:
+        if each / ave_signal_sd >= threshold:
+            artifacts_idx.append(0)
+        else:
+            artifacts_idx.append(1)
+
+    artifacts_idx = np.array(artifacts_idx).astype(bool)
+    artifacts_idx = np.repeat(artifacts_idx, int(5 * sf))
+    slice_length = artifacts_idx.shape[0] if artifacts_idx.shape[0] < len(signal) else len(signal)
+    signal = np.array(signal[:slice_length])[artifacts_idx[:slice_length]]
+
+    return signal