Mora sleep analysis

video walkthrough

Setup

Run python -m pip install -r requirements.txt

Running sample data

1. Run python Mora.py
2. Make sure that your files are exported as '.wav'
3. Click Load Data and select sample_signal.wav in the sample data folder
4. NEW: Add in date and time for light/dark cycle in the pop-up window.
5. Click on the EEG graph and press the left and right arrow keys to move through the data
6. To see some example scores, click Load Scores and select sample_scores.txt in the sample data folder
7. Press W (wake), E (NREM), R (REM), T (unscored) to change the scores manually and save scores to a .txt file by clicking Export Scores
8. Now let's use machine learning to automatically score the data - clear the current scores by clicking Clear Scores
9. In the model tab, click Load Model and select the .pkl file in sample data folder, then click Score Data
10. A window will pop up, pre-populated with the number 2, click "Ok" and wait a few moments
11. Go back to the home tab to see how well the model worked!

In this repo...

• sample_data: This folder contains sample EEG/EMG data, example scores, and the classification model saved as a .pkl file
• Mora.py: This file contains the PyQT code for running the application, including all plots, buttons, etc. See the walkthrough video above!
• model/: This folder contains all the code to train and save models.
• data_processing/: This folder contains the modules needed for feature engineering and data pre-processing.
• data_converting/: NEW: This folder contains modules for converting your already scored data output from another program into a Mora-friendly format
• customizations/: COMING SOON: This folder contains modules with additional figure customization options, including color gradient hypnograms.
• requirements.txt: Dependencies for running this program

Background

Our lab studies sleep in the context of addiction and dopamine. One of our recent publications shows that dopamine uptake rates vary across the sleep/wake cycle, and more recent data from our lab indicate that restoring sleep during withdrawal from cocaine reduces drug craving and normalizes striatal dopamine transmission. Pretty neat!

As cool as sleep studies may be, in our lab they have historically been a pain to do. We hand-score all of the sleep data, assigning each 10 second bin a score of Wake, Non-REM, or REM. Scoring this way takes ~1 hour per 24hr recording. Considering we record each animal for 7+ days, that's 7+ hours of labor to score the data from just one rat. My first goal for this project was to create a ML model that could automatically generate scores from the raw data. This has cut our analysis time down from 7 hours to several minutes per rat.

The next issue to solve was related to the software we had been using to view and score our data. The program was slow, buggy, and prone to crashing. And upgrading to its newest version would have cost a lot of $$$. As an alternative I generated a GUI in which users can load raw data and view plots containing eeg/emg signals, a hypnogram, a power spectrum, and a simple bar plot. This required learning PyQt and took a lot of trial and error - but it was worth it!

In the end I was able to combine the model and the GUI, so that the user can load a file, score it instantly, and then cruise through the data and see how well the model performed. See the walkthrough video above for a demonstration. We're calling this program Mora, after the demon from slavic mythology that causes nightmares 😵.

Future additions will include options to train a new model, evaluate model performance, and run batch analyses to make things even faster.

2025 Updates

In this latest version, we have made 4 big improvements to the model and analysis outputs!

1. We improved the accuracy of the model-assigned scores for more noisy EEG/EMG recordings by providing better training data.
2. We have now included the option to add light/dark cycles into the GUI with 'Load Data' so that analysis of light and dark cycle effects is super simple now. We realized that some other softwares actually misrepresent the light/dark cycle metrics because they do not separate a bout that starts during light or dark but ends in the opposite phase. You can imagine this would greatly skew data if a rat woke up 1 min before the start of the dark cycle but stayed awake for an hour, with the whole hour being counted for the light phase instead of the dark phase.
3. We now provide options to upload your already scored data from two major sleep software output formats in a "Mora-friendly" format. This allows you to use our figure-making features and correct for the light/dark phase quantification issue (described above) with your own data.
4. The BIG update here is the inclusion of new analysis and output functions. We now have the option to output relative percent of total time per phase (24hr, 12hr light, 12hr dark) for each state (wake, non-REM, REM), total number of bouts per phase for each state, average bout duration per phase for each state, and number of transitions between states per phase. This now offers a robust analysis output comparable to very costly sleep scoring softwares with the improved light/dark accuracy (described above).

Future updates will include options to customize the hypnograms with color gradients for figure making, option to compare data to the same individual's baseline scores with statistical analyses, batch processing for faster scoring and analysis, and a GUI for user-friendly model traning with your own data.

Disclaimer: This model was trained on hand-scored data from rat EEG/EMG recordings with an intracranial implant and tethered set up. Data collected from other systems (i.e. wireless telemetry) may vary from ours but should not differ so much as to render the model inaccurate. However, it is best to validate that our model's scores match your lab's standard.