Home

Overview

Dusk2Dawn allows you to easily clean whole-night sleep EEG using Artifact Subspace Reconstruction (ASR). As ASR must be calibrated using relatively clean reference data, and there is considerable variability in signal-to-noise ratio across and within sleep-stages, a standard ASR applied to the whole-night would lack sensitivity during lower-amplitude N1 and REM stages, while inappropriately removing large-amplitude brain signals such as slow-waves in N2 and N3 stages. Dusk2Dawn therefore implements two methods to solve this problem:

1. Running ASR separately for each sleep stage
2. Running ASR in a short sliding-window (e.g. 4 - 16 minutes).

The other main benefit of Dusk2Dawn is that it allows you to easily and automatically run ASR several times with different sets of parameters (e.g. different levels of ASR severity) and easily test the effects of each run-through on your data, before choosing which final dataset to use for your analysis. This can be achieved by plotting the data before & after ASR superimposed and also by plotting a range of validation metrics including Slow-Wave amplitude & consistency and reduction of power in particular frequency bands. This functionality is fully implemented in the graphical interface of Dusk2Dawn, so that anyone can perform this validation regardless of programming ability.

Together, these features of Dusk2Dawn make it a useful tool to clean whole-night sleep EEG, or indeed any long EEG recordings.

An explanation of how ASR works can be found on the github page for the clean_rawdata plugin for EEGLAB: https://github.com/sccn/clean_rawdata/blob/master/README.md

Please cite the following paper:

Somervail R, Cataldi J, Stephan AM, Siclari F, Iannetti GD. 2023. Dusk2Dawn: an EEGLAB plugin for automatic cleaning of whole-night sleep electroencephalogram using Artifact Subspace Reconstruction. Sleep. 1–14.

Requirements

* MATLAB
* EEGLAB 
* clean_rawdata plugin for EEGLAB (installed by default in recent versions) 

Installation

1. Add EEGLAB to your MATLAB path with the command:
   addpath [directory where you saved EEGLAB]
   e.g. addpath ‘C:\Toolbox\eeglab2022.1’

2. Start EEGLAB with the command: eeglab

3. Once EEGLAB is open you can install Dusk2Dawn using the built-in plugin manager by clicking: File -> Manage EEGLAB extensions and searching for “Dusk2Dawn”

Manual Installation: Download zip from GitHub, extract the folder and copy it into the plugins subfolder of your eeglab directory.

How to use

1. First you must load your data into EEGLAB by either importing raw data (File -> Import data) or by loading an existing dataset (File -> Load existing dataset).

2. Before performing ASR, your data must be appropriately high-pass filtered with a low cutoff of at least 0.5 Hz (Tools -> Filter the data -> Basic FIR filter). For more information about this step visit: https://github.com/sccn/clean_rawdata/blob/master/README.md

3. You can now clean your data with ASR and explore the effects of ASR on your data before progressing to your analysis. Both of these steps can be performed in one click: Tools -> Dusk2Dawn -> Dusk2Dawn - Run all core functions

Handling multiple datasets in a memory efficient way

All functions in Dusk2Dawn can be run with multiple datasets selected so that you can save yourself the extra time of manually running everything for each subject.

However, since whole-night EEG is very memory intensive, to do this you must change your EEGLAB preferences so that only one dataset is stored in memory at a time.

To handle multiple datasets in a memory efficient way:

1. Go to EEGLAB -> File -> Preferences, and check the box labelled "If set, keep at most one dataset in memory".

2. Load multiple datasets and then go to EEGlab -> Datasets -> Select Multiple Datasets, before running Dusk2Dawn cleaning & validation functions.

Clean the data

First you must choose the ASR parameters for the cleaning. The most important parameter here is the cutoff value. This determines the ASR severity, i.e. how much larger artifacts must be than signal to be removed by ASR, and is expressed in standard deviations (SD). In sleep we have found values from 30 to 45 SD are appropriate to avoid removing Slow Waves.

• You can vary up to 3 parameters in this screen by entering a range of values like this: [ 30, 35, 40, 45 ]

• Advanced settings can also be found by clicking the popup buttons, but for most users this is unnecessary.

Second, you must choose the ASR implementation. By default the data will be segmented by sleep stage and ASR performed in a sliding-window. You must specify the events in your dataset which correspond to sleep stages using the selection box. You can also vary the sliding window length and overlap, although the default settings are probably fine here.

Third you can choose which additional validation metrics you would like to compute before & after cleaning. These include:

1. How much variance ASR removed from the data (computed by default)

2. Power by frequency band

3. Slow-wave amplitude and consistency (here you can either select previously-loaded events in your dataset which correspond to SW events or automatically detect them in each dataset)

4. Quality of Independent Component Analysis (ICA) decomposition using IClabel. This allows you to judge how much ASR has removed artifacts which are difficult to classify using ICA (labelled ‘unknown’ components) and how much of the data is comprised of brain activity.

Evaluate the results & apply ASR cleaning

After the data has been cleaned using ASR with the select set(s) of parameters, you can visualise the data before & after ASR, and plot the computed validation metrics.

Once you are happy with your ASR parameters you can apply the chosen ASR to your data and proceed with your analysis!