Workflow for Unsupervised Clustering of Sleep States (WUCSS) is a novel workflow designed for unsupervised clustering of sleep states in rodents. It leverages accelerometer and electrophysiological data to classify different sleep states with high accuracy. The method enhances traditional sleep staging by introducing an unbiased approach, particularly excelling in discriminating between deep and light sleep states.
- About
- Motivation and Documentation
- Dependencies
- Dataset requirements
- Getting Started
- License
- Contributing
- Contributors
WUCSS is part of a larger Python workflow for analysing all kinds of electrophysiological data. The code presented here is tailored to run on the example dataset. All variables and directories are set up to run without any modification. This is to provide an example of how the code can be applied and to show the results the module produces. To use this module for other datasets, you will need to adjust some of the parameters.
The module is published in the Journal of Neuroscience Methods.
The repository complements the manuscript and provides a better understanding of how the WUCSS module works. It is a functional standalone module that can be used and modified by others who are interested. The dataset we provide is used in the manuscript to generate Figures 2 and 3. We hope that by providing the code for the module, other groups will be inspired, explore the module and ideally gain a better understanding of their data.
The WUCSS module is written in Python, and requires Python >= 3.8 to run.
It has the following required dependencies:
We further provide a .yml file to quickly set up the Python environment for the module (.yml file). The file contains all the Python libraries required for the module.
We recommend using the Anaconda distribution to manage these requirements.
-
File format: We provide functions that allow Python to handle the .nex5 file format, if other file formats are used, the code must be adapted accordingly. The .nex5 file format allows continuous data, such as an EEG signal, to be stored with annotated intervals, such as time stamps of when the animal was awake or asleep.
-
Electrode placement: Sleep classification was tested on EEG data from frontal and parietal EEG. Signals coming from other brain areas were not tested to classify the sleep state.
-
Behavioural state annotations: The module starts at a point where it expects the data to be annotated into awake and sleep states, therefore the file or another data source must provide timestamps of such annotations.
This repository runs on the example dataset. The steps to get the module to run on this example dataset are:
- Download the repository
- Install the dependencies, e.g. in an anaconda environment.
- Run the main task of WUCSS
- View results
Note: the example file is quite heavy (around 500 MB), as it represents a 24-hour recording. So both downloading and running the example will take some time, around 10-20 minutes depending on your PC.
WUCSS uses the Apache License 2.0.
The Apache License, Version 2.0, is a permissive open-source license that allows for the free use, modification, and distribution of software. It also includes patent grants, protecting users from patent litigation related to the software. The license is well-known and widely used in the open-source community.
First off, thanks for taking the time to contribute! Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make will benefit everybody else and are greatly appreciated.
Please read our contribution guidelines, and thank you for being involved!
Simon Gross |
Riccardo Cusinato |