misleep 0.3.0__py3-none-any.whl

misleep/preprocessing/filtering.py

@@ -0,0 +1,94 @@
+# -*- coding: UTF-8 -*-
+"""Signal filtering.
+
+Currently provides a Butterworth zero-phase filter through
+:func:`signal_filter` and mains (power-line) noise removal through
+:func:`filter_power_line_noise`.
+"""
+
+import numpy as np
+from scipy import signal
+
+
+def signal_filter(data, sf=256.0, btype="lowpass", low=0.5, high=30.0):
+    """Filter a signal with a zero-phase Butterworth filter.
+
+    Parameters
+    ----------
+    data : ndarray
+        1-D array, the signal to filter.
+    sf : float
+        Sampling frequency of the signal. Default is 256.
+    btype : {'lowpass', 'highpass', 'bandpass', 'bandstop'}, optional
+        The type of filter. Default is ``'lowpass'``.
+    low : float
+        Lower cutoff frequency (Hz), used by ``'highpass'``, ``'bandpass'``
+        and ``'bandstop'``.
+    high : float
+        Higher cutoff frequency (Hz), used by ``'lowpass'``, ``'bandpass'``
+        and ``'bandstop'``.
+
+    Returns
+    -------
+    filtered_data : ndarray
+        The filtered signal.
+    fname : str
+        A short name describing the filter, e.g. ``'bandpass_0.5_30'``.
+    """
+    if not isinstance(sf, (int, float)):
+        raise TypeError(f"Sample frequency should be a float, got {type(sf)}")
+    if not isinstance(low, (int, float)):
+        raise TypeError(f"Low threshold should be a float, got {type(low)}")
+    if not isinstance(high, (int, float)):
+        raise TypeError(f"High threshold should be a float, got {type(high)}")
+
+    if btype == "lowpass":
+        fnorm = high / (0.5 * sf)
+        fname = f"{btype}_{high}"
+    elif btype == "highpass":
+        fnorm = low / (0.5 * sf)
+        fname = f"{btype}_{low}"
+    elif btype in ("bandpass", "bandstop"):
+        fnorm = np.divide([low, high], 0.5 * sf)
+        fname = f"{btype}_{low}_{high}"
+    else:
+        raise ValueError(
+            f"'{btype}' is an invalid type for filter, you can only choose "
+            f"'lowpass', 'highpass', 'bandpass' or 'bandstop'")
+
+    b, a = signal.iirfilter(N=3, Wn=fnorm, btype=btype, analog=False,
+                            output="ba", ftype="butter", fs=None)
+    filtered_data = signal.filtfilt(b=b, a=a, x=data)
+
+    return filtered_data, fname
+
+
+def filter_power_line_noise(data, sf, noise_band="50-100-150"):
+    """Remove mains (power-line) noise with band-stop filters.
+
+    Parameters
+    ----------
+    data : ndarray
+        Signal to filter.
+    sf : float
+        Sampling frequency.
+    noise_band : {'50-100-150', '60-120-180'}, optional
+        Mains frequency harmonics to remove. ``'60-120-180'`` is not yet
+        implemented.
+
+    Returns
+    -------
+    ndarray
+        The filtered signal.
+    """
+    filter_band = []
+    if noise_band == "50-100-150" and sf > 306:
+        filter_band = [[47, 53], [97, 103], [147, 153]]
+    elif noise_band == "50-100-150" and sf > 206:
+        filter_band = [[47, 53], [97, 103]]
+    elif sf > 106:
+        filter_band = [[47, 53]]
+    for each in filter_band:
+        data, _ = signal_filter(data, sf, btype="bandstop", low=each[0], high=each[1])
+
+    return data

misleep/preprocessing/segment.py

@@ -0,0 +1,59 @@
+# -*- coding: UTF-8 -*-
+"""Segmentation of signals by sleep state.
+
+The :func:`crop_state_data` helper splits a recording into per-state
+sub-recordings (NREM / REM / Wake / Init) based on the annotation.
+"""
+
+from copy import deepcopy
+
+import numpy as np
+
+from misleep.data import MiData
+from misleep.utils.annotation import lst2group
+
+
+def crop_state_data(midata, mianno):
+    """Split the data into per-state sub-recordings.
+
+    The sleep-state sequence is grouped into consecutive runs; the samples
+    of every run of the same state are concatenated, and a new
+    :class:`MiData` is returned per state.
+
+    Parameters
+    ----------
+    midata : MiData
+        The recording to split.
+    mianno : MiAnnotation
+        The annotation defining the states.
+
+    Returns
+    -------
+    (NREM_data, REM_data, Wake_data, Init_data) : tuple of MiData
+        One data container per state, with ``describe`` set accordingly.
+        States not present in the annotation yield empty signals.
+    """
+    sleep_state = deepcopy(mianno.sleep_state)
+    sleep_state = lst2group([[idx, each] for idx, each in enumerate(sleep_state)])
+    signals = deepcopy(midata.signals)
+
+    state_signals = {1: [], 2: [], 3: [], 4: []}
+    for idx, signal in enumerate(signals):
+        sf = midata.sf[idx]
+        for state in state_signals:
+            state_data = [signal[int(each[0] * sf): int(each[1] * sf)]
+                          for each in sleep_state if each[2] == state]
+            state_signals[state].append(
+                np.array([element for sublist in state_data for element in sublist]))
+
+    names = {1: "NREM", 2: "REM", 3: "Wake", 4: "Init"}
+    results = []
+    for state in (1, 2, 3, 4):
+        results.append(MiData(
+            signals=state_signals[state],
+            channels=midata.channels,
+            sf=midata.sf,
+            time=midata.time,
+            describe=f"{names[state]} cropped data"))
+
+    return tuple(results)

misleep/preprocessing/spectral.py

@@ -0,0 +1,169 @@
+# -*- coding: UTF-8 -*-
+"""Spectral analysis: Welch power spectrum, spectrogram and band power."""
+
+import numpy as np
+from scipy.integrate import simpson
+from scipy.ndimage import gaussian_filter1d
+from scipy.signal import stft, welch
+
+from misleep.preprocessing.filtering import signal_filter
+
+
+def spectrum(signal, sf, band=None, relative=True, win_sec=1, nfft=None, gaussian_sigma=None):
+    """Calculate the (Welch) power spectrum of a signal.
+
+    The signal is band-pass filtered to ``band`` first, then the power
+    spectral density is estimated with :func:`scipy.signal.welch`.
+
+    Parameters
+    ----------
+    signal : ndarray
+        1-D signal.
+    sf : float
+        Sampling frequency.
+    band : list, optional
+        Frequency band of interest, e.g. ``[0.5, 30]``. Default is ``[0.5, 30]``.
+    relative : bool
+        Whether to normalize the PSD so it integrates to 1.
+    win_sec : int
+        Window length (in seconds) for the FFT.
+    nfft : int, optional
+        Number of FFT points.
+    gaussian_sigma : float, optional
+        Sigma for Gaussian smoothing of the PSD.
+
+    Returns
+    -------
+    freq : ndarray
+        Frequency bins.
+    psd : ndarray
+        Power spectral density.
+    """
+    if not isinstance(signal, np.ndarray):
+        raise TypeError(f"'signal' should be a numpy array, got {type(signal)}")
+    if not isinstance(sf, (int, float)):
+        raise TypeError(f"'sf' should be an integer or float, got {type(sf)}")
+    if not isinstance(relative, bool):
+        raise TypeError("'relative' should be a boolean")
+
+    if band is None:
+        band = [0.5, 30]
+    if not isinstance(band, list):
+        raise TypeError(f"'band' should be a list, e.g. [0.5, 4], got {type(band)}")
+
+    signal, _ = signal_filter(data=signal, sf=sf, btype="bandpass", low=band[0], high=band[1])
+
+    freq, psd = welch(signal, sf, nperseg=int(sf * win_sec), nfft=nfft, scaling="density")
+    freq = np.array([round(each, 2) for each in freq])
+    psd = gaussian_filter1d(psd, sigma=gaussian_sigma) if gaussian_sigma is not None else psd
+
+    idx_freq = np.logical_and(freq >= band[0], freq <= band[1])
+    freq = freq[idx_freq]
+    psd = psd[idx_freq]
+
+    total_power = simpson(psd, dx=freq[1] - freq[0])
+    if relative and total_power > 0:
+        psd /= total_power
+
+    return freq, psd
+
+
+def spectrogram(signal, sf, band=None, step=0.2, win_sec=2, norm=False, nfft=None):
+    """Calculate the spectrogram of a signal with the STFT.
+
+    Parameters
+    ----------
+    signal : ndarray
+        1-D signal.
+    sf : float
+        Sampling frequency.
+    band : list, optional
+        Frequency band of interest, e.g. ``[0.5, 30]``.
+    step : float
+        Step (in seconds) between STFT windows.
+    win_sec : float
+        Window length (in seconds) for the STFT.
+    norm : bool
+        Whether to normalize the power across frequencies at each time point.
+    nfft : int, optional
+        Number of FFT points.
+
+    Returns
+    -------
+    f : ndarray
+        Frequency bins.
+    t : ndarray
+        Time bins.
+    Sxx : ndarray
+        Spectrogram (squared magnitude of the STFT).
+    """
+    if not isinstance(signal, np.ndarray):
+        raise TypeError(f"'signal' should be a numpy array, got {type(signal)}")
+    if not isinstance(sf, (int, float)):
+        raise TypeError(f"'sf' should be an integer or float, got {type(sf)}")
+
+    if step > win_sec:
+        raise ValueError(f"'step' ({step}) should be smaller than 'win_sec' ({win_sec})")
+    step = 1 / sf if step <= 0 else step
+
+    if not isinstance(norm, bool):
+        raise TypeError("'norm' should be a boolean")
+
+    if band is None:
+        band = [0.5, 30]
+    if not isinstance(band, list):
+        raise TypeError(f"'band' should be a list, e.g. [0.5, 30], got {type(band)}")
+
+    nperseg = int(win_sec * sf)
+    noverlap = int(nperseg - (step * sf))
+
+    f, t, Sxx = stft(signal, sf, nperseg=nperseg, nfft=nfft,
+                     noverlap=noverlap, padded=False, boundary="zeros")
+
+    f = np.array([round(each, 2) for each in f])
+
+    idx_f = np.logical_and(f >= band[0], f <= band[1])
+    f = f[idx_f]
+    Sxx = Sxx[idx_f, :]
+    Sxx = np.square(np.abs(Sxx))
+
+    if norm:
+        sum_power = Sxx.sum(0).reshape(1, -1)
+        np.divide(Sxx, sum_power, out=Sxx, where=sum_power != 0)
+
+    return f, t, Sxx
+
+
+def band_power(psd, freq, bands=None, relative=False):
+    """Compute the band power of a PSD.
+
+    Parameters
+    ----------
+    psd : ndarray
+        Power spectral density values.
+    freq : ndarray
+        Frequencies corresponding to ``psd``.
+    bands : list, optional
+        Frequency bands, e.g. ``[[0.5, 4, 'delta'], [4, 9, 'theta']]``.
+    relative : bool
+        Whether to express each band power relative to the total power.
+
+    Returns
+    -------
+    dict
+        Band name -> band power.
+    """
+    freq_res = freq[1] - freq[0]
+    band_dict = {}
+    for each in bands:
+        idx_band = np.logical_and(freq >= each[0], freq <= each[1])
+        bp = simpson(psd[idx_band], dx=freq_res)
+
+        if relative:
+            total = simpson(psd, dx=freq_res)
+            if total > 0:
+                bp /= total
+
+        band_dict[each[2]] = bp
+
+    return band_dict

misleep/utils/__init__.py

@@ -0,0 +1,45 @@
+# -*- coding: UTF-8 -*-
+"""Utility module.
+
+Pure-Python helpers that do not depend on the GUI or the data containers:
+
+* :mod:`misleep.utils.annotation`  -- annotation line <-> list conversion
+* :mod:`misleep.utils.time_utils`  -- datetime helpers
+* :mod:`misleep.utils.entropy`     -- signal complexity measures
+* :mod:`misleep.utils.misc`        -- various small helpers
+"""
+
+from .annotation import (
+    lst2group,
+    marker2mianno,
+    start_end2mianno,
+    sleep_state2mianno,
+    insert_row,
+    temp_loop4below_row,
+)
+from .time_utils import transfer_time, second2time
+from .entropy import num_zerocross, hjorth_params, perm_entropy
+from .misc import (
+    create_new_mianno,
+    identify_startend_color,
+    get_base_path,
+    downsample_by_most_frequent,
+)
+
+__all__ = [
+    "lst2group",
+    "marker2mianno",
+    "start_end2mianno",
+    "sleep_state2mianno",
+    "insert_row",
+    "temp_loop4below_row",
+    "transfer_time",
+    "second2time",
+    "num_zerocross",
+    "hjorth_params",
+    "perm_entropy",
+    "create_new_mianno",
+    "identify_startend_color",
+    "get_base_path",
+    "downsample_by_most_frequent",
+]

misleep/utils/annotation.py

@@ -0,0 +1,130 @@
+# -*- coding: UTF-8 -*-
+"""Helpers for converting between annotation representations."""
+
+from misleep.utils.time_utils import transfer_time
+
+
+def lst2group(pre_lst):
+    """Group consecutive rows of a two-column list into ``[start, end, value]`` triples.
+
+    Converts a list like ``[[1, 2], [2, 2], [3, 2], [4, 2], [5, 2], [6, 1], [7, 1], ...]``
+    into ``[[1, 6, 2], [6, 9, 1], ...]`` where the second element of each
+    triple is an *exclusive* end index.
+
+    Parameters
+    ----------
+    pre_lst : list of [index, value]
+        Sorted list of ``[index, value]`` pairs.
+
+    Returns
+    -------
+    list of [start, end, value]
+        Consecutive runs, ``end`` is exclusive.
+    """
+    rows = iter(pre_lst)
+    try:
+        first_idx, first_value = next(rows)
+    except StopIteration:
+        return []
+
+    grouped = []
+    run_start = last_idx = first_idx
+    run_value = first_value
+    for idx, value in rows:
+        if value != run_value:
+            grouped.append([run_start, last_idx + 1, run_value])
+            run_start = idx
+            run_value = value
+        last_idx = idx
+    grouped.append([run_start, last_idx + 1, run_value])
+    return grouped
+
+
+def marker2mianno(marker):
+    """Convert MiSleep annotation lines to ``[[time, label], ...]`` markers."""
+    if marker != [] or marker is not None:
+        marker = [each.split(", ") for each in marker]
+        marker = [[float(each[1]), each[7]] for each in marker]
+        return marker
+    return []
+
+
+def start_end2mianno(start_end):
+    """Convert MiSleep annotation lines to ``[[start, end, label], ...]`` events."""
+    if start_end != [] or start_end is not None:
+        start_end = [each.split(", ") for each in start_end]
+        start_end = [[float(each[1]), float(each[4]), each[7]] for each in start_end]
+        return start_end
+    return []
+
+
+def sleep_state2mianno(sleep_state):
+    """Convert MiSleep annotation lines to a per-second state sequence."""
+    start_end = [each.split(", ") for each in sleep_state]
+    # Old version misleep labels start from 1
+    if start_end[0][1] == "1":
+        sleep_state = [item for each in start_end for item in [int(each[6])] * (int(each[4]) - int(each[1]) + 1)]
+    else:
+        sleep_state = [item for each in start_end for item in [int(each[6])] * (int(each[4]) - int(each[1]))]
+    return sleep_state
+
+
+def insert_row(df, idx, row):
+    """Insert a row into a dataframe at a specific position.
+
+    Parameters
+    ----------
+    df : pandas.DataFrame
+        Dataframe to insert into.
+    idx : int
+        Position to insert the row (inserted below this index).
+    row : pandas.Series or DataFrame
+        Row to insert.
+
+    Returns
+    -------
+    pandas.DataFrame
+        A new dataframe with the row inserted.
+    """
+    import pandas as pd
+
+    if isinstance(row, pd.Series):
+        row = pd.DataFrame(row).T
+    df = pd.concat([df[:idx], row, df[idx:]], axis=0).reset_index(drop=True)
+    return df
+
+
+def temp_loop4below_row(row, acquisition_time, columns):
+    """Split a row that crosses an hour boundary into three rows.
+
+    Used when exporting per-hour sleep statistics: a long bout that
+    straddles a full hour is split into "before hour", an hourly
+    ``MARKER`` divider row, and "after hour".
+
+    Returns
+    -------
+    (previous_row, new_row, below_row) : tuple of pandas.Series
+    """
+    import pandas as pd
+
+    seconds_ = (int(row["start_time_sec"] / 3600) + 1) * 3600
+    previous_row = pd.Series([
+        row["start_time"], row["start_time_sec"], "1",
+        transfer_time(acquisition_time, seconds_, "%Y-%m-%d %H:%M:%S"),
+        seconds_, "0", row["state_code"], row["state"]
+    ], index=columns)
+
+    new_row = pd.Series([
+        transfer_time(acquisition_time, seconds_, "%Y-%m-%d %H:%M:%S"),
+        seconds_, " ",
+        transfer_time(acquisition_time, seconds_, "%Y-%m-%d %H:%M:%S"),
+        seconds_, " ", "5", "MARKER"
+    ], index=columns)
+
+    below_row = pd.Series([
+        transfer_time(acquisition_time, seconds_ + 1, "%Y-%m-%d %H:%M:%S"),
+        seconds_ + 1, "1", row["end_time"], row["end_time_sec"],
+        "0", row["state_code"], row["state"]
+    ], index=columns)
+
+    return previous_row, new_row, below_row

misleep/utils/entropy.py

@@ -0,0 +1,135 @@
+# -*- coding: UTF-8 -*-
+"""Self-contained implementations of a few signal-complexity measures.
+
+These functions were originally copied from the `antropy` package
+(https://github.com/raphaelvallat/antropy, BSD-3-Clause) so that MiSleep
+does not need to import the whole package just for three functions --
+importing antropy used to cost a lot of startup time.
+"""
+
+import numpy as np
+from math import factorial
+
+
+def num_zerocross(x, normalize=False, axis=-1):
+    """Number of zero-crossings of a signal.
+
+    Parameters
+    ----------
+    x : array_like
+        1-D or N-D data.
+    normalize : bool
+        If True, divide by the number of samples (output in ``[0, 1]``).
+    axis : int
+        Axis along which to compute. Default is -1.
+
+    Returns
+    -------
+    nzc : int or ndarray
+        Number of zero-crossings.
+    """
+    x = np.asarray(x)
+    nzc = np.diff(np.signbit(x), axis=axis).sum(axis=axis)
+    if normalize:
+        nzc = nzc / x.shape[axis]
+    return nzc
+
+
+def hjorth_params(x, axis=-1):
+    """Calculate Hjorth mobility and complexity on the given axis.
+
+    Parameters
+    ----------
+    x : array_like
+        1-D or N-D data.
+    axis : int
+        Axis along which to compute. Default is -1.
+
+    Returns
+    -------
+    mobility, complexity : float or ndarray
+        Hjorth mobility and complexity parameters.
+    """
+    x = np.asarray(x)
+    dx = np.diff(x, axis=axis)
+    ddx = np.diff(dx, axis=axis)
+    x_var = np.var(x, axis=axis)  # = activity
+    dx_var = np.var(dx, axis=axis)
+    ddx_var = np.var(ddx, axis=axis)
+    mob = np.sqrt(dx_var / x_var)
+    com = np.sqrt(ddx_var / dx_var) / mob
+    return mob, com
+
+
+def perm_entropy(x, order=3, delay=1, normalize=False):
+    """Permutation entropy (Bandt & Pompe, 2002).
+
+    Parameters
+    ----------
+    x : array_like
+        1-D time series.
+    order : int
+        Order of permutation entropy (embedding dimension). Default is 3.
+    delay : int or array_like
+        Time delay (lag). When several delays are given, the average
+        permutation entropy across them is returned.
+    normalize : bool
+        If True, divide by ``log2(order!)`` so the output lies in [0, 1].
+
+    Returns
+    -------
+    pe : float
+        Permutation entropy (in bits, unless normalized).
+    """
+    if isinstance(delay, (list, np.ndarray, range)):
+        return np.mean([perm_entropy(x, order=order, delay=d, normalize=normalize) for d in delay])
+    x = np.array(x)
+    ran_order = range(order)
+    hashmult = np.power(order, ran_order)
+    assert delay > 0, "delay must be greater than zero."
+    sorted_idx = _embed(x, order=order, delay=delay).argsort(kind="quicksort")
+    hashval = (np.multiply(sorted_idx, hashmult)).sum(1)
+    _, c = np.unique(hashval, return_counts=True)
+    p = np.true_divide(c, c.sum())
+    pe = -_xlogx(p).sum()
+    if normalize:
+        pe /= np.log2(factorial(order))
+    return pe
+
+
+def _embed(x, order=3, delay=1):
+    """Time-delay embedding of a 1-D or 2-D array."""
+    x = np.asarray(x)
+    N = x.shape[-1]
+    assert x.ndim in [1, 2], "Only 1D or 2D arrays are currently supported."
+    if order * delay > N:
+        raise ValueError("Error: order * delay should be lower than x.size")
+    if delay < 1:
+        raise ValueError("Delay has to be at least 1.")
+    if order < 2:
+        raise ValueError("Order has to be at least 2.")
+
+    if x.ndim == 1:
+        Y = np.zeros((order, N - (order - 1) * delay))
+        for i in range(order):
+            Y[i] = x[(i * delay): (i * delay + Y.shape[1])]
+        return Y.T
+    else:
+        Y = []
+        embed_signal_length = N - (order - 1) * delay
+        indice = [[(i * delay), (i * delay + embed_signal_length)] for i in range(order)]
+        for i in range(order):
+            temp = x[:, indice[i][0]: indice[i][1]].reshape(-1, embed_signal_length, 1)
+            Y.append(temp)
+        Y = np.concatenate(Y, axis=-1)
+        return Y
+
+
+def _xlogx(x, base=2):
+    """Return ``x * log_b(x)`` for positive x, 0 for x == 0, else nan."""
+    x = np.asarray(x)
+    xlogx = np.zeros(x.shape)
+    xlogx[x < 0] = np.nan
+    valid = x > 0
+    xlogx[valid] = x[valid] * np.log(x[valid]) / np.log(base)
+    return xlogx

misleep/utils/misc.py

@@ -0,0 +1,69 @@
+# -*- coding: UTF-8 -*-
+"""Miscellaneous helpers shared across MiSleep."""
+
+import os
+from collections import Counter
+
+from misleep.data.annotation import MiAnnotation
+
+
+def create_new_mianno(data_duration):
+    """Create a fresh :class:`MiAnnotation` with all states set to Init (4).
+
+    Parameters
+    ----------
+    data_duration : int
+        Duration of the recording in seconds.
+
+    Returns
+    -------
+    MiAnnotation
+    """
+    marker = []
+    start_end = []
+    sleep_state = [4 for _ in range(data_duration)]
+    return MiAnnotation(sleep_state=sleep_state, start_end=start_end, marker=marker)
+
+
+def identify_startend_color(color_dict, state_name, end=False):
+    """Return the color of a state name from a mapping, or ``'blue'`` as fallback."""
+    if state_name in color_dict.keys():
+        return color_dict[state_name]
+    return "blue"
+
+
+def get_base_path(file_path):
+    """Strip a known data-file extension from a path.
+
+    Returns the path without ``.txt``/``.xlsx``/``.mat``/``.edf``/``.csv``
+    when present, otherwise the input unchanged.
+    """
+    base, ext = os.path.splitext(file_path)
+    if ext in [".txt", ".xlsx", ".mat", ".edf", ".csv"]:
+        return base
+    return file_path
+
+
+def downsample_by_most_frequent(lst, group_size=5):
+    """Downsample a list by taking the most frequent element per chunk.
+
+    Parameters
+    ----------
+    lst : list
+        Input sequence.
+    group_size : int
+        Chunk size. Default is 5.
+
+    Returns
+    -------
+    list
+        One representative value per chunk.
+    """
+    result = []
+    for i in range(0, len(lst), group_size):
+        group = lst[i:i + group_size]
+        if group:
+            counter = Counter(group)
+            most_common = counter.most_common(1)[0][0]
+            result.append(most_common)
+    return result