Giter Club home page Giter Club logo

asleep's Introduction

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

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 {Yuan2023.07.07.23292251,
	author = {Hang Yuan and Tatiana Plekhanova and Rosemary Walmsley and Amy C. Reynolds and Kathleen J. Maddison and Maja Bucan and Philip Gehrman and Alex Rowlands and David W. Ray and Derrick Bennett and Joanne McVeigh and Leon Straker and Peter Eastwood and Simon D. Kyle and Aiden Doherty},
	title = {Self-supervised learning of accelerometer data provides new insights for sleep and its association with mortality},
	elocation-id = {2023.07.07.23292251},
	year = {2023},
	doi = {10.1101/2023.07.07.23292251},
	publisher = {Cold Spring Harbor Laboratory Press},
	URL = {https://www.medrxiv.org/content/early/2023/07/08/2023.07.07.23292251},
	eprint = {https://www.medrxiv.org/content/early/2023/07/08/2023.07.07.23292251.full.pdf},
	journal = {medRxiv}
}

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.

asleep's People

Contributors

angerhang avatar chanshing avatar leandrocasiraghi avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar

asleep's Issues

torch.cat(): expected a non-empty list of Tensors

This is very interested work, and we are interested in using the algorithm with some of our actigraphy data but have been running into an error. We are using .gt3x files and when running the code, the initial steps seem to work and a handful of outputs are produced: a raw csv, an info JSON file and 2 NPY files (data2model and times), but we then get the error: RuntimeError: torch.cat(): expected a non-empty list of Tensors.

Are you able to advise what the issue may be?

Merge info.json and summary.json into one

In contrast to other OxWearables packages, asleep produces an "info.json" file for actipy parameters and a "summary.json" file for the sleep-related parameters. I believe these two should be one file.

Also, the --remove_intermediate_files argument deletes "info.json", which I believe is wrong. It is not an intermediate file but an important part of the final output.

Dependency Pinning Missing, Compatibility Issues with Newer Python Versions, and Unhelpful Results

I've encountered several critical issues while attempting to use this project, which have significantly hindered my ability to effectively leverage its capabilities. These issues pertain to the lack of dependency pinning, compatibility problems with newer versions of Python, and the overall usefulness of the results produced. Below is a detailed account of each problem and its impact on my experience.

1. Missing Dependency Pinning

It took a while to finde the working dependencies. env.yml.txt

2. Incompatibility with Newer Python Versions

New versions just break it enirely.

3. Missing sample data

The project is missing sample data to verify that it works as expected.

4. Unhelpful Results

Testing muliple datasets the results were always 0 or a few minutes of sleep. As I cannot upload our samples the same happens with sample data from another issue:
#33 (comment)
Output:

Saving files to dir: outputs/sample
Raw data file already exists. Skipping raw data parsing.
   Unnamed: 0                           time         x         y         z  non_wear
0           0  2023-08-15 15:00:00.017000000 -0.461000  0.894996 -0.116996     False
1           1  2023-08-15 15:00:00.050333333 -0.443447  0.781798 -0.121022     False
2           2  2023-08-15 15:00:00.083666666 -0.527073  0.767216 -0.148742     False
3           3  2023-08-15 15:00:00.117000000 -0.605458  0.903918 -0.139534     False
4           4  2023-08-15 15:00:00.150333333 -0.689671  1.284508 -0.111031     False
Data2model file already exists. Skip data transformation.
data2model shape: (8640, 3, 900)
times shape: (8640,)
Non_wear flag shape: (8640,)
prediction set sample count: 8640
Using local /home/tobi/asleep/src/asleep/torch_hub_cache/OxWearables_ssl-wearables_v1.0.0
100%|████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 5/5 [01:38<00:00, 19.62s/it]
(8640,)
(array([0., 1., 2.]), array([5807,  451, 2382]))
                     time  label  is_wear
0 2023-08-15 15:00:00.017      0     True
1 2023-08-15 15:00:30.017      0     True
2 2023-08-15 15:01:00.017      0     True
3 2023-08-15 15:01:30.017      0     True
4 2023-08-15 15:02:00.017      0     True
No sleep windows >30 mins detected. Exiting...
Non-wear time has been written to outputs/sample/non_wear.npy
Current sleep classification has been written to outputs/sample/ssl_sleep.npy

Any thoughts @angerhang

double-check python version

Hang if you're using actipy I don't think Python 3.6 is supported.

image

Also the java check should be java -version

Input output format

The asleep package should behave the same way as the step count page at least in terms of input and output interface

  • Decide and implement the input output interfaces
  • Provide an interface with random forest and sleepnet

Add versioneer

Add versioneer to support for automatic publishing for version number increment

Parallelisation

Very interesting package, which I would like to use on data we collected with the Axivity devices. Do you have tips for parallelisation of the get_sleep command to speed up the analysis process of multiple files? I tried to use the command in a shell script using xargs for parallelisation but ran into an error thrown by the Java Runtime (see attached file).

hs_err_pid6048.log

TypeError: expected np.ndarray (got list).

Hey @angerhang , the last bug fix worked well. I have now got through the processing on all our files and have come across a couple of additional issues.

For a number of files we are getting the type error in the title - I have attached a txt output of this. This happens in the JR001.gt3x file that you had previously.

I am also seeing a less frequent issue where I run on a given file and it appears to start, produces the text Saving files to dir: outputs/'filename', but then stops processing and waits for the next file input. It appears that it does not successfully read the file. I didn't know if you may have come across this/had any immediate thoughts? If not I would plan to analyse all the data we can, if we can fix the type error issue and then if all is looking good with those work through everything we need to, to get some of our study files to you to see if you can replicate.

Inconsistent error.txt

proper documentation

Before we publish this package we should do the following:

  • Make the printout messages more helpful
  • Document how to use this package
  • Include the entry point get_sleep and visu_sleep
  • Fix pypi image

Extract StartTime and EndTime from .csv file

The monitoring StartTime and EndTime is automatically extracted for CWA files but not csv files, leading to a processing error.

Therefore, for csv files, we need to be able to extract this information from the provided 'time' column.

Add sleep start, sleep end and sleep mid point calculations

  • Calculate the sleep window, sleep window start, sleep window end, and non-wear time per day and the window midpoint
  • Test it on the participants that Harry shared so that we make sure that package will run for cases where when sleep end points are easier than the sleep start timestamps.

End2end test

Run the asleep package on some of the UKB files to see if the results line up

Update the model weights with the latest one.

Total sleep time feature support

Currently, the summary statistics only generate the sleep parameters for overnight sleep duration but not the for the total sleep time.

To do this, we will need to add the computation for all the sleep blocks for each day in the day class object.

Refactor get_sleep

Right now, get_sleep function is a bit messy.

We probably should clean it up soon/

Sleep parameters generation

Having obtained all the required sleep predictions, we will want to generate the common sleep parameters for the downstream analysis

  • Common sleep parameters included in the sleepnet paper: tst, se, ratio
  • Total sleep time: hourly , daily, weekday, weekend, overall averages
  • Check for NAs: at the moment all the NAs are non-wear from actipy. We would want to store the non-wear information in certain format that would allow to do QAs based on the non-wear threshold.
  • Test on UKB file

When dealing with NAs, it is probably to specify the the min_duration is 22 hours because it could be that at the start and the end of particular recording, we have a very short day hence also a short NA duration. This might change a bit of the statistics at the beginning and the end.

Incorporate sleep prediction

Having parsed the data into the right format, we will need to

  • Run the RF model to obtain sleep window
  • Run the sleepnet on continuous blocks of sleep periods

Non-wear detection fix

Actipy now renders all the non-wear as NA but this is not ideal because it is likely to yield false positives during sleep periods.

  • Disable non-wear detection from parsing using Actipy
  • Replicate non-wear detection in asleep
  • Correct false positive non-wear detection after the capture-24 model has been applied to account for non-wear periods within two blocks of sleep windows

Time Zone Corrections

Is there any chance you could add time zone correction argument(s) similar to GGIR/Accelerometer? Some of our watches were improperly configured, so their time zones need adjusted.

Thanks!

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.