Skip to main content

A toolbox for sleep stage classification using ECG data

Project description

Py Version PyPI Version

SleepECG

This package provides tools for sleep stage classification when EEG signals are not available. Based only on ECG (and to a lesser extent also movement data), SleepECG provides a functional interface for

  • downloading and reading open polysomnography datasets (TODO),
  • detecting heartbeats from ECG signals, and
  • classifying sleep stages (which includes the complete preprocessing, feature extraction, and classification pipeline) (TODO).

Installation

SleepECG is available on PyPI and can be installed with pip:

pip install sleepecg

Heartbeat detection

ECG-based sleep staging heavily relies on heartrate variability. Therefore, a reliable and efficient heartbeat detector is essential. SleepECG provides a detector based on the approach described by Pan & Tompkins (1985). We outsourced performance-critical code to a C extension, which leads to substantially faster detections as compared to implementations in pure Python.

Usage

The function detect_heartbeats() finds heartbeats in an unfiltered ECG signal ecg (a one-dimensional NumPy array) with sampling frequency fs (in Hz). It returns the indices of all detected heartbeats. A complete example including visualization and performance evaluation is available in examples/heartbeat_detection.py.

from sleepecg import detect_heartbeats

detection = detect_heartbeats(ecg, fs)

Performance evaluation

We evaluated detector runtime using slices of different lengths from LTDB records with at least 20 hours duration. Error bars in the plot below correspond to the standard error of the mean. Our detector is by far the fastest implementation among all tested packages (note the y-axis is logarithmically scaled).

LTDB runtimes

We also evaluated detection performance on all MITDB records. We defined a successful detection if it was within 100ms (i.e. 36 samples) of the corresponding annotation (using a tolerance here is necessary because annotations usually do not coincide with the exact R peak locations). In terms of recall, precision, and F1 score, our detector is among the best heartbeat detectors available.

MITDB metrics

For analysis of heartrate variability, detecting the exact location of heartbeats is essential. As a measure of how accurate a detector is, we computed Pearson's correlation coefficient between resampled RRI time series deduced from annotated and detected beat locations from all GUDB records. Our implementation detects peaks in the bandpass-filtered ECG signal, so it produces stable RRI time series without any post-processing.

GUDB pearson correlation

We used the following detectors for our benchmarks:

# mne
import mne  # https://pypi.org/project/mne/
detection = mne.preprocessing.ecg.qrs_detector(fs, ecg, verbose=False)

# wfdb_xqrs
import wfdb.processing  # https://pypi.org/project/wfdb/
detection = wfdb.processing.xqrs_detect(ecg, fs, verbose=False)

# pyecg_pan_tompkins
import ecgdetectors  # https://pypi.org/project/py-ecg-detectors/
detection = ecgdetectors.Detectors(fs).pan_tompkins_detector(ecg)

# biosppy_hamilton
import biosppy  # https://pypi.org/project/biosppy/
detection = biosppy.signals.ecg.hamilton_segmenter(ecg, fs)[0]

# heartpy
import heartpy  # https://pypi.org/project/heartpy/
wd, m = heartpy.process(ecg, fs)
detection = np.array(wd['peaklist'])[wd['binary_peaklist'].astype(bool)]

# neurokit2_nk
import neurokit2  # https://pypi.org/project/neurokit2/
clean_ecg = neurokit2.ecg.ecg_clean(ecg, int(fs), method='neurokit')
peak_indices = neurokit2.ecg.ecg_findpeaks(clean_ecg, int(fs), method='neurokit')['ECG_R_Peaks']

# neurokit2_kalidas2017
import neurokit2  # https://pypi.org/project/neurokit2/
clean_ecg = neurokit2.ecg.ecg_clean(ecg, int(fs), method='kalidas2017')
peak_indices = neurokit2.ecg.ecg_findpeaks(clean_ecg, int(fs), method='kalidas2017')['ECG_R_Peaks']

# sleepecg
import sleepecg  # https://pypi.org/project/sleepecg/
detection = sleepecg.heartbeat_detection.detect_heartbeats(ecg, fs)

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sleepecg-0.1.0.tar.gz (17.2 kB view hashes)

Uploaded Source

Built Distributions

sleepecg-0.1.0-cp39-cp39-win_amd64.whl (27.8 kB view hashes)

Uploaded CPython 3.9 Windows x86-64

sleepecg-0.1.0-cp39-cp39-win32.whl (26.5 kB view hashes)

Uploaded CPython 3.9 Windows x86

sleepecg-0.1.0-cp39-cp39-manylinux2014_x86_64.whl (44.0 kB view hashes)

Uploaded CPython 3.9

sleepecg-0.1.0-cp39-cp39-manylinux2014_i686.whl (43.7 kB view hashes)

Uploaded CPython 3.9

sleepecg-0.1.0-cp39-cp39-manylinux1_x86_64.whl (44.0 kB view hashes)

Uploaded CPython 3.9

sleepecg-0.1.0-cp39-cp39-manylinux1_i686.whl (43.7 kB view hashes)

Uploaded CPython 3.9

sleepecg-0.1.0-cp39-cp39-macosx_10_9_x86_64.whl (23.4 kB view hashes)

Uploaded CPython 3.9 macOS 10.9+ x86-64

sleepecg-0.1.0-cp38-cp38-win_amd64.whl (27.8 kB view hashes)

Uploaded CPython 3.8 Windows x86-64

sleepecg-0.1.0-cp38-cp38-win32.whl (26.5 kB view hashes)

Uploaded CPython 3.8 Windows x86

sleepecg-0.1.0-cp38-cp38-manylinux2014_x86_64.whl (44.3 kB view hashes)

Uploaded CPython 3.8

sleepecg-0.1.0-cp38-cp38-manylinux2014_i686.whl (44.0 kB view hashes)

Uploaded CPython 3.8

sleepecg-0.1.0-cp38-cp38-manylinux1_x86_64.whl (44.3 kB view hashes)

Uploaded CPython 3.8

sleepecg-0.1.0-cp38-cp38-manylinux1_i686.whl (44.0 kB view hashes)

Uploaded CPython 3.8

sleepecg-0.1.0-cp38-cp38-macosx_10_9_x86_64.whl (23.4 kB view hashes)

Uploaded CPython 3.8 macOS 10.9+ x86-64

sleepecg-0.1.0-cp37-cp37m-win_amd64.whl (27.8 kB view hashes)

Uploaded CPython 3.7m Windows x86-64

sleepecg-0.1.0-cp37-cp37m-win32.whl (26.4 kB view hashes)

Uploaded CPython 3.7m Windows x86

sleepecg-0.1.0-cp37-cp37m-manylinux2014_x86_64.whl (45.0 kB view hashes)

Uploaded CPython 3.7m

sleepecg-0.1.0-cp37-cp37m-manylinux2014_i686.whl (44.7 kB view hashes)

Uploaded CPython 3.7m

sleepecg-0.1.0-cp37-cp37m-manylinux1_x86_64.whl (45.0 kB view hashes)

Uploaded CPython 3.7m

sleepecg-0.1.0-cp37-cp37m-manylinux1_i686.whl (44.7 kB view hashes)

Uploaded CPython 3.7m

sleepecg-0.1.0-cp37-cp37m-macosx_10_9_x86_64.whl (23.4 kB view hashes)

Uploaded CPython 3.7m macOS 10.9+ x86-64

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page