IntelliSleepScorer, a Software Package with a Graphic User Interface for Mice Automated Sleep Stage Scoring

Summary

We present a software package with a graphic user interface for researchers without coding experience to score sleep stages in mice with a simple download and operation.

Abstract

Sleep stage scoring in rodents is the process of identifying the three stages: nonrapid eye movement sleep (NREM), rapid eye movement sleep (REM), and wake. Sleep stage scoring is crucial for studying sleep stage-specific measures and effects.

Sleep patterns in rodents differ from those in humans, characterized by shorter episodes of NREM and REM interspaced by waking, and traditional manual sleep stage scoring by human experts is time-consuming. To address this issue, previous studies have used machine learning-based approaches to develop algorithms to automatically categorize sleep stages, but high-performing models with great generalizability are often not publicly available/cost-free nor user-friendly for non-trained sleep researchers.

Therefore, we developed a machine learning-based LightGBM algorithm trained with a large dataset. To make the model available to sleep researchers without coding experience, a software tool named IntelliSleepScorer (v1.2- newest version) was developed based on the model, which features an easy-to-use graphic user interface. In this manuscript, we present step-by-step instructions for using the software to demonstrate a convenient and effective automatic sleep stage scoring tool in mice for sleep researchers.

Introduction

Sleep stage scoring in rodents is the procedure to identify the three stages: non-rapid eye movement sleep (NREM), rapid eye movement sleep (REM), and wake². In rodents, NREM is characterized by reduced muscle activity, slow and regular breathing, decreased heart rate, and low-frequency oscillations of the brain waves. REM in rodents, similar to humans, shows muscle atonia, EEG activation, and rapid eye movements, although the occurrence of vivid dreaming is less clear in rodents compared to humans^2,3. The "wake" state in rodents is marked by desynchronized brain activity with high-frequency, low-amplitude waves, increased muscle tone, and active behavior, such as grooming and exploration⁴. These three stages can be identified by inspecting electroencephalogram (EEG) and electromyogram (EMG) signals⁵.

The automatic sleep stage scoring models in rodents are in great need. First, manual sleep stage scoring by human experts is labor-intensive and time-consuming. Secondly, sleep patterns in rodents differ from those in humans and have more fragmented episodes of NREM and REM interspaced by waking, around 10 min, in contrast to 60-120 min in humans⁶. Therefore, identifying these brief periods during manual scoring is challenging. There have been many attempts since the 60s to develop an automatic scoring system of rodent sleep data⁷. Although many automated rodent sleep scoring methods exist, their performances vary^{8,9,10,11,12,13,14,15,16,17,18}. Importantly, most high-performing models with high generalizability are not publicly available (some need special requests from developers) or are not cost-free for sleep researchers.

Therefore, to fill the current technology gap, we developed a machine learning-based model using a large dataset of 5776 h of EEG and EMG signals from 519 recordings across 124 mice with the LightGBM algorithm¹. The lightGBM uses a gradient-boosting approach to construct decision trees¹⁹. In Wang et al., 2023, the LightGBM model (consisting of over 8000 decision trees) achieved an overall accuracy of 95.2% and a Cohen's kappa of 0.91, which outperformed two widely used baseline models such as the logistic regression model (accuracy = 93.3%) and the random forest model (accuracy = 94.3%, kappa = 0.89). The overall performance of the model also displayed a similar performance to that of human experts. Most importantly, the model has been proved to have generalizability and not overfitted to the original training data¹: 1) It performed well (accuracy > 89%) on two other publicly available independent datasets, from Miladinovic and colleagues¹¹, with different sampling frequencies and epoch lengths; 2) The performance of the model is not impacted by the light/dark cycle of mice; 3) A modified LightGBM model performed well on data containing only one EEG and one EMG electrode with kappa ≥ 0.89; 4) Both wildtype and mutant mice were used for the testing and the performances of the model were both accurate. This suggests the model can score sleep stages for mice with different genetic backgrounds.

In order to make this model accessible to sleep researchers who may not have coding expertise, we developed IntelliSleepScorer, a user-friendly software tool with a visually intuitive interface. The software can fully automate the sleep-scoring procedure in mice. It produces interactive visualizations of the signals, hypnogram, and Shapley Additive exPlanations (SHAP) values from an European data format (EDF)/EDF+ file input. The SHAP value approach, based on cooperative game theory, enhances the interpretability of machine learning models²⁰. The model offers both global and epoch-level SHAP values, revealing how different feature values contribute to the scoring decision of the model overall and for each epoch. This advanced program significantly reduces the time and effort required for sleep stage scoring in mice while ensuring that downstream analysis can rely on highly accurate results. In this manuscript, we present step-by-step usage of IntelliSleepScorer (v1.2) with several updates upon version 1.0, including an option to run SHAP analysis separately from sleep pattern prediction, an user adjustable epoch length for sleep stage scoring, and a sleep stage manual correction feature integrated within the GUI.

Protocol

This study used data collected from in vivo experiments in mice. No human experiments were involved in the study. All the experiments with animals were approved by the Institutional Animal Care and Use Committee at the Broad Institute. All experiments were performed in accordance with relevant guidelines and regulations. The ARRIVE guidelines are not applicable to this study because the focus of this study is to develop machine learning models rather than comparing different treatment groups.

1. Data preparation

NOTE: Data compatibility: the recorded data can have any sampling rate higher than 40 Hz. There is no need to bandpass filter the signal because the software bandpass filters the EEG and EMG signals at the first step. The LightGBM models were developed and tested using data from mice. No evidence regarding the performance of the LightGBM models in other types of lab animals is available. The recording electrodes need to be placed at the frontal and the parietal cortex, or either place if only one EEG channel is recorded.

1. EDF/EDF+ format arrangement and requirement
   NOTE: The software used in this study only reads EDF/EDF+ files using the MNE-Python package. The standard EDF/EDF+ specification needs to be applied to generate the EDF/EDF+ files. In addition to the standard specification, ensure that the EDF/EDF+ annotations are encoded in UTF-8. Otherwise, the software application will crash.
   1. Convert another file (non-EDF/EDF+ file) format into EDF/EDF+ format with online free tools.
      NOTE: There is no requirement for the apparatus filter when obtaining EEG and EMG signals. As long as users sample their EEG and EMG data at a frequency of 40 Hz or higher, the software will function correctly. This is because, in the initial preprocessing step, the signals undergo bandpass filtering between 1 Hz and 40 Hz. This bandpass filtering is integrated into the software's preprocessing pipeline, eliminating users needing to perform any additional signal processing.
2. There are two models inside the software for scoring. One is LightGBM-2EEG, and the other is LightGBM-1EEG. The LightGBM-2EEG model is designated for recording data that has 2 EEG channels and 1 EMG channel. Perform the following steps depending on the model.
   1. Organize data files for LightGBM-2EEG specifically in the following order: 1) EEG channel recorded in the parietal area; 2) EEG channel recorded in the frontal area; 3) EMG channel. The LightGBM-1EEG is designated for data that only contains 1 EEG channel (electrode placement on either parietal or frontal area) and 1 EMG channel.
   2. Organize the channels in EDF/EDF+ files for LightGBM-1EEG in the following order: 1) EEG channel; 2) EMG channel.

2. Downloading IntelliSleepScorer for Windows, Mac, and Linux users

1. For Windows users, a Windows Executable for the software is available using PyInstaller. Find the download link on the Pan group research page https://sites.broadinstitute.org/pan-lab/resources. For MacOS or Linux users, use the source code on the GitHub repository https://github.com/broadinstitute/IntelliSleepScorer to launch the software. 
2. Access two recorded example data to test the program saved as EDF files by downloading them through the GitHub repository.
3. The source code repository does not include the models folder due to size limits. Instead, download models.zip, unzip it, and copy the models folder inside the repository for the program to run. Otherwise, the software will crash due to missing model files.

3. Workflow and Program launch and operation

1. Launch IntelliSleepScorer
   1. To launch the software in Windows, double-click IntelliSleepScorer.exe located in the root folder. To launch the software in MacOS or Linux, open a terminal emulator, change the directory to the root folder of the software, and then launch the software using the command: python3 IntelliSleepScorer.py.
2. Once the software opens, click Select EDF/EDF+ File(s) to select the intended file(s) to score. If files were selected by mistake, click the Clear button to clear the selected file list.
   NOTE: By default, the software encodes the sleep stages as Wake:1, NREM:2, and REM:3 in the output score files. The default epoch length is set at 10 s. The current version (v1.2) of the GUI allows users to change stage encodings or epoch lengths to 4 s, 10 s, or 20 s with the dropdown menu.
3. Select the desired epoch length. Use the provided dropdown menu to select the intended epoch length among options of 4 s, 10 s, and 20 s for sleep stage scoring.
4. Select the model that is to be used for sleep scoring. LightGBM-2EEG is intended for data files with two EEG channels and one EMG channel, while the LightGBM-1EEG is designed for data with one EEG channel and one EMG channel.
5. Before running the sleep stage prediction, include the additional SHAP calculation that helps explain the sleep stage prediction results. To process the SHAP calculation, check the Run/Plot SHAP checkbox. The SHAP calculation requires around 5-10 min to process.
6. Click Score All Files. The model automatically scores all the EDF/EDF+ files and calculates the global and epoch SHAP values to interpret the scoring decisions in the list if that is chosen to do so.
   NOTE: During the scoring process, the model generates the following files and saves them to the same folder where the EDF/EDF+ files are located. The model uses these files to plot the global SHAP values and epoch SHAP values.
   
   "EDF/EDF+ file name}_{model_name}_features.csv"; this file stores all the extracted feature values.
   "EDF/EDF+ file name}_{model_name}_scores.csv"; this file stores the predicted sleep stages.
   "EDF/EDF+ file name}_{model_name}_rs_100hz.npy"; this file stores a copy of the resampled/downsampled signals (100hz). To improve the visualization speed, the model uses the downsampled signal instead of the original signal when plotting the signal.
   "​EDF/EDF+ file name}_{model_name}explainer. pickle"; "{EDF/EDF+ file name}{model_name}shap_500samples.pickle"; "{EDF/EDF+ file name}{model_name}_indicies_500samples.npy";
7. After finishing the sleep scoring process, click on the Visualize the Selected File option to visualize the EEG/EMG signals and a hypnogram time-aligned with the signals.
   1. Score the selected file again before visualization if the epoch length is changed.

4. Navigating the scored results

1. Click the provided Navigation buttons to move forward and backward to see different epoch data.
2. If SHAP calculation is chosen to be performed, view both the global and epoch-level SHAP values. Right-click on an epoch to plot the epoch-level SHAP values.
   NOTE: It will take a few seconds to update the epoch-level SHAP plot. Figure 1 shows the GUI page overview after running the prediction for Example-1 EDF/EDF+ file with 1_LightBGM-2EEG model.

5. Interpretation of the scored sleep stages hypnogram

NOTE: There are 4 rows in the hypnogram (Figure 2). The top row is the predicted results. The bottom 3 rows are raw data of 2 EEG and 1 EMG channels, respectively. On the top row, orange suggests the Wake stage, blue suggests the NREM stage, and red suggests the REM stage in each epoch.

1. To change the number of the epochs to display, click on the menu box on the right of Select Number of Epochs to Display and choose a desired value. In Figure 2, 100 epochs were chosen. Therefore, only 100 epochs are displayed in the sleep stage prediction plot. Select a smaller number in the dropdown menu to zoom into the plot.
2. The pink transparent bar on the left of Figure 2 indicates the current location of the epoch. Left-click on any place on the hypnogram to switch to another epoch, or simply click on Go to Epoch and enter a specific number of epochs to be observed. Right-click the selected epoch to generate its epoch SHAP plot if the user has enabled the SHAP function.

6. Manual correction of the predicted sleep stages on GUI (Optional)

NOTE: if no anomaly is observed or extremely high accuracy is not required for REM stage prediction, manual verification is not needed.

1. Left-click on an epoch in the sleep stage prediction plot (top plot) to select a specific epoch. The model predicted Stage of Selected Epoch is shown on the right of the text. To manually change the predicted stage on that epoch, click on the widget and select a new stage from the Wake, NREM, and REM options in the dropdown menu.
2. The user-corrected stages are marked with dashed lines on top of the original plot (Figure 3). Close the GUI, and a new file with corrected prediction results will be automatically generated in the same folder.
   1. To open a saved scored file on the GUI again, ensure that the epoch length setting and the selected model match the one used when the EDF file was initially processed to be able to reopen it. All the previously modified/scored information will be quickly loaded.

Results

There are three plots (only the top plot if SHAP values were not run) generated in the GUI after sleep stage scoring: the top plot presents EEG and EMG channels with a hypnogram of sleep stage prediction. The middle plot presents epoch SHAP values. The bottom plot presents Global SHAP values (Figure 1).

There are 4 types of data presented in the sleep stage prediction hypnogram plot (Figure 2). The top row is the predicted results. Th...

Discussion

This paper presents how to use the IntelliSleepScorer (v1.2) graphic user interface to automatically score the sleep stages of mice and how to leverage SHAP values/plots to better understand the sleep stage scores generated by the model.

An important consideration when using the software is data compatibility. The in-house data used in this study was limited to electrodes placed in the frontal and parietal regions. In the independent dataset from Miladinovic and colleagues^11<...

Materials

Name	Company	Catalog Number	Comments
Canonical Unbuntu 18.04	Canonical	https://releases.ubuntu.com/18.04/	Supporting Operating System for the software IntelliSleep Scorer: Windows, Mac, or Linux
Intel Core i7-8550U CPU @ 1.80 GHz 1.99 GHz; RAM: 24 GB	Intel Corp	https://www.intel.com/content/www/us/en/products/details/processors/core-ultra.html	Hardware requirment for the software: Both Inte Core listed here have been used to process the data. It takes around 10 min to process 12 h of recording sampled at 1000 Hz for both hardwares. Any similar or superior hardware would yield comparable or better performance.
Intel Core i7-10610U CPU @1.80 GHz 2.30 GHz; RAM: 16 GB	Intel Corp	https://www.intel.com/content/www/us/en/products/details/processors/core-ultra.html	Hardware requirment for the software: Both Inte Core listed here have been used to process the data. It takes around 10 min to process 12 h of recording sampled at 1000 Hz for both hardwares. Any similar or superior hardware would yield comparable or better performance.
LightGBM	Microsoft	https://lightgbm.readthedocs.io/en/latest/index.html	Machine learning-based algorithm that was used to train the software.
MacBook Pro	Apple	https://www.apple.com/in/macbook-pro/	Supporting Operating System for the software IntelliSleep Scorer: Windows, Mac, or Linux
Windows	Microsoft	https://www.microsoft.com/en-in/windows/?r=1	Supporting Operating System for the software IntelliSleep Scorer: Windows, Mac, or Linux