Configurations
Click on Configurations (don’t worry, everything selected is save) to open the configurations GUI:
Automagic offers several methods to detect bad channels that are later interpolated. Typically, either PREP (Bigdely-Shamlo et al. 2015) or the clean_rawdata() pipelines work very well, so we recommend to choose either of them. We noticed that artifact subspace reconstruction (ASR) in the clean_rawdata() not always yields replicable outcomes, but it might work for your data, so just test it before applying it to your data! An additional method is implemented that searches for residual bad channels after having run the entire preprocessing pipeline. It catches the rare cases when the other pipelines missed a channel with high variance.
Important notes considering filtering of the data when using PREP or clean_rawdata():
- PREP by default uses a similar operation as notch filter. When you do select PREP, then it is a good idea to avoid selecting an additional notch filter in the filtering section (at the right hand side of the GUI). But still, please do not forget to choose the line power frequency in the filtering section (Just deselect the Notch Filter). Alternatively, you can select 'PREP discard notch' to avoid using PREP's in-built notch filter and retain your own preferred additional notch parameters.
- As with ICA MARA, we tried to give the option of having a temporarily high pass filter before clean_rawdata(). The user may want to have high pass filters before these steps which are different from the high pass filter which will be applied on the end result (which can be selected in the filtering section at the right hand side of the GUI). By selecting the option High pass in the clean_rawdata() section, you can have a temporarily high pass filter before the clean_rawdata() operations except when either of Run ASR with burst criterion or Window criterion are selected. In both of these cases the clean_rawdata() returns a cleaned EEG data which could be even shorter than the original EEG. Because of this we can not undo the filtering on the returned data or ignore this returned EEG, otherwise there would be no use of selecting these criteria which are for cleaning the data rater than a mere channel detection. However when these two criteria are not selected, we can ignore the returned EEG data which is only filtered, and only take the detected bad channels. So be aware that while selecting these two criteria alongside the High pass option, you may want to be careful with the high pass filtering in the filtering section.
Residual Bad Channel Detection
- High Variance Criterion (HVC):
This will identify channels which have high-variance activity. You can specify the standard deviation which is the upper
limit for identifying bad channels.
- Cut-off: Deletes timepoints with amplitudes greater than this cut-off value.
- Rejection Ratio: This removes channels with too many values above the cut-off value. The value indicates the ratio of bad timepoints per channel allowed; channels with ratios above this value are rejected.
- Minimum Variance Criterion (MVC): This will identify channels which have low-variance activity. You can specify the standard deviation which is the lower limit for identifying bad channels.
Filtering is applied after the Bad channel detection and before Artefact removal.
-
Line Power:
- Notch Filter: Indicate if you would like to apply a notch filter to your data. Note that using PREP already takes care of line noise using CleanLine (Mullen 2012). Indicate the line power where your EEG was recorded.
- ZapLine Filter: This is an alternative to the notch filter which filters out power line noise by combining spectral and spatial filtering (de Cheveigné 2019). The complementary 'No. components' option "specifies the number of spatial components to reject from the power-line dominated part of the data. Multiple power line components indicate multiple sources of artifact, each with a different time course and spatial signature" (de Cheveigné 2019).
- Important: Please select a line power frequency even if you do not desire to use a notch filter. This information can be used by PREP or later for log files.
-
High Pass Filter: Check the box if you would like to apply a high pass filter and indicate the cutoff frequency. The filter order will be estimated according to
eeg_filtnew()of EEGLAB by default. -
Low Pass Filter: Check the box if you would like to apply a low pass filter and indicate the cutoff frequency. The filter order will be estimated according to
eeg_filtnew()of EEGLAB by default.
Alternatively you can select firws() which will apply a windowed sinc type I linear phase FIR high or low pass filter; it will open a new window for specifying cut-off parameters, etc. and may take time to load.
- Select
firws(), which will open the file manager. - Browse to an EEG structure (e.g., EEG.mat) and press open
-
firws()GUI will appear, where you can selectfirws()parameters
In the Artifact removal section you can select EOG-regression, MARA (Winkler, Haufe, and Tangermann 2011; Winkler et al. 2014), ICLabel (Pion-Tonachini, Kreutz-Delgado, Makeig, 2019) or robust PCA.
- In the EOG regression (Parra et al. 2005), EOG electrodes are used as a reference signal that is subtracted in proportion to their contribution to each EEG channel. Please indicate the indices of the EOG channels, separated by white space. In the case you choose to use the preset defaults of our lab for the EGI case, these channels are already known to Automagic and you need not to provide them. You can see the list of those channels here.
- MARA performs an ICA and detects and rejects artifactual independent components (Winkler, Haufe, and Tangermann 2011; Winkler et al. 2014). The ICA of MARA works best if the data is high pass filtered, so we recommend to filter the data with 2 Hz. Note that this filtering is only temporary and specifically for the ICA. This option will not be applied to the final preprocessed data. Note that MARA requires that EEG channels are labeled according to the 10-20 system. You should therefore provide a channel location
.chanlocswhere labels are according to 10-20 system (i.e.'Fp1', 'Fp2', 'Fz', 'F3', etc.). Components extracted during ICA can be optionally stored before they are removed using the 'Save All Components' tickbox. - ICLabel performs an ICA and detects and rejects artifactual independent components (Pion-Tonachini, Kreutz-Delgado, Makeig, 2019). The ICA of ICLabel works best if the data is high pass filtered, so we recommend to filter the data with 2 Hz. Note that this filtering is only temporary and specifically for the ICA. This option will not be applied to the final preprocessed data. There are categorical options for selecting identified artefacts to be subtracted/retained along with their probability of the IC being labelled as that component type. Two probability thresholds are required: the lower und upper threshold. Please note that the thresholds will never be or exceed 0 and 1. Components extracted during ICA can be optionally stored before they are removed using the 'Save All Components' tickbox.
- IClabel with OPTICAT (Dimigen, O. (2020). Optimizing the ICA-based removal of ocular artifacts from free viewing EEG. NeuroImage, https://doi.org/10.1016/j.neuroimage.2019.116117). This feature is still in development and many parameters are hardcoded. Please contact us, if you need any help to adapt the code to your data. After overweighting saccade intervals containing spike potentials, ET data is separated from EEG data and stored in EEG.ET. Important! Data folder must follow a restrict structure so that Automagic can read and merge EEG and ET recordings:
- Default Automagic folder structure
StudyFolder
Subject1
sub01-run1-task_EEG.mat
sub01-run1-task_ET.mat
Subject2
sub02-run1-task_EEG.mat
sub02-run1-task_ET.mat
If there are more than 1 EEG and ET files in a given subject folder, the filenames of the EEG and ET files MUST be identical and MUST end with _EEG. and _ET., respectively.
e.g.:
sub01-run1-task_EEG.mat
sub01-run1-task_ET.mat
sub01-run2-task_EEG.mat
sub01-run2-task_ET.mat
- BIDS format. Automagic also recognize BIDS format. In this case, Automagic expects an
etfolder, as shown in the example below.
sub-<label>/
[ses-<label>/]
eeg/
sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>]_eeg.<extension>
sub-<label>...
et/
sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>]_et.<extension>
- The implemented algorithm of the robust PCA ((Lin, Chen, and Ma 2010) estimates a low-dimensional subspace of the observed data, reflecting the signal that is cleaned from sparse corruptions. This method is generally faster but typically removes less artifacts than MARA as we have observed in validations. Unless you aim to tune the robust PCA, the default parameters work well for many situations.
- The Overall Thresholds is a list of absolute voltage magnitudes in mV at which the ratio of data points (i.e. channels x time points) that have a higher absolute voltage magnitude than that threshold is calculated.
- The Time Thresholds is a list of values of standard deviations of voltage magnitudes in mV within time points (across channels) at which the ratio of time points that have a higher standard deviation than that threshold is calculated.
- The Channels Thresholds is a list of values of standard deviations of voltage magnitudes in mV within channels (across time) at which the ratio of channels that have a higher standard deviation than that threshold is calculated.
The interpolation method can be selected here. Refer to the help of eeg_interp() for details about the options.
- The downsampling only affects the visual representation of your data. A higher downsampling rate will shorten loading times and reduce memory need. In general, a downsampling rate of 2 is a good choice. But this still depends on the size of the EEG.
- By selecting the Sort channels F-C-P-O (Plots only) the channels will be arranged in following order: Frontal - Central - Parietal - Occipital, but only on the final plots. The EEG.data will not be sorted.
- You can select one of three colormaps for the final plots: default jet colormap, red-yellow-blue or red-white-blue.
- By selecting the Save a
.matafter each steps, Automagic will save a version of the EEG after each preprocessing step. This allows you to inspect the data and see the effect of each preprocessing step. All these files are saved in the same result folder under the name ofallSteps_'fileName'.mat. Note that selecting this option will obviously take more disk space after the preprocessing.
Finally you can confirm your configurations by clicking OK. In the project GUI create your project by clicking the button Create Project and a pop up window appears, stating that the Project was successfully created. Depending on the size of your dataset this may take a while.
- Please note that once the configurations are defined and a project is created, all the configurations are fixed and cannot be changed any more to assure that all datasets of a project are identically processed. In contrast to having the configurations fixed, the input files are not, that is, it is always possible to add (or to delete) datasets to a data folder and Automagic detects these changes whenever the application is restarted. This guarantees that all EEG files of a project are preprocessed in an identical standardized way.
In case you would like to create a new project with the exact parameters from another project, you can simply click on Load existing configuration… and then choose the project_state.mat file of the project from which you would like to take the parameters. This will load all the configuration parameters to the GUI, where you can also make modifications before creating the project.
If you are curious about the project_state.mat, take a look here.