misleep 0.3.0__py3-none-any.whl

misleep/__init__.py

@@ -0,0 +1,111 @@
+# -*- coding: UTF-8 -*-
+"""MiSleep: mice sleep EEG/EMG visualization, scoring, and analysis.
+
+MiSleep is organized into a small number of modules:
+
+=================  ======================================================
+Module             Purpose
+=================  ======================================================
+``misleep.data``   in-memory data containers (MiData, MiAnnotation)
+``misleep.io``     load/save signals (``.mat``, ``.edf``) and annotations
+``misleep.preprocessing`` filtering, artifact rejection, spectral analysis
+``misleep.analysis`` event detection and automatic sleep staging
+``misleep.viz``    matplotlib plotting (signals, spectra, hypnograms)
+``misleep.gui``    PySide6 desktop application (``python -m misleep``)
+``misleep.utils``  small helpers
+=================  ======================================================
+
+The GUI is intentionally *not* imported here so that the core package
+works without PySide6; import ``misleep.gui`` explicitly when needed.
+"""
+
+from importlib import import_module
+
+__author__ = "Xueqiang Wang <swang9194@gmail.com>"
+__version__ = "0.3.0"
+
+# Importing ``misleep`` used to import scipy, pandas, sklearn and matplotlib
+# immediately.  The GUI necessarily imports some of those later, but making
+# the public convenience API lazy removes a large block of duplicate startup
+# work and keeps lightweight uses such as ``misleep.__version__`` instant.
+_LAZY_EXPORTS = {
+    "MiData": ("misleep.data", "MiData"),
+    "MiAnnotation": ("misleep.data", "MiAnnotation"),
+    **{name: ("misleep.io", name) for name in (
+        "load_mat", "write_mat", "load_edf", "write_edf", "load_npy",
+        "load_npz", "load_csv", "load_tsv", "write_npz",
+        "load_misleep_anno", "save_misleep_anno", "load_bio_anno",
+        "transfer_result", "load_annotation", "load_json_anno",
+        "load_table_anno", "load_signal", "write_signal")},
+    **{name: ("misleep.preprocessing", name) for name in (
+        "signal_filter", "filter_power_line_noise", "z_score",
+        "reject_artifact", "spectrum", "spectrogram", "band_power",
+        "crop_state_data")},
+    **{name: ("misleep.analysis", name) for name in (
+        "SWA_detection", "spindle_detection", "artifact_detection",
+        "auto_stage_gbm", "result_constraints")},
+    **{name: ("misleep.viz", name) for name in (
+        "plot_signals", "plot_spectrum", "plot_spectrogram", "plot_hypno")},
+    "utils": ("misleep.utils", None),
+}
+
+
+def __getattr__(name):
+    """Load public convenience exports only when first accessed."""
+    try:
+        module_name, attribute = _LAZY_EXPORTS[name]
+    except KeyError as exc:
+        raise AttributeError(f"module 'misleep' has no attribute {name!r}") from exc
+    module = import_module(module_name)
+    value = module if attribute is None else getattr(module, attribute)
+    globals()[name] = value
+    return value
+
+
+def __dir__():
+    return sorted(set(globals()) | set(_LAZY_EXPORTS))
+
+__all__ = [
+    # data
+    "MiData",
+    "MiAnnotation",
+    # io
+    "load_mat",
+    "write_mat",
+    "load_edf",
+    "write_edf",
+    "load_npy",
+    "load_npz",
+    "load_csv",
+    "load_tsv",
+    "write_npz",
+    "load_misleep_anno",
+    "save_misleep_anno",
+    "load_bio_anno",
+    "transfer_result",
+    "load_annotation",
+    "load_json_anno",
+    "load_table_anno",
+    "load_signal",
+    "write_signal",
+    # preprocessing
+    "signal_filter",
+    "filter_power_line_noise",
+    "z_score",
+    "reject_artifact",
+    "spectrum",
+    "spectrogram",
+    "band_power",
+    "crop_state_data",
+    # analysis
+    "SWA_detection",
+    "spindle_detection",
+    "artifact_detection",
+    "auto_stage_gbm",
+    "result_constraints",
+    # viz
+    "plot_signals",
+    "plot_spectrum",
+    "plot_spectrogram",
+    "plot_hypno",
+]

misleep/__main__.py

@@ -0,0 +1,16 @@
+# -*- coding: UTF-8 -*-
+"""Entry point for ``python -m misleep [data] [anno]`` (launches the GUI)."""
+
+import sys
+
+
+def main():
+    from misleep.gui.app import show
+    from misleep.gui.app import _parse_args
+
+    data_path, anno_path = _parse_args(sys.argv[1:])
+    show(data_path=data_path, anno_path=anno_path)
+
+
+if __name__ == "__main__":
+    main()

misleep/analysis/__init__.py

@@ -0,0 +1,23 @@
+# -*- coding: UTF-8 -*-
+"""Analysis module: event detection and automatic sleep staging.
+
+* :mod:`misleep.analysis.detection`     -- SWA / spindle / artifact detection
+* :mod:`misleep.analysis.features`      -- auto-staging feature extraction
+* :mod:`misleep.analysis.auto_stage`    -- LightGBM auto staging
+* :mod:`misleep.analysis.transformer`   -- Causal-transformer auto staging (PyTorch)
+
+The transformer sub-module is only imported on demand because it requires
+PyTorch, which is not available on every platform.
+"""
+
+from .detection import SWA_detection, spindle_detection, artifact_detection
+from .auto_stage import auto_stage_gbm, result_constraints, model_path
+
+__all__ = [
+    "SWA_detection",
+    "spindle_detection",
+    "artifact_detection",
+    "auto_stage_gbm",
+    "result_constraints",
+    "model_path",
+]

misleep/analysis/auto_stage.py

@@ -0,0 +1,158 @@
+# -*- coding: UTF-8 -*-
+"""Automatic sleep staging with a LightGBM classifier.
+
+The model is trained on 20-second windows (stride 5 s) of EEG and EMG
+features; every window label is then expanded back to per-second labels.
+"""
+
+import copy
+import warnings
+from importlib.resources import files
+from pathlib import Path
+
+import numpy as np
+
+from misleep.analysis.features import get_data_features, split_window_data
+from misleep.logger import logger
+
+
+def _model_dir() -> Path:
+    """Return the directory containing the packaged LightGBM models."""
+    ref = files("misleep.analysis.models")
+    return Path(str(ref)) if ref.is_dir() else ref
+
+
+def model_path(mouse_age="adult", EEG_channel="F") -> Path:
+    """Return the path of a packaged LightGBM model file.
+
+    Parameters
+    ----------
+    mouse_age : {'adult', 'ado', 'P30'}
+        Age category of the model.
+    EEG_channel : {'F', 'P'}
+        EEG electrode site (frontal or parietal).
+
+    Returns
+    -------
+    Path
+    """
+    return _model_dir() / f"{mouse_age}_EEG_{EEG_channel}_lightgbm.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"):
+    """Auto-stage an EEG/EMG recording with the LightGBM model.
+
+    Parameters
+    ----------
+    EEG : ndarray
+        EEG signal.
+    EMG : ndarray
+        EMG signal.
+    label : list
+        Reference labels (kept for API compatibility; not used by the model).
+    sf : float
+        Sampling frequency of both signals.
+    EEG_channel : {'F', 'P'}
+        EEG electrode site (frontal or parietal). Default is ``'F'``.
+    mouse_age : {'adult', 'ado', 'P30'}
+        Model age category: adult > P56, ``ado`` is P30~P56, ``P30`` is < P30.
+
+    Returns
+    -------
+    list of int
+        Per-second predicted state codes (1 = NREM, 2 = REM, 3 = Wake).
+        May be slightly shorter than the input for the last few seconds.
+    """
+    try:
+        import joblib
+    except ImportError as e:  # pragma: no cover
+        raise ImportError(
+            "Auto staging requires the 'joblib' package. "
+            "Install it with: pip install joblib") from e
+
+    EEG_windows = split_window_data(EEG, sf, state=4)
+    EMG_windows = split_window_data(EMG, sf, state=4)
+    if not EEG_windows or not EMG_windows:
+        raise ValueError("Signals are too short for auto staging (need >= 20 s).")
+
+    window_feature_df = get_data_features(EEG_windows, sf, data_format="EEG")
+    emg_feature_df = get_data_features(EMG_windows, sf, data_format="EMG")
+    # Combine and keep only feature columns (drop 'label')
+    window_feature_df = window_feature_df.join(emg_feature_df, lsuffix="_eeg", rsuffix="_emg")
+    window_feature_df = window_feature_df.filter(like="E")
+
+    model_file = model_path(mouse_age=mouse_age, EEG_channel=EEG_channel)
+    if not model_file.exists():
+        raise FileNotFoundError(
+            f"Model file not found: {model_file}. "
+            f"Make sure the 'misleep' package data is installed "
+            f"(pip install misleep) or provide the model manually.")
+
+    # The bundled LightGBM estimators were trained with scikit-learn 1.3.2.
+    # Their LabelEncoder is only retained as fitted metadata and is not used
+    # by predict_proba(), but newer sklearn versions otherwise print a long
+    # compatibility warning on every run.  Limit the suppression narrowly to
+    # that known packaged object; all other model-loading warnings remain.
+    try:
+        from sklearn.exceptions import InconsistentVersionWarning
+    except ImportError:  # pragma: no cover - sklearn is a LightGBM dependency
+        InconsistentVersionWarning = Warning
+    with warnings.catch_warnings():
+        warnings.filterwarnings(
+            "ignore",
+            message="Setting the shape on a NumPy array has been deprecated.*",
+            category=DeprecationWarning,
+            module=r"joblib\.numpy_pickle",
+        )
+        warnings.filterwarnings(
+            "ignore",
+            message="Trying to unpickle estimator LabelEncoder from version 1.3.2.*",
+            category=InconsistentVersionWarning,
+        )
+        gbm_model = joblib.load(model_file)
+
+    pred_prob = gbm_model.predict_proba(window_feature_df,
+                                        num_iteration=gbm_model.best_iteration_)
+    pred_label = result_constraints(pred_prob)
+    pred_label = [item for each in pred_label for item in [each] * 5]
+    logger.info("Auto staging finished (%d windows, %d seconds)",
+                len(pred_prob), len(pred_label))
+    return pred_label

misleep/analysis/detection.py

@@ -0,0 +1,198 @@
+# -*- coding: UTF-8 -*-
+"""Event detection: slow-wave activity (SWA), sleep spindles, artifacts.
+
+All detectors operate on 1-D signal arrays plus a sampling frequency and
+return either a list of detections or a pandas DataFrame (``df=True``).
+"""
+
+import numpy as np
+import pandas as pd
+from scipy.signal import find_peaks
+
+from misleep.preprocessing.filtering import signal_filter
+from misleep.preprocessing.spectral import spectrogram
+from misleep.utils.annotation import lst2group
+
+
+def SWA_detection(signal, sf, freq_band=[0.5, 4], amp_threshold=(75,), df=False, start_time_sec=0):
+    """Slow-wave activity (SWA) detection.
+
+    The signal is band-pass filtered to ``freq_band``; waves are detected
+    from trough to peak using relative amplitude thresholds and validated
+    by their instantaneous frequency.
+
+    Parameters
+    ----------
+    signal : ndarray
+        Signal to analyze.
+    sf : float
+        Sampling frequency.
+    freq_band : list of two floats
+        Frequency band of the slow wave, e.g. ``[0.5, 4]`` Hz.
+    amp_threshold : tuple
+        Minimum (and optionally maximum) absolute amplitude of the peaks.
+    df : bool
+        Whether to return a pandas DataFrame instead of a list.
+    start_time_sec : float
+        Offset (in seconds) added to all detection times -- useful when
+        processing segments of a longer recording.
+
+    Returns
+    -------
+    list or pandas.DataFrame or None
+        Detections (``None`` when nothing was found).
+    """
+    band_data, _ = signal_filter(signal, sf, btype="bandpass",
+                                 low=freq_band[0], high=freq_band[1])
+
+    # Find peaks and zero-crossings
+    pos_peak_idx, _ = find_peaks(band_data, amp_threshold)
+    neg_peak_idx, _ = find_peaks(-1 * band_data, amp_threshold)
+    zero_crossing = np.where(np.diff(np.signbit(band_data), axis=0))[0]
+
+    # Find zero -> neg_peak -> zero -> pos_peak -> zero pattern
+    negative_peaks_hold = []
+    positive_peaks_hold = []
+    zero_crossing_hold = []
+    for neg_idx in neg_peak_idx:
+        for zero_idx in zero_crossing:
+            if zero_idx > neg_idx:
+                for pos_idx in pos_peak_idx:
+                    if pos_idx > zero_idx and zero_idx not in zero_crossing_hold:
+                        if True not in (band_data[zero_idx + 1: pos_idx] <= 0) and \
+                                True not in (band_data[neg_idx: zero_idx] >= 0):
+                            negative_peaks_hold.append(neg_idx)
+                            positive_peaks_hold.append(pos_idx)
+                            zero_crossing_hold.append(zero_idx)
+                        break
+                break
+
+    if negative_peaks_hold == []:
+        return None
+
+    # zero before the negative peak
+    start_zero_cross_hold = zero_crossing[:-1][np.diff(
+        np.searchsorted(negative_peaks_hold, zero_crossing)).astype(bool)]
+
+    if zero_crossing[-1] < positive_peaks_hold[-1]:
+        zero_crossing = np.append(zero_crossing, positive_peaks_hold[-1] + 1)
+    end_zero_cross_hold = zero_crossing[np.searchsorted(zero_crossing, positive_peaks_hold)]
+
+    df_lst = []
+    for idx, start_zero in enumerate(start_zero_cross_hold):
+        start_time = start_zero / sf + start_time_sec
+        end_time = end_zero_cross_hold[idx] / sf + start_time_sec
+        total_duration = end_time - start_time
+        frequency = 1 / total_duration
+        if frequency > freq_band[1] or frequency < freq_band[0]:
+            continue
+
+        middle_cross_time = zero_crossing_hold[idx] / sf + start_time_sec
+        time_pos_peak = positive_peaks_hold[idx] / sf + start_time_sec
+        val_pos_peak = band_data[positive_peaks_hold[idx]]
+        time_neg_peak = negative_peaks_hold[idx] / sf + start_time_sec
+        val_neg_peak = band_data[negative_peaks_hold[idx]]
+
+        peak_to_peak = val_pos_peak - val_neg_peak
+        slope = peak_to_peak / (time_pos_peak - time_neg_peak)
+
+        df_lst.append([start_time, time_neg_peak, middle_cross_time, time_pos_peak,
+                       end_time, total_duration, val_neg_peak, val_pos_peak,
+                       peak_to_peak, slope, frequency])
+
+    if df:
+        return pd.DataFrame(df_lst, columns=["StartTime", "NegTime", "MiddleTime",
+                                             "PosTime", "EndTime", "Duration", "NegPeak",
+                                             "PosPeak", "PTP", "Slope", "Frequency"])
+    return df_lst
+
+
+def spindle_detection(signal, sf, freq_band=[10, 15], start_time_sec=0,
+                      std_thresh=None, duration_thresh=None):
+    """Sleep spindle detection based on spectrogram power.
+
+    The signal's spectrogram power within ``freq_band`` is computed; a
+    spindle is defined as a period where the power exceeds
+    ``mean + std_thresh * std`` (for detection) and
+    ``mean + duration_thresh * std`` (for duration) and lasts at least
+    0.5 seconds.
+
+    Parameters
+    ----------
+    signal : ndarray
+        Signal to analyze.
+    sf : float
+        Sampling frequency.
+    freq_band : list of two floats
+        Frequency band of the spindle, e.g. ``[10, 15]`` Hz.
+    start_time_sec : float
+        Offset added to the detection times.
+    std_thresh : float, optional
+        Std multiplier for the detection threshold (default 2).
+    duration_thresh : float, optional
+        Std multiplier for the duration threshold (default 1.5).
+
+    Returns
+    -------
+    list or None
+        List of ``[start, end]`` (in seconds) spindle detections.
+    """
+    if std_thresh is None:
+        std_thresh = 2
+    if duration_thresh is None:
+        duration_thresh = 1.5
+
+    f, t, Sxx = spectrogram(signal, sf, band=freq_band, step=0.2, win_sec=2, norm=False)
+
+    # Summed power over the band, then squared
+    Sxx = np.sum(Sxx, axis=0)
+    Sxx_squared = Sxx ** 2
+
+    Sxx = Sxx_squared
+    Sxx_mean = np.mean(Sxx)
+    Sxx_std = np.std(Sxx)
+    spindle_threshold = std_thresh * Sxx_std + Sxx_mean
+    duration_threshold = duration_thresh * Sxx_std + Sxx_mean
+
+    Sxx_peaks_idx, _ = find_peaks(Sxx, (spindle_threshold))
+    if Sxx_peaks_idx.shape == (0,):
+        return None
+
+    # Find duration groups
+    duration_group = lst2group([[idx, each] for idx, each in enumerate(Sxx > duration_threshold)])
+    start_time = []
+    end_time = []
+    for each in duration_group:
+        if each[0] != 0 and each[2]:
+            if each[1] < len(t) and each[2]:
+                start_time.append(t[each[0]])
+                end_time.append(t[each[1]])
+
+    start_time = np.array(start_time)
+    end_time = np.array(end_time)
+
+    if start_time.shape != end_time.shape:
+        return None
+    if start_time.shape == (0,):
+        return None
+
+    start_time = start_time + start_time_sec
+    end_time = end_time + start_time_sec
+
+    return [[each, end_time[idx]] for idx, each in enumerate(start_time)
+            if end_time[idx] - each >= 0.5]
+
+
+def artifact_detection(signal):
+    """Artifact detection (placeholder).
+
+    Parameters
+    ----------
+    signal : ndarray
+        Signal to analyze.
+
+    Returns
+    -------
+    None
+    """
+    return None

misleep/analysis/features.py

@@ -0,0 +1,131 @@
+# -*- coding: UTF-8 -*-
+"""Feature extraction for automatic sleep staging.
+
+Implements the window-based time- and frequency-domain features used by
+the LightGBM auto-staging model (EEG and EMG).
+"""
+
+from math import floor
+
+import numpy as np
+import pandas as pd
+from scipy import stats
+
+from misleep.preprocessing.spectral import spectrogram, band_power
+from misleep.utils.entropy import hjorth_params, num_zerocross, perm_entropy
+
+
+def split_window_data(data, sf, state, window_length=20, stride_length=5):
+    """Split a signal into sliding windows.
+
+    Parameters
+    ----------
+    data : ndarray
+        Signal to split.
+    sf : float
+        Sampling frequency.
+    state : int
+        State code attached to every window (used as the label).
+    window_length : int
+        Window length in seconds.
+    stride_length : int
+        Stride in seconds.
+
+    Returns
+    -------
+    list
+        List of ``[window_array, state]`` pairs. Empty when the signal is
+        shorter than the window.
+    """
+    if data.shape[0] / sf < window_length:
+        return []
+
+    window_data = []
+    data_sec_length = floor(data.shape[0] / sf)
+    for i in range(0, data_sec_length - stride_length, stride_length):
+        window = data[int(i * sf): int((i + window_length) * sf)]
+        window_data.append([window, state])
+
+    return window_data
+
+
+def delta_theta_ratio_theta(data, sf):
+    """Delta/theta ratio and theta power from the first 5 seconds.
+
+    Parameters
+    ----------
+    data : ndarray
+        Windowed signal (20 s).
+    sf : float
+        Sampling frequency.
+
+    Returns
+    -------
+    (ratio, theta_power) : tuple of float
+    """
+    freq, t, Sxx = spectrogram(data, sf, win_sec=1)
+    band_second = np.where(t < 5)
+    psd = np.sum(np.array([each[band_second] for each in Sxx]), axis=1)
+    band_power_dict = band_power(psd, freq, bands=[[0.5, 4, "delta"], [5, 9, "theta"]], relative=True)
+    return band_power_dict["delta"] / band_power_dict["theta"], band_power_dict["theta"]
+
+
+def self_zscore(feature, quantile=0.95):
+    """Quantile-clipped z-score normalization of a feature array."""
+    upper_quantile = np.quantile(feature, quantile)
+    feature = [each if each < upper_quantile else upper_quantile for each in feature]
+    return (feature - np.mean(feature)) / np.std(feature)
+
+
+def get_data_features(data, sf, data_format="EEG"):
+    """Extract the auto-staging feature set from windowed data.
+
+    Parameters
+    ----------
+    data : list
+        List of ``[window_array, label]`` pairs (see :func:`split_window_data`).
+    sf : float
+        Sampling frequency.
+    data_format : {'EEG', 'EMG'}
+        Which channel type the windows come from. EEG additionally gets
+        skewness, kurtosis, delta/theta ratio and theta power.
+
+    Returns
+    -------
+    pandas.DataFrame
+        Feature table with a ``label`` column.
+    """
+    window_feature_df = pd.DataFrame()
+    window_feature_df["label"] = [each[1] for each in data]
+
+    # ---- Time-domain features, both EEG and EMG ----
+    data_std = np.array([np.std(each[0][:int(5 * sf)]) for each in data])
+    window_feature_df[f"{data_format}_std_zscore"] = self_zscore(data_std)
+
+    zerocross_rate = [num_zerocross(each[0][:int(5 * sf)]) / (5 * sf) for each in data]
+    window_feature_df[f"{data_format}_zerocross_rate"] = \
+        (zerocross_rate - np.mean(zerocross_rate)) / np.std(zerocross_rate)
+
+    hjorth = [hjorth_params(each[0][:int(5 * sf)]) for each in data]
+    hjorth_M = [each[0] for each in hjorth]
+    hjorth_C = [each[1] for each in hjorth]
+    window_feature_df[f"{data_format}_Hjorth_M"] = self_zscore(hjorth_M)
+    window_feature_df[f"{data_format}_Hjorth_C"] = self_zscore(hjorth_C)
+
+    perm_entropy_ = [perm_entropy(each[0][:int(5 * sf)]) for each in data]
+    window_feature_df[f"{data_format}_perm_entropy"] = self_zscore(perm_entropy_)
+
+    # ---- EEG-only features ----
+    if data_format.startswith("EEG"):
+        data_skewness = np.array([stats.skew(each[0][:int(5 * sf)]) for each in data])
+        data_kurtosis = np.array([stats.kurtosis(each[0][:int(5 * sf)]) for each in data])
+        window_feature_df[f"{data_format}_skewness_zscore"] = self_zscore(data_skewness)
+        window_feature_df[f"{data_format}_kurtosis_zscore"] = self_zscore(data_kurtosis)
+
+        delta_theta = [delta_theta_ratio_theta(each[0], sf) for each in data]
+        delta_theta_ratio = [each[0] for each in delta_theta]
+        theta = [each[1] for each in delta_theta]
+        window_feature_df[f"{data_format}_delta_theta_ratio"] = self_zscore(delta_theta_ratio)
+        window_feature_df[f"{data_format}_theta"] = self_zscore(theta)
+
+    return window_feature_df