asleep: a sleep classifier for wearable sensor data using machine learning

This is a Python package for classifying sleep stages from wearable sensor data / wrist - worn accelerometer. The underlying model was trained and tested in 1000 + nights of multi - centre polysomnography with tri - axial accelerometer data.

The key features of this package are as follows:

A simple and easy - to - use API for sleep stage classification.
Sleep / wake metric estimation including total sleep duration and sleep efficiency.
Sleep architecture metric estimation including rapid - eye - movement(REM) / NREM sleep duration.

Dependencies

Python 3.8
Java 8 (1.8.0) or greater

Check with:

$ python --version
$ java -version

Installation

$ pip install asleep

Development checks

Install the development dependencies and run the same quality gates used by tox:

$ pip install -e '.[dev,test]'
$ ruff check .
$ mypy
$ pytest

Usage

All the processing will be much faster after the first time because the model weights will to have to be downloaded the first time that the package is used.

# Process an AX3 file
$ get_sleep sample.cwa

# Or an ActiGraph file
$ get_sleep sample.gt3x

# Or a GENEActiv file
$ get_sleep sample.bin

# Or a CSV file (see data format below)
$ get_sleep sample.csv

Output

Summary
-------
{
    "Filename": "sample.cwa",
    "Filesize(MB)": 65.1,
    "Device": "Axivity",
    "DeviceID": 2278,
    "ReadErrors": 0,
    "SampleRate": 100.0,
    "ReadOK": 1,
    "StartTime": "2013-10-21 10:00:07",
    "EndTime": "2013-10-28 10:00:01",
    "Total sleep duration(min)": 655.7,
    "Total overnight sleep(min)": 43132,
    ...
}

Estimated total sleep duration
---------------------
              total sleep duration(min)
time
2013 - 10 - 21     435.2
2013 - 10 - 22     436.2
2013 - 10 - 23    432.2
...

Output: outputs /sample/

Visualisation

You can visualise the sleep parameters using the following command:

$ visu_sleep PATH_TO_OUTPUT_FOLDER

Processing CSV files

If a CSV file is provided, it must have the following header: time, x, y, z.

Example:

time, x, y, z
2013 - 10 - 21 10: 00: 08.000, -0.078923, 0.396706, 0.917759
2013 - 10 - 21 10: 00: 08.010, -0.094370, 0.381479, 0.933580
2013 - 10 - 21 10: 00: 08.020, -0.094370, 0.366252, 0.901938
2013 - 10 - 21 10: 00: 08.030, -0.078923, 0.411933, 0.901938

Citation

If you want to use our package for your project, please cite our paper below:

@article{yuan2024self,
  title={Self-supervised learning of accelerometer data provides new insights for sleep and its association with mortality},
  author={Yuan, Hang and Plekhanova, Tatiana and Walmsley, Rosemary and Reynolds, Amy C and Maddison, Kathleen J and Bucan, Maja and Gehrman, Philip and Rowlands, Alex and Ray, David W and Bennett, Derrick and others},
  journal={NPJ digital medicine},
  volume={7},
  number={1},
  pages={86},
  year={2024},
  publisher={Nature Publishing Group UK London}
}

Acknowledgements

We would like to thank all our code contributors, manuscript co - authors, and research participants for their help in making this work possible. The data processing pipeline of this repository is based on the step_count package from our group. Special thanks to @chanshing for his help in developing the package.

Maintainer documentation

See RELEASING.md for the package release process.

Metadata

Release files for asleep 0.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for asleep 0.5.0
File	Size	Uploaded
asleep-0.5.0.tar.gz	41.2 MB	Oct 9, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for asleep 0.5.0
File	Interpreter	ABI	Platform	Reset
asleep-0.5.0-py3-none-any.whl 51.1 kB Oct 9, 2026	Python 3	none	any	Details

Total release size: 41.3 MB

Release files / asleep-0.5.0.tar.gz

Download URL	asleep-0.5.0.tar.gz
Size	41.2 MB
Tags	Source
SHA-256 checksum How to use checksums	`69e0bb7dcc72708f50e55fa437682d637d261cd1e9398ea665c522548abbe8f2`
BLAKE2b-256 checksum How to use checksums	`73ae8846613724ea8f3585d83f8dd7e9f7f8a6ffd26ab4644a58a1e6d139a43a`
Upload date	Oct 9, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Release files / asleep-0.5.0-py3-none-any.whl

Download URL	asleep-0.5.0-py3-none-any.whl
Size	51.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`0d2d94aedfcf0023b00b25a41eb8e444c228df90f189f23324e6d9d207312a7d`
BLAKE2b-256 checksum How to use checksums	`866fce881f3a7f8bc134c8809c791c5e36c58afeed5e2a3431cd9d643123c5b5`
Upload date	Oct 9, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`