Zapline plus user guide

Installation

The package is completely standalone and has no dependencies. You can install it in two ways:

1. Download the latest release version and unzip it into your MATLAB path.
2. If you use EEGLAB, you can instead directly go to the EEGLAB plugins manager and download it from there.

The algorithm

The algorithm is explained in detail in our paper, this figure sums up the processing:

Using the tool

It is recommended to use Zapline-plus on data sampled between 250 Hz and 512 Hz. It is also recommended to use Zapline-plus very early in the processing, ideally as the first step, before average referencing and before removing bad channels or samples, as it might recover data that would otherwise be lost. It has an internal check to be able to deal with flat channels.

From the command line

If you have your data in any data matrix in MATLAB you can process it with zapline-plus, as long as you also know the sampling rate. To do so, run this command (no need to transpose the data, this is done internally and the shape is preserved):

cleanedData = clean_data_with_zapline_plus(data,srate);

If you want more control over the processing than using defaults you can add parameters in key-value format. For example, this setting replicates the default original Zapline behavior (no chunking, no adaptive cleaning strength, fixed removal of 3 components over the entire data):

cleanedData = clean_data_with_zapline_plus(data,srate,'noisefreqs',50,'adaptiveNremove',0,'fixedNremove',3,'chunkLength',1e9);

If you have your data in EEGLAB structure, you can also use zapline-plus like this:

[EEG plothandles] = clean_data_with_zapline_plus_eeglab_wrapper(EEG,struct('noisefreqs','line')) % specifying the config is optional and can be done as above

The advantage of this case is, that all used parameters are stored in the EEG struct and can be found in EEG.etc.zapline. Specifying the plothandles output is optional and allows saving the plot on disk.

From the EEGLAB GUI

If you have installed Zapline-plus via the EEGLAB plugins manager, you can find the Zapline-plus noise removal option in the Tools section of EEGLAB. Running this tool gives you a GUI option to use Zapline-plus with the most relevant parameters to be adjusted:

The Zapline-plus parameters in detail

While Zapline-plus is created with the aspiration of no necessary parameter adjustment, it still offers detailed and exhaustive adjustments of all used parameters to tune the cleaning to everyone's need if the default settings do not work. The parameters and the reasoning for default choices are explained in our paper, here is an excerpt to explain all options and our reasoning for their default values:

• noisefreqs (default = empty): Vector with one or more noise frequencies to be removed. If empty or missing, noise frequencies will be detected automatically. If set to the string 'line', only line noise in either 50 or 60 Hz (automatic selection) is detected and removed. Individual chunk peak detection will still be applied if set.
• minfreq (default = 17): Minimum frequency to be considered as noise when searching for noise frequencies automatically. We chose this default as it is well above the potentially problematic range of alpha oscillations (8–13 Hz) and also above the third subharmonic of 50 Hz, which was present in some MEG data sets.
• maxfreq (default = 99): Maximum frequency to be considered as noise when searching for noise freqs automatically. We chose this default as it is below the second harmonics of the 50 Hz line noise. If the line noise cannot be removed successfully in the original frequency, trying to remove the harmonics can potentially lead to overcleaning.
• adaptiveNremove (default = true): Boolean if the automatic detection of number of removed components (Section 2.4) should be used. If set to false, a fixed number of components will be removed in all chunks. As this is a core feature of the algorithm it is switched on by default.
• fixedNremove (default = 1): Fixed number of removed components per chunk. If adaptiveNremove is set to true, this will be the minimum. Will be automatically adapted if “adaptiveSigma” is set to true. We chose this default to remove at least one component at all times, no matter whether or not a noise oscillation was detected per chunk, as the detector can fail to find an oscillation that should be removed, and removing a single component does not lead to a large effect if no oscillation was present in the chunk.
• detectionWinsize (default = 6): Window size in Hz for the detection of noise peaks. As the detector uses the lower and upper third of the window to determine the center power (Section 2.3) this leaves a noise bandwidth of 2 Hz. In our tests, some data sets indeed had such a large bandwidth of line noise, which can occur if the noise varies in time.
• coarseFreqDetectPowerDiff (default = 4): Threshold in 10log10 scale above the center power of the spectrum to detect a peak as noise frequency. If this is too high, weaker noise can go undetected and thus uncleaned. If it is too low, spurious peak oscillations can be wrongfully classified as noise artifacts. This default corresponds to a 2.5-fold increase of the noise amplitude over the center power in the detection window which worked well in our tests.
• coarseFreqDetectLowerPowerDiff (default = 1.76): Threshold in 10log10 scale above the center power of the spectrum to detect the end of a noise artifact peak. This is necessary for the noise frequency detector to stop. This default corresponds to a 1.5× increase of the noise amplitude over the center power in the detection window which worked well in our tests.
• searchIndividualNoise (default = true): Boolean whether or not individual noise peaks should be applied on the individual chunks instead of the noise frequency specified or found on the complete data (Section 2.3). As this is a core feature of the algorithm it is switched on by default.
• freqDetectMultFine (default = 2): Multiplier for the 5% quantile deviation detector of the fine noise frequency detection for adaption of SD thresholds for too strong/weak cleaning (Section 2.3). If this value is lowered, the adaptive changes of Section 2.5 are stricter, if it is increased, these adaptations happen more rarely.
• detailedFreqBoundsUpper (default = [−0.05 0.05]): Frequency boundaries for the fine threshold of too weak cleaning. This is also used for the search of individual chunk noise peaks as well as the computation of analytics values of removed power and the ratio of noise power to surroundings. Low values mean a more direct adaptation to the peak, but too low values might mean that the actual noise peaks are missed.
• detailedFreqBoundsLower (default = [−0.4 0.1]): Frequency boundaries for the fine threshold of too strong cleaning. Too strong cleaning usually makes a notch into the spectrum slightly below the noise frequency, which is why these boundaries are not centered around the noise peak.
• maxProportionAboveUpper (default = 0.005): Proportion of frequency samples that may be above the upper threshold before cleaning is adapted. We chose this value since it allows a few potential outliers before adapting the cleaning.
• maxProportionBelowLower (default = 0.005): Proportion of frequency samples that may be below the lower threshold before cleaning is adapted. We chose this value since it allows a few potential outliers before adapting the cleaning.
• noiseCompDetectSigma (default = 3): Initial SD threshold for iterative outlier detection of noise components to be removed (Section 2.4). Will be automatically adapted if “adaptiveSigma” is set to 1. This value led to the fewest adaptations in our tests.
• adaptiveSigma (default = 1): Boolean if automatic adaptation of noiseCompDetectSigma should be used. Also adapts fixedNremove when cleaning becomes stricter (Section 2.5). As this is a core feature of the algorithm it is switched on by default.
• minsigma (default = 2.5): Minimum when adapting noiseCompDetectSigma. We found that a lower SD than 2.5 usually resulted in removing too many components and a distortion of the data.
• maxsigma (default = 4): Maximum when adapting noiseCompDetectSigma. We found that a SD higher than 4 usually did not relax the cleaning meaningfully anymore.
• chunkLength (default = 0): Length of chunks to be cleaned in seconds. If set to 0, automatic, adaptive chunking based on the data covariance matrix will be used.
• minChunkLength (default = 30): Minimum length of the chunks when adaptive chunking is used. We chose a minimum chunk length of 30 s because shorter chunks resulted in both, a sometimes suboptimal decomposition within Zapline and a lower frequency resolution for the chunk noise peak detector. Smaller chunks result in better adaptation to nonstationary noise, but also potentially worse decomposition within Zapline. The necessary minimum chunk length for ideal performance may also depend on the sampling rate.
• winSizeCompleteSpectrum (default = 300): Window size of the pwelch function to compute the spectrum of the complete data set for detecting the noise frequencies in samples. If larger than 1/8 of the dataset, a window length of 1/8 of the dataset is used. This parameter mainly adjusts the resolution of the computed spectrum. We chose relatively long windows to ensure a high resolution for the noise frequency detector.
• nkeep (default = 0): Principal Component Analysis dimension reduction of the data within Zapline. If 0, no reduction will be applied. This option can be useful for extremely high number of channels in which there is a risk of overfitting, but in our tests, even on high-density EEG and MEG data, it did not lead to better results.
• plotResults (default = 1): Boolean if the plot should be created.