A toolbox for sleep stage classification using ECG data
Project description
SleepECG
SleepECG 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 functions 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
Alternatively, install via conda:
conda install -c conda-forge sleepecg
Contributing
The contributing guide contains detailed instructions on how to contribute to SleepECG.
Dataset reading
SleepECG provides a consistent functional interface for downloading and reading common polysomnography datasets. While reader functions are a WIP, SleepECG already provides an interface for downloading datasets from the National Sleep Research Resource (NSRR) on sleepdata.org, which replicates the functionality of the NSRR Ruby Gem.
The example below downloads all files within mesa/polysomnography/edfs
matching *-00*
to a local folder ./datasets
:
from sleepecg.io import download_nsrr, set_nsrr_token
set_nsrr_token('<your-download-token-here>')
download_nsrr(
db_slug='mesa',
subfolder='polysomnography/edfs',
pattern='*-00*',
data_dir='./datasets',
)
ECG dataset readers
To facilitate evaluation of heartbeat detector performance, reader functions for the following annotated ECG datasets are provided:
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 makes the detector substantially faster than other implementations. However, we also provide Numba and pure Python backends (the Numba backend is almost as fast whereas the pure Python implementation is much slower).
Usage
The function detect_heartbeats()
finds heartbeats in an unfiltered ECG signal ecg
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
All code used for performance evaluation is available in examples/benchmark
. The used package versions are listed in requirements-benchmark.txt
.
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. The C backend of our detector is by far the fastest implementation among all tested packages (note that the y-axis is logarithmically scaled). Runtime evaluation was performed on an Intel® Xeon® Prozessor E5-2440 v2 with 32 GiB RAM. No parallelization was used.
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.
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.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distributions
Hashes for sleepecg-0.3.0-cp39-cp39-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 72f7bb6a21fa8962e5dbf098dddd4e18f3e9abd5df3bc79d0ef21f575c6ef8e8 |
|
MD5 | a01f0592e6d88542991052136b0ca115 |
|
BLAKE2b-256 | cfcfa9f07ab4c8184b37b44e82456ece5f615918af7f1439bc21ea80e6bba5a5 |
Hashes for sleepecg-0.3.0-cp39-cp39-win32.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 23ddcec88383ff605d7ada30f2ad3c7c026aafaaae2ca81a7c45de771e141fd7 |
|
MD5 | 9f5b5a888a30beb681897ab56beac002 |
|
BLAKE2b-256 | fcb768b7927941114543059208e0540b53bf2aef1f672282588470bd72dd3958 |
Hashes for sleepecg-0.3.0-cp39-cp39-manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 60c64bc1ddd20c5489678629cc53190e54c33f7517beae84664542bf330cda4c |
|
MD5 | 928d95b16ebc11d34fb1d18da0f75664 |
|
BLAKE2b-256 | a6a7e933c86c0fed7a158eafcaca9f10fa8a4cd94109633de5153b6a6fd4fab7 |
Hashes for sleepecg-0.3.0-cp39-cp39-manylinux2014_i686.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8cede376a59c169cd759b64e06d1327d07a9585378473d5455cba58d9133e79e |
|
MD5 | 47e60c329b97f0a72f364959aebc641c |
|
BLAKE2b-256 | 52e1d0e7780f87fc45188a5d5953b9c908e15b5f1a30f3502fb7281b42a05e67 |
Hashes for sleepecg-0.3.0-cp39-cp39-manylinux1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 32c625c878528f5e8ce9c826ca7200fc564a4960096a81b728342be36184675e |
|
MD5 | 300c14b8d99e41d8ba8089801217c866 |
|
BLAKE2b-256 | b3cf4af75374c6caaec1e84edd2208828c75003d92f68691d3a8cee1a38519a7 |
Hashes for sleepecg-0.3.0-cp39-cp39-manylinux1_i686.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3e8106a9983f44ff865546a5aab150e9eb5497167e521a21ce4133db885ec884 |
|
MD5 | 3939e43cb84c6f14cba8f24fa79ec34f |
|
BLAKE2b-256 | 2fb68716e18a8dfc02d03314acfa759f893c7cda8be0e916aa295ebe658719b9 |
Hashes for sleepecg-0.3.0-cp39-cp39-macosx_11_0_arm64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 546032842f54cbaf88a5985de97b745f4fe89e11e604d4adf4c6f87871bb8f81 |
|
MD5 | 287143e19c973a83dbd6051165a29dca |
|
BLAKE2b-256 | a81802866fc432b936b224533d48412302953554db7f2acc9accabe7931ec45a |
Hashes for sleepecg-0.3.0-cp39-cp39-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | bd5e0ce1dbb250ded51366e896d5aa33bacf04769fe808549387ab7ab734a245 |
|
MD5 | 7a3d3eb03c4fbccdf10b9921d27d30c0 |
|
BLAKE2b-256 | dcb8bf64d411836e92f0e5cab16569d3ec9cd5a6ea93ddbde829af9881a75559 |
Hashes for sleepecg-0.3.0-cp38-cp38-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | ca12b1b7c88908b669dc4a4693a36bcf337f302d415d2e9d2fe3944a914427cf |
|
MD5 | f478d660192693abf84e7f14a0c1fb14 |
|
BLAKE2b-256 | c85cb276de69ab90ef163c1a4ad45ddd552f560b37713423951e36a02f7c06c5 |
Hashes for sleepecg-0.3.0-cp38-cp38-win32.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 2ca068711e1b665c34e1f5fc360a3ca83a305ac024e7906c129ce126f3a5182f |
|
MD5 | 4dd8ceaf0d4866672d9285f85b34bb11 |
|
BLAKE2b-256 | b22dfbd7ae9fd8a939795c8be14284935873ef690d1d8bca274cd690c83d4924 |
Hashes for sleepecg-0.3.0-cp38-cp38-manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 501d6056b5b2addba28a9dd3c628a4d77171ef536b8627f4bcee124eeb882b76 |
|
MD5 | 1766c77248dabec9c1bf04b16247c451 |
|
BLAKE2b-256 | 8cdb46626c5f7c2d15feda04a1beba34903e220da7da2c6961feb02f99fc7846 |
Hashes for sleepecg-0.3.0-cp38-cp38-manylinux2014_i686.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | fdc5ce9061f0e4d260bc32b0ad1657fa1fc541b486c05e2eae6a83b6845c07df |
|
MD5 | 0f6ca4a625e8bf60a2153a5725a13491 |
|
BLAKE2b-256 | 306667bb5abeb499040d3c72eafeb3f231d30c17f9426fbf8f316df97c9f994f |
Hashes for sleepecg-0.3.0-cp38-cp38-manylinux1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3e218fbfba7896f4a26805b1bfcbc653483c0ba4325cd7bbb9f16e7e29a6ddec |
|
MD5 | 1b47f57fb3c89f147a33d8ff7b2e74c6 |
|
BLAKE2b-256 | 418f294bef8917998cc7a07835b0b08ccf2026a8b7151fd39e485ff4828c657e |
Hashes for sleepecg-0.3.0-cp38-cp38-manylinux1_i686.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 83695de627b1df74aedf5b475824d244b01cab9279f62c62d3ada333a46c55f0 |
|
MD5 | 6c554367e34c6348c1cfc7ce386dbc60 |
|
BLAKE2b-256 | 3a0eb433fe667ca92dcc053ccbc24704db6e60abf08c74eca18115b9ed54d236 |
Hashes for sleepecg-0.3.0-cp38-cp38-macosx_11_0_arm64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 21b14c8acc6839c61134286aaa11776b1aaa1621538c26ff239578e06a8de49f |
|
MD5 | 94283489c72b1a427d06f7d7736c01d2 |
|
BLAKE2b-256 | c520a3df848e1eebad044750b932a047f7be8d150bdbe7aab79453bef34175da |
Hashes for sleepecg-0.3.0-cp38-cp38-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0d36999165c4a95da018e00798f475eefcfccf371a7783e3a97739045dcb422f |
|
MD5 | bdb1691cdf815b82773ab419c0ab95f5 |
|
BLAKE2b-256 | 4337b58228b1bb2b9977e753c091728032e935dd3881ed53c7af61d4482685f9 |
Hashes for sleepecg-0.3.0-cp37-cp37m-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 1d055bedf5fa6b65957d0e3abb8794c0796985f28f4b2e113f85d96a46b6652d |
|
MD5 | f5f6cdd1e9471aad3f4785fbc6587806 |
|
BLAKE2b-256 | 3dde1c1938c2fd0edaac82a36d422c8b3d9e094d2a454e815aefde497ccf0a6f |
Hashes for sleepecg-0.3.0-cp37-cp37m-win32.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | ec3cdf0b78b887ccabd7136d9be43383db114565403d9631d8b3c77e2d82c4d5 |
|
MD5 | 127a5e07325a450531a7a02269a59e36 |
|
BLAKE2b-256 | b8965e1c5df40dac9d35629d1eebb80808df16a580fd316c3f89b0f49f643a7e |
Hashes for sleepecg-0.3.0-cp37-cp37m-manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | cb4a1fe43da309059e6f37bac0773a17f38cbbac11430da8f280a31d47919f42 |
|
MD5 | 9b1d466961acad7720a7906b082c4f25 |
|
BLAKE2b-256 | 729296b8f31bf532d331a99e5da7861d035ff584ed8ee13beb430aae3a812f14 |
Hashes for sleepecg-0.3.0-cp37-cp37m-manylinux2014_i686.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | d3d7e28401eb11eec7bb4324fe209a413cd47ce09fdfa548c2261aaf7d5af24a |
|
MD5 | 8bd259b1f608ebbe68becac24f5cf985 |
|
BLAKE2b-256 | feaa1f12c4c73d7072e342d346720ca81952b4b29b6d1afb7202462b0d269269 |
Hashes for sleepecg-0.3.0-cp37-cp37m-manylinux1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | f97c69a6e46033011468817d521c79f4053ecb7aba22648022a5a7911f141db8 |
|
MD5 | 9543c1f85580b11508ec94fe178aed0a |
|
BLAKE2b-256 | 4e7d6363f994626d05c87ba3126e50910532f21292b1970e91c8242070859964 |
Hashes for sleepecg-0.3.0-cp37-cp37m-manylinux1_i686.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 2aeef476b7d93c2bac3d3ae7545f4fef69eb02f86ee0fb8f88bb7bd53e5011e9 |
|
MD5 | b87afed5d69591377ab35f8b5420ea61 |
|
BLAKE2b-256 | 424873c8a6140850088d89dec3586950723956d257257e99a4832b6188d6c57f |
Hashes for sleepecg-0.3.0-cp37-cp37m-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 19f871059a4808e64a045d7c68e34dec2be201de8404ece9de973531d9edbc89 |
|
MD5 | 36feb79de4724b64f172bbac7c0f12d0 |
|
BLAKE2b-256 | eda60a313a6309ec51d727ade47d50fd574e898a89a775c953b1238255d8c8b1 |