SSAVE was designed to identify sleep periods from the sleep-stage annotations that are embedded with EEG signals in data files in the EDF (European Data Format) format. The EDF file formats can be vendor dependent. SSAVE extracts epoch-based sleep stages from the embedded annotations provided by board-certified sleep technicians/doctors using all polysomnography data and employs our revised rules (Supplementary Table S1) (Feinberg and Floyd, 1979; Blume and Cajochen, 2021) to identify sleep periods. SSAVE outputs the hypnogram as a JPEG image and a listing of epoch-based sleep stages and sleep periods in text format. If EEG data are the input, SSAVE uses the EEG signals to automatically generate a multitaper spectrogram (Prerau et al., 2017) that is time-matched to the hypnogram. If sleep-stage annotations are not available in the EDF file, SSAVE can generate only the spectrogram but neither the sleep periods nor the corresponding the hypnogram. Alternatively, SSAVE can input user provided sleep annotations in text format and outputs only the hypnogram and listing (Figure 1).

With EEG data as input, SSAVE simultaneously divides the EEG signal data and sleep-stage annotations embedded in the EDF data into epochs commensurate with the annotation timestamps. An epoch size of 30 s is the default, but that value can be changed by the user. Any epochs without sleep-stage annotation, are removed from both the annotations and the signal data. SSAVE then constructs a hypnogram (a graph representing the stages of sleep as a function of time) using the annotations and identifies NREMPs and REMPs using its identification rules. It also generates a spectrogram using the EEG signal data aligned with the timestamps of the hypnogram. When a text file provides sleep-stage annotations as the only input, similar to SleepCycles, SSAVE constructs the hypnograms and identifies the sleep periods without generating the spectrogram. SSAVE currently requires sleep-stage annotations to identify sleep periods and construct a hypnogram.

An NREMP begins with an N1 or N2 stage, whichever appears first. A REMP begins with an R stage. The NREMP must be at least 15 min long. No minimum duration is required for the first REMP. All subsequent REMPs must be longer than 5 min. Short duration (i.e., < 5 min) R and W stages are allowed within NREMPs. Similarly, short duration of NREM and W stages are allowed within REMPs. NREMPs longer than 120 min are split with user feedback. Detailed rules are provided below.

SSAVE scans from low to high timestamps of the annotation epochs to detect a sleep period using a set of rules (Supplementary Table S1). We adopted most of the traditional rules used previously (Feinberg and Floyd, 1979; Blume and Cajochen, 2021) with the following five modifications.

(1) SSAVE does not explicitly define sleep cycles; instead, it defines the two types of component sleep periods, NREMP and REMP, separately. This approach differs somewhat from that of SleepCycle which considers a pair of NREMP and REMP together as a sleep cycle (Blume and Cajochen, 2021). This approach of focusing on individual sleep periods is useful. For example, the first NREMP is often not accompanied by a REMP for young adults. Moreover, NREMP and REMP have distinct characteristics such as duration and frequency, especially for younger subjects or those with sleep disorders (Ohayon et al., 2004; Galland et al., 2012). Treating NREMP and REMP separately, instead of combining consecutive pairs into cycles, enables one to obtain distinct features for each NREMP and REMP. This emphasis on sleep periods is also in accord with work suggesting that NREM and REM sleep have distinct regulation mechanisms (Le Bon et al., 2002).

(2) Like SleepCycles, SSAVE sets the minimum and maximum durations of an NREMP (excluding any internal W stages) to be 15 and 120 min, respectively. For an NREMP longer than 120 min, both tools accommodate splitting the NREMP (details below). This feature is important especially when a REMP does not occur between two NREMPs (Blume and Cajochen, 2021). Neither tool sets a maximum duration for REMPs. The minimum duration for a REMP is 5 min, although this restriction does not apply to the first REMP. If an NREMP is < 15 min long or a REMP (except the first one) is < 5 min long, SSAVE merges it into the adjacent respective sleep periods.

(3) The first NREMP ends upon encountering an R stage. All remaining NREMPs and all REMPs end, respectively, upon encountering consecutive REM and NREM stages of at least 5 min duration. There may be occasions when a person wakes up from sleep in the middle of an NREMP (REMP) for at least 5 min and falls back to sleep. In this scenario, SleepCycles considers the whole period as one NREMP (REMP). In contrast, SSAVE breaks the NREMP (REMP) into two NREMPs (REMPs) while omitting the W stages.

(4) In SSAVE, an NREMP may contain W stages if and only if the W stages are < 5 consecutive minutes long. When it encounters consecutive W stages lasting at least 5 min, SSAVE ends the current sleep period, removes the W stages, and begins a new sleep period. This rule allows SSAVE to properly handle EEG data with frequent W stages [e.g., EEG data for insomnia patients where the subject may wake up frequently in the middle of sleep cycles (Wei et al., 2017)]. In SleepCycles, all NREMPs may contain W stages regardless of their duration.

(5) An NREMP that is longer than 120 min is split at the first point of either arousal or “lightening of sleep”; but SSAVE and SleepCycles choose splitting points differently. SleepCycles splits at the end of the first N3 stage after at least 12 consecutive minutes of N1, N2 or W stages. SSAVE, instead, splits the NREMP at an “arousal” point defined by consecutive W stages exceeding 1 min or at a “lightening of sleep” point defined by consecutive N1 stages exceeding 3 min. Because these definitions may admit multiple splitting positions for a long NREMP, the user is provided the flexibility to choose the splitting positions by selecting the appropriate epoch number (in the web and desktop versions) or by typing it (in the command line interface). Note that a REMP does not have any maximum duration, thus, is never split.

Lastly, sleep-stage annotation may begin before sleep commences and continue after sleep ends; the annotation file typically includes these superfluous W stages. Both tools ignore W stages before the first NREMP and W stages after the last REMP or NREMP. Because newborns have unique sleep structures, these rules are more appropriate for individuals at least 1 year old.

SSAVE provides a multitaper spectrogram aligned with the sleep hypnogram in the visualization plot. A spectrogram is a frequency domain representation of EEG signal power through time as a heatmap. Its X-axis shows the time (in epochs), its Y-axis shows the frequency, and color indicates the relative signal power. SSAVE aligns its multitaper spectrogram with the epochs of the sleep hypnogram (Supplementary Figure S1, Section 1). This alignment can help users to identify useful sleep band features (e.g., alpha, beta, gamma, delta, theta waves), and sleep spindles (Paller et al., 2021) and map them to sleep periods.

SSAVE was developed with Python version 3. It can be imported either as a Python package or run as a standalone desktop application. We have also developed a web-based portal so that users can directly access the tool using a web browser. The web-based portal can be slower than the package or the desktop version, as it requires the user to upload an input file to the SSAVE server (https://manticore.niehs.nih.gov/ssave).

The web-based and the desktop-based applications present a similar user interface (Supplementary Figures S2–S6). Initially, the user will see a home window prompting for either one of the two data inputs: an EDF file containing EEG signals with embedded sleep-stage annotations; or a text file of only sleep-stage annotations having two columns, epoch number and sleep stage (“W,” “N1,” “N2,” “N3,” “R”) (Supplementary Figure S2A). The desktop-based and the command-line versions take the output directory as an additional input. Data are loaded when the “Load” button is clicked (Supplementary Figure S2B). The “Execute” button allows SSAVE to extract the sleep periods and generate the visualization figure and a listing of epoch-based sleep stages and identified sleep periods (Supplementary Figure S2C). The outputs are shown in the user interface under the “Visualization” and “Sleep Periods and Stages” tabs (Supplementary Figure S2D) and can be downloaded (See “Output” below).

SSAVE allows a user to split long NREMP (Supplementary Figure S3). When a NREMP is longer than 120 min, SSAVE searches for suitable epoch positions to split the period based on the arousal or lightening-of-sleep criteria mentioned earlier. If SSAVE finds such epoch positions, an additional tab “NREMP cut points” will appear (Supplementary Figure S3A). This tab shows a table of suitable epochs at which the long NREMP may be cut (Supplementary Figure S3B). User can select a cut option and click “Execute” to apply it (Supplementary Figure S3C). Once execution completes, the new outputs will show up with the split applied (Supplementary Figure S3D).

SSAVE uses default settings (Supplementary Table S2) to analyze the sleep periods, but the user can change the defaults in the settings window (Supplementary Figure S4). The settings window opens by clicking the “Configure” button at the home window after the input data are loaded. This window has four tabs corresponding to four categories of settings. In the “Select Channels” panel, the user can select their preferred EEG channels for analysis. The default settings contain eight channels: F3, F4, C3, C4, O1, O2, M1 and M2 (Supplementary Figure S4A). The “Select Sleep Stage” panel helps user to assign the proper annotations for the five sleep stages (Supplementary Figure S4B). User can also apply filters to remove noise and irrelevant epochs from the data using the “Set Filters” panel (Supplementary Figure S4C). The filters include two types of frequency filters (notch and bandpass); and three epoch filters (to remove epochs with maximum amplitude, flat signals, and unwanted annotations that do not bear useful information, e.g., bathroom breaks). The “Set Epoch Size” panel allows users to change the epoch size if the data provided as input was constructed with an epoch size different from 30 s (Supplementary Figure S4D). The user needs to re-run the analyses after changing the settings by clicking the “Execute” button at the home window. The filters can be optionally applied by checking the “Apply Filters” checkbox and then clicking the “Execute” button. All other settings will be automatically applied once the “Execute” button is clicked.

For machines without desktop support, SSAVE can be used as a command-line application. After running the tool, the user is prompted for the same inputs as above.

The SSAVE file “app_desktop.py” represents the desktop or command-line front end of the tool. The “utils.py” file contains the default settings of the tool. The “visualize_sleep.py” file can be imported as a Python package to use for further analysis.

SSAVE generates four outputs: the visualization figure (both hypnogram and spectrogram, or hypnogram alone, depending on input), a listing of epoch-based sleep stages, a listing of the sleep periods identified, and spectrogram data matrix containing epoch, frequency band and channel-wise EEG signal power data written to a NumPy file with “.npz” extension. The dimension of the spectrogram data matrix is (number of epochs x 901 x number of channels) (see Supplementary Method). The desktop-based and the command-line versions save output files in the user-specified output directory. The web-based application requires the user to download any files to be saved.

SSAVE mimics SleepCycles (Blume and Cajochen, 2021) in concept but offers several notable advantages. First, SSAVE was developed to be used easily in multiple platforms for users with or without programming skills. The web version provides a convenient platform for all users. SleepCycles requires familiarity with the R programming language. Second, both SleepCycles and SSAVE takes sleep stage annotations in text format as input, but only SSAVE takes EEG data with embedded sleep stage annotations as input. When EEG data are input, SSAVE outputs not only a hypnogram with the identified sleep periods but also the time-matched spectrogram. The spectrogram provides power in spectral bands that are characteristic of sleep periods. SleepCycles provides only a hypnogram. Third, SSAVE uses revised rules for identifying sleep periods to avoid including long consecutive W stages within any NREMP or REMP, in contrast to SleepCycles. Below, we provide three examples to illustrate these key differences.

In the first example, SleepCycles fails to exclude a long period (more than 5 min) of wakefulness in a sleep period (Figure 2A). In contrast, SSAVE breaks the current NREMP or REMP and starts a new one after excluding consecutive W stages (Figure 2B). As a result, SSAVE allows consecutive W stages within a sleep period only if their duration is < 5 min (10 epochs). This choice allows an NREMP or REMP to contain brief intervals of arousal or lightening of sleep without containing intervals where a subject is likely fully awake.

In the second example, for a long NREMP (more than 2 h), SleepCycles searches for the first N3 stage preceded by at least 12 min of consecutive N1, N2 or W stages and then splits the NREMP at the beginning of the N3 stage, resulting in two consecutive NREMPs (Figure 3A). Instead, SSAVE searches for the first N3 stage immediately preceded either by more than 1 min of consecutive W stages and splits the NREMP at the beginning of the N3 stage. Alternatively, it searches the for the first N3 stage following more than 3 min of consecutive of N1 stages and splits the NREMP at the beginning of the first N1 stage (Figure 3B). Because W or N1 stages precede deep sleep, SSAVE's rule provides reasonable place to split a long NREMP.

In the third example, SSAVE breaks a long sleep period, either NREMP or REMP, upon encountering more than 5 min of consecutive W stages and starts a new sleep period after their removal. This process divides long sleep periods, so that two consecutive NREMPs or two consecutive REMPs are possible. This possibility is one reason why SSAVE does not explicitly define a sleep cycle as an NREMP followed by a REMP.