Skip to content

How to start

Jump to bottom
ksgfan edited this page Aug 30, 2023 · 42 revisions

Start Automagic

To run Automagic, start Matlab and change your working directory to the unzipped folder automagic-master/:

>> cd path/to/automagic-master
  • Please avoid adding Automagic manually to the Matlab path. Avoid any use of addpath(genpath('automagic-master')) or addpath(genpath('eeglab')) in order to avoid conflicts.

While your working directory is automagic-master, type

>> runAutomagic

in the Matlab command line. Automagic will be started, necessary paths will be added to the path, and the project GUI will appear:

By clicking on question marks anywhere in the GUI, you will be directed to different sections of this wiki for more help.

Automagic directory hierarchy

Data folder must follow a restrict structure so that Automagic can read EEG recordings. Except the BIDS folder structure that is also integrated, the default folder structure of Automagic is as follows:

The root data folder (e.g. path/to/Study) contains only folders each of which corresponding to a Subject (e.g. path/to/Study/Subject01). Each Subject then contains the recording EEG files (e.g. path/to/Study/Subject01/Sub-01-task-rest-EEG-01.set). Note that the root folder path/to/Study should not contain any other file or folder except the Subjects (and the automatically generated state file). However, the subject folder itself path/to/Study/Subject01 can contain multiple other files such as images, etc. The way Automagic recognises the recording files out of the other files is using the file extension provided at the project creation (see next section). You are free to name all files and folders to anything you would like.

Image below illustrates this structure:

  • Tip: Instead of a file extension such as .set, you can provide Automagic a mask such as EEG-01.set where in our example will tell Automagic to consider only the first runs of each subjects. This feature can be helpful in some scenarios where you have many recordings with the same extension but you need to choose only a subset of them. Please note that this mask only works for the end of the file name where the extension is provided.

The preprocessed data is stored in the results folder and contains for each EEG file one preprocessed EEG file (i.e. gip_Sub-01-task-rest-EEG-01.mat), reduced EEG file (reduced_Sub-01-task-rest-EEG-01.mat), methods logfile(Sub-01-task-rest-EEG-01_log.txt), visual output (Sub-01-task-rest-EEG-01.jpg), one visual output of the original file (1Hz filtered, Sub-01-task-rest-EEG-01_orig.jpg), and one file with the data after all preprocessing steps (if the option save a .mat file is activated):

Below is an example of the visual output file (Sub-01-task-rest-EEG-01.jpg):

The EOG plot in the visual output image is z-normalised, i.e. The data from each EOG channel are centralised around a mean of 0 and 1 standard deviation.

How to create a new project

Below are the steps to take in order to create a new project. Some steps are then explained in more detail in the following subsections.

  1. Start Automagic (as explained above)
  2. Navigate to the drop-down list Select Project
  3. Select Create New Project…
  4. Name your project
  5. Provide the file extension (case-sensitive) that corresponds to your data file format (e.g. .set, .mat, .raw, .RAW, .edf ...).
  6. Choose the Data folder (where the raw data is located). This folder must have the structure as explained in the previous section. In addition to this, the BIDS folder structure is also admissible.
  7. Automagic suggests a new path to save the result files based on the selected Data Folder. You can however change this to any other path by choosing the Results folder.
  8. By typing the channel indices (not the labels!) into the field Exclude EEG Channels you can exclude channels from further processing. Please note that the channels will be removed AFTER loading the channel location file (i.e., they must exist in the channel location file).
  9. By typing the channel indices (not the labels!) into the field Exclude Misc. Channels you can exclude miscellaneous channels (i.e., ECG, photodiode, etc.) from further processing. Please note that the channels will be removed BEFORE loading the channel location file, as they don't have a specific location on the scalp. The removed channels are stored in EEG.Misc.
  10. Set the channel location file:
    • Unless your data contains an EEGLAB EEG structure with channel locations (EEG.chanlocs) included, you need to provide a file supported by EEGLAB pop_chanedit function, in which channel locations are specified. In the case of an EGI file (128(+1) and 256(+1) channels) where you select to use the Langer lab preset values, you do not need to provide this information.
    • The Channel location file (with the full path).
    • The Channel location file type must specify the type of the file as required by pop_chanedit (eg. .sfp, .xyz, etc.).
  11. Indicate the sampling rate in Hz unless it is indicated in the EEG structure (EEG.srate). This is specially the case for .txt formats where there is no sampling rate in the structure.
  12. If a specific reference channel is included in your data, please indicate the index of that channel so it is excluded from the bad channel detection.
  13. Please note that if you have Electrical geodesics (EGI HCGSN) recordings with 128 and 256 channels (or if the reference is included 129 and 257 respectively) you can select the default recommended values for the above steps by simply choosing Use presets of Langer lab for EGI (HCGSN).

By now you could simply press the Create Project button and you would have created a new project, ready to be preprocessed. However, before pressing on Create Project, you can change the default configurations as explained here for the preprocessing methods that are implemented Automagic.

If the steps above are ambiguous or you are simply curious to know more, following subsections explain in more detail:

File extension

Currently Automagic uses five different functions to read files with different extensions. For .mat EEG files, load() the usual built-in function of MATLAB is used. For .txt files pop_importdata('dataformat','ascii', ...) is used. pop_loadset is used to load .set files and pop_biosig is used for .edf file formats. Finally any other extension will be read through pop_fileio. If the extension is not supported by pop_fileio an error will occur.

extension function
.mat MATLAB load()
.txt pop_importdata('dataformat','ascii', ...)
.set pop_loadset(...)
.edf pop_biosig(...)
.raw, .dat, etc. pop_fileio(...)

If you believe any important file type is missing please let us know.

Exclude channels

Sometimes you may want to carry out the preprocessing on only a subset of the EEG channels and not all of them. In Automagic you can always write down the indices of these EEG channels in the Exclude channels section. Before preprocessing steps start, these channels are removed from the EEG structure using pop_select.

Channel location

It is important for Automagic to provide a correct channel location where for each channel in the EEG.data data structure a corresponding location in EEG.chanlocs exists. A channel location can be provided in either of the two following ways:

  1. The EEG structure that is loaded has already a .chanlocs field with all the location information in it. In this case there is no need of providing a path to the channel location file or even its file type/extension and those fields can be left empty.
  2. Otherwise you could simply provide Automagic with the full path to the channel location (e.g. path/to/GSN-HydroCel-129.sfp) and its corresponding file type (e.g. .sfp). To load the channel location from this file Automagic uses the function pop_chanedit. This implies that all files and formats supported by pop_chanedit are also supported here.
  • Important note: If EEG.data has more additional channels than EEG.chanlocs such as event channels (i.e., miscellaneous channels; ECG, EMG etc.), you should NOT try to exclude those channels using Exclude EEG channels field to "hack around". Automagic exclude those EEG channels only after having loaded the channel locations, therefore this does not solve the problem.To remove miscellaneous channels, use the Exclude Misc channels field. It will remove them from EEG.data and store in EEG.misc.

Reference channel

Although reference channel is used nowhere in the preprocessing part, Automagic still needs to know where the reference channel is. If the reference channel is already in your EEG.data structure, you need to simply choose the option Has already a reference channel and provide the index of that channel in your dataset. However if this is not the case, then you need to choose to add a new reference if your channel location file has already a location for the reference channel. As an example for the case of EGI the location of Cz channel is already in the EEG.chanlocs so if we have only 256 channels, we need to select the option Add a new reference channel where a new channel of zeros will be added to the EEG.data. Otherwise you can simply choose non-scalp reference channels where no reference channel in the EEG.data is assumed if this corresponds to your data.

Filtering datasets by file-size

This feature is useful if you want to only preprocess files which have file-sizes within a specific range (i.e. exclude excessively large/small files). Above the 'Run' button in the main GUI you will find the File Size Filter feature. This opens a separate window for specifying the criteria for file-size filtering. If no project is selected, this window will not open. The distribution of file sizes can be plotted using a box plot or using a histogram, but this feature is best applied to very large datasets. Two filter options are currently available:

  • Maximum File Size - Specify the maximum file size (in Mbytes) you wish to include.
  • Minimum File Size - Specify the minimum file size (in Mbytes) you wish to include.

After selecting your filter criteria you can click 'Calculate' to know what percentage of your files will be excluded if you confirm these criteria. Click 'OK' to confirm your preferences.

Trim data

This option allows to remove noisy beginning or/and ending of a dataset. You have to select the trigger before/after which the dataset will be cut off and the time from that trigger (in time points). Negative time indicates time before the trigger, positive time indicates time after the trigger.

Trim Outlier

This option allows to reject datapoints that are above the specified threshold. Point spread width (in ms) determines the range for rejection.

Preset values of Langer lab

The recorded data in our lab are in EGI format (Electrical geodesics). For this specific case we have some default preset values. By choosing this option you can simply ignore filling few of the above sections such as channel location, exclude channels and reference channel. The following values are then used in these cases:

128 channels

In this case channel location GSN-HydroCel-129.sfp is used. A new reference channel with zeros is added as the last channel Cz. The following channels are excluded from preprocessing: 48 49 56 63 68 73 81 88 94 99 107 113 119.

In case of EOG regression, the following channels are considered as EOG channels: 1 8 14 17 21 25 32 125 126 127 128.

256 channels

In this case channel location GSN-HydroCel-257.sfp is used. A new reference channel with zeros is added as the last channel Cz. The following channels are excluded from preprocessing: 67 73 82 91 92 102 111 120 133 145 165 174 187 199 208 209 216 217 218 219 225 227 228 229 231 232 233 235 236 237 239 240 242 243 245 246 247 249 250 251 253 254 255 256.

In case of EOG regression, the following channels are considered as EOG channels: 1 10 18 25 31 32 37 46 54 226 230 234 238 241 244 248 252.

Deleting a project

If a project is selected, you can click on Delete Project in the lower right corner of the study panel. A dialog box will appear to make sure you take responsibility by clicking on Delete!

Note: This will only delete the file named project_state.mat in the data folder and remove the project from the Automagic GUI and its structure. Your data will however remain in both directories data and results folder. Please use Finder (Mac), Explorer (Windows) or your Linux equivalent to delete your results folder and/or data folder.

Clone this wiki locally