Navigation auf uzh.ch
You need Matlab installed and activated on your system to use Automagic. Automagic was developed and tested in Matlab R2015b and newer releases.
Installation
Download the latest (beta) Version here: AutomagicInstaller1.4.6 (MLAPPINSTALL, 10 MB)
How to Run Automagic
In this section of the manual, only the basic functionality of Automagic will be explained. This covers the basic workflow from selecting a project to rating the data. Please refer to chapters 3 to 6 for detailed information all functions within the main GUI.
The Project Panel
1. Navigate to the drop-down list labelled Select Project.
2. Select Create New Project...
3. Name your project.
4. Write down the file extension that corresponds to your data file format. For example raw image files (.raw
or .RAW
), fractal image files (.fif
), generic data files (.dat
) or even texts (.txt
or .asc
).
.txt
, .asc
or .csv
) , then an edit box below in the window is enabled so that you determine the sampling rate of you recorded data. This information is not necessary for other formats and the edit box is disabled.5. Choose the EEG System in which your data is recorded. Currently only EGI HCGSN is fully supported for both number of channels 128 and 256 (or 129 and 257 respectively). This information is needed mainly to find channel locations. In case you choose the option Other... for your EEG System, you must provide a file in which channel locations are specified. The file format must be one which is also supported by EEGLab (pop_chanedit
function). In addition, you must provide a list of indices of the EOG channels of your dataset. Note that here the list contains the indices of those channels and not their labels (You can also simply deselect the EOG regression and this step will be skipped during the preprocessing).
pop_chanedit
. eg. sfp
6. You can select or deselect the EOG regression (It is recommended to select it). If you choose Other... for your EEG system then you need to specify the list of EOG channels as well. In the case of EGI automagic already knows the EOG channels and you don't need to specify anything. The list of EOG channels must be integers seperated by space or comma, e.g. 1 32 8 14 17 21 25 125 126 127 128
7. Set the downsampling rate on the manual rating panel. The downsampling only affects the visual representation of your data. A higher downsampling rate will shorten loading times. In general, a downsampling rate of 2 is a good choice.
8. Specify the path of your data folder. Automagic will scan all folders in your data folder for data files. Files and folders in the data folder will not be altered by Automagic.
9. Specify the path of your project folder. If the specified folder does not yet exist, Automagic will create it for you. Automagic will save all processed data to your project folder. By default, Automagic opts for your data folder's path and adds _results
to your data folder's name, e.g. \PathDataFolder\MyDataFolder_results\
10. Choose your filtering parameters in the Filtering panel.
US
if your data was recorded in adherence to US standards (60 Hz). Choose EU
if your data was recorded in adherence to EU standards (50 Hz).11. By clicking on the Configurations... button you can modify additional optional parameters of the preprocessing. This is not necessary, and you can leave it so that the default values are used.
12. Click on Create New in the lower right corner of the project panel to create your new project. If the specified data and project folders do not yet exist, Automagic will now create them for you.
If you already had created a project with Automagic and for some reasons re-installed your matlab or Automagic app, you can load that project and keep all the information. There are two options to load an existing project. The first option can only be used to open projects that have been created on your system or that have been loaded before:
The second option can be used to load any Automagic project:
project_state.mat
To merge any number of existing projects without losing the individual projects, please follow these steps:
project_state.mat
. Do not copy these files to your new project folder.If you would like to add some new subjects, or files to your existing project you could use this option.
project_state.mat
in the project folder and remove the project from the Automagic GUI. Please use Finder (Mac), Explorer (Windows) or your Linux equivalent to delete your project data and/or project folder.After clicking on Configurations... button a new window is opened where you can customize preprocessing steps:
In the Filtering section you can choose the order of the filtering. The default value corresponds to the default value computed by pop_eegfiltnew.m
.
In the Channel rejection criterias you can select or deselect the four different criterias Line Noise, Channel criterion, Burst Criterion and Window Criterion. The first to criteria are used to detect noisy channels and the last two criterias to remove noisy time windoes. By default only the first two criteria are checked and noisy channels will be marked during the visualisation step, where you can choose to interpolate them. For more information about these criterias, please see clean_artifacts.m
by Artifact Subspace Reconstruction (Mullen et al., 2013).
ICA can be selected or deselected. Note that ICA and PCA can not be chosen together at the same time. The ICA uses the algorithm in MARA (Winkler et al., 2011, Winkler et al., 2014).
PCA (Lin et al., 2010) can be selected or deselected. The parameters correspond to paramters of inexact_alm_rpca.m
. The default value is where m is the number of channels.
The mode of interpolation can be determined. The default value is spherical.
Click on Run to start the pre-processing of your data. This is the first thing you should do after creating a new project or after adding data to an existing project. Pre-processing may include filtering, detection of bad channels, EOG regression, PCA or ICA, and detrending.
Should the project folder already contain files (i.e. should some of the projects data already have been pre-processed), you will be able to choose whether existing files will be overwritten or skipped after clicking on Run.
Click on Start... to open the rating GUI.
A visualisation of the currently selected file is displayed. Time corresponds to the x-axis, EEG channels correspond to the y-axis. You can use the tools in the top left corner to e.g. magnify an area or select a specific point of the current visualisation. Use the filters right below the tools to focus on a subset of your files based on their rating. You can navigate between files of the current subset by clicking on Previous and Next or by selecting a file from the drop-down list in the top right corner.
You can rate the quality of the visualised data on the very right. You can choose between Good, OK, and Bad. These ratings are subjective and relative rather than absolute: The overall quality of your data should be used as point of reference. The colouring allows you to rate the quality of your data: Ideally, everything is green. Darker colours signify lower quality, i.e. artifacts etc. As a rule of thumb, horizontal artifacts are worse than vertical artifacts of the same size and colouring. After choosing a rating, you will automatically proceed to the next file. Please note that depending on your data and its signal to noise ratio, the color map may need to be modified. On the very bottom right of the window you can select the range of color map [-X, X] where X can be a positive integer between 25 < X < 150. The default range is [-100, 100].
Detected bad channels during preprocessing are represented by horizontal lines which are darker than their surroundings. Should you also spot bad channels, please select Interpolate. This will activate selection mode. Manually navigate to bad channels and select them by clicking on them. Click on Turn off after selecting all bad channels. Click on Next to proceed to the next file. In the next step you will start interpolationg these bad channels and finally you can come back to re-rate these files after interpolating all selected channels.
Going through every file of a huge dataset and manually inspecting them can be a very cumbersum task. Keyboard shortcuts can be used to accelerate this inspection in rating window. Using keyboard shortcuts you can rate and/or select the next or previous file:
Further information, including a manual about the internal application structure, Automagic as a EEGLab extension and how to run the application from code can be found on https://github.com/amirrezaw/automagic
References of used functions in Automagic:
Bigdely-Shamlo, N., Mullen, T., Kothe, C., Su, K. M., & Robbins, K. A. (2015). The PREP pipeline: standardized preprocessing for large-scale EEG analysis. Frontiers in neuroinformatics, 9, 16.
Winkler, I., Brandl, S., Horn, F., Waldburger, E., Allefeld, C., & Tangermann, M. (2014). Robust artifactual independent component classification for BCI practitioners. Journal of neural engineering, 11(3), 035013.