See the LICENSE file for license rights and limitations. By downloading and/or installing this software and associated files on your computing system you agree to use the software under the terms and condition as specified in the License agreement.
This MATLAB toolbox implements an algorithm based on the Multi-channel Wiener Filter (MWF) for processing multi-channel EEG as published in [1]. The algorithm removes any type of artifact marked a-priori by the user from the EEG in order to enhance signal quality for further processing.
The functions of the MWF toolbox can be used either
-through a graphical user interface (see GUI manual) -directly in your own scripts or from the MATLAB command window (see MWF manual). Manual marking of artifacts can be done in EEGLAB (Make sure EEGLAB is added to the MATLAB path: you can check this by typing "eeglab" in the command window)
NOTE: Scripting + EEGLab was developed and tested in MATLAB R2015a. The use of the GUI in V2.0 requires MATLAB R2018b
All functions are documented properly in their respective m-files. Additional documentation and examples can be found in:
- For the GUI: gui folder, which contains a manual in pdf format and demo data to illustrate the usage of the various functions. Open the GUI with the file main_GUI.m.
- For scripting: doc folder, which contains a manual in pdf format and a MWF demo file to illustrate the usage of the various functions. A quick start guide is provided below.
NEW: Release 2.0 includes a GUI to mark artifact segments, apply the MWF and inspect signals during the process. Use of the GUI is an optional alternative to using MWF functions from the MATLAB command line/scripts or with EEGLAB for manual marking of artifacts (see below). Open the GUI with the file main_GUI.m.
More information about functionality and usage can be found in the included GUI manual, which includes a quick start guide on demo data.
The MWF GUI requires MATLAB version R2018b or later (scripting with MWF functions (see below) also works with older versions of Matlab).
All functions needed to perform MWF-based EEG artifact removal are in the mwf folder. Before starting, make sure that this folder is added to the MATLAB path. The MWF first requires examples of EEG with and EEG without artifacts. Based on this segmentation of the EEG data, the MWF can be computed and applied in order to remove the artifacts. This two-step approach is fully implemented in the toolbox.
Step 1: EEG segmentation. In the toolbox, this step is performed by manual marking of the data using EEGlab. If you have your EEG data matrix in the the MATLAB workspace (channels x samples), you can create(*) the artifact mask by calling
mask = mwf_getmask(EEG, samplerate); [requires EEGLAB to be installed (**)]
A pop-up window will appear in which artifacts can be marked by clicking and dragging over them. When done, clicking the 'Save Marks' button will close the pop-up window and the function returns a binary (1 x samples) mask. In this mask, ones correspond to artifact segments, and zeros correspond to clean data. Optionally, the mask may contain NaNs which indicate segments to be ignored from the MWF computation (i.e. they belong neither to the artifact nor the clean segments). Section 4.1.4. of the manual contains extra tips on annotating artifacts.
(*) The artifact marking/detection step is not inherently a part of the MWF algorithm: if you prefer, you can also use a different method for acquiring the artifact mask (e.g. an automatic method, for example based on thresholding,. . . ). The mask needs to consist of ones, zeros and NaNs, and must have the same length as the EEG data.
(**)The function mwf_getmask requires EEGLAB to be installed (only required for manual marking of artifacts): EEGLAB website. (Make sure EEGLAB is added to the MATLAB path: you can check this by typing "eeglab" in the command window)
Important note: all segments that are not marked and come before the lasted marked segment will be treated as artifact-free samples in the training of the filter. The samples that come after the last marked segment are not used in the filter design. In other words: the filter design assumes that all artifacts before the last marked artifact are marked.
Because samples after the lasted marked segment are ignored, it is not necessary to go through the entire signal to mark all the artifacts. It is sufficient to annotate only the first few seconds or minutes of the signal. However, the more artifacts are marked, the better the filter design will be. Additionally, there should be enough clean (unmarked) segments before the last marked artifact for a good filter design.
Step 2: MWF artifact removal is performed by calling the mwf_process function. It requires the EEG data, the mask indicating which segments are artifacts, and optionally a delay parameter:
clean_EEG = mwf_process(EEG, mask, delay);
More parameters than the delay value can be changed and used by setting them in a struct using mwf_params() function and passing this struct to the mwf_process function:
params = mwf_params(...
'delay', 5, ...
'delay_spacing', 2);
clean_EEG = mwf_process(EEG, mask, params);
This will return the artifact-free EEG in the clean EEG variable. Using a delay greater than zero includes temporal information into the filter, leading to better artifact removal but may increase processing time. If omitted, the default value is zero. See [1] for more details.
A contribution made by Neil Bailey (Monash University) suggests that MWF cleaning can be improved by using sparse delay spacing. For example, instead of using consecutive delays [-3 -2 -1 0 1 2 3], it is now possible to specify the "delay_spacing" parameter to create a sparser sampling such as [-9 -6 -3 0 3 6 9], which is obtained with "delay = 3" and "delay_spacing = 3". This is also useful to include more relevant samples when your data has a higher sample rate.
From informal testing by Neil Bailey, for data sampled at 1000Hz, optimal performance at cleaning eye blink artifacts was obtained by using a delay parameter setting of 8 (so that 8 positive & negative delays are included in the MWF ), as well as a delay spacing of 16 (so that each delay is separated from the previous delay by 16 samples or 16 milliseconds). This provides the MWF algorithm with delay embedded covariance matrices that characterises 272ms of the data, enabling the MWF algorithm to account for a considerable proportion of each blink period. For muscle artifact cleaning of data sampled at 1000Hz, a delay period of 10 and delay spacing of 2 was found to be optimal.
To use this functionality, the delay_spacing parameter can be set using the mwf_params function (as in the example above).
[1] Somers, B., Francart, T. and Bertrand, A. (2018). A generic EEG artifact removal algorithm based on the multi-channel Wiener filter. Journal of Neural Engineering, 15(3), 036007. DOI: 10.1088/1741-2552/aaac92