WTools initial version tutorial
Note: there's a new version of WTools (v2.0) which is highly recommended.
Here, we provide a step-by-step tutorial to execute the WTools pipeline.
Sample data belong to the following publication:
Parise, E., & Csibra, G. (2013). Neural responses to multimodal ostensive signals in 5-month-old infants. PloS one, 8(8), e72360. doi: 10.1371/journal.pone.0072360
Data to be imported into WTools should conform to an event-related within-subject design with one single trigger per segment/epoch indicating the onset of the key event.
In general, WTools calls existing EEGLAB plugins to import data. Each plugin takes as input a specific data format. Users must save the data in a format that is compatible with the EEGLAB plugin of interest, which is called by the WTools import routine (see guidelines: eeglab.org/tutorials/04_Import/Import.html). Alternatively, one can first convert a dataset into EEGLAB format using EEGLAB directly, and then import the resulting files (.set and .fdt for each subject) into WTools.
Be sure to name the files to be imported into WTools following the format: "0 " (e.g. "01 subject", "02 subject", "03 subject", etc…). We provide sample data that already follow this format.
Be sure to know which channel location file applies to your data. This will be requested during data import. You find some of the most common channel location files in the WTools folder "./WTools/chans_splines" (but please double-check that the order of the channel locations matches the one of your data, otherwise all your topographies will be flawed!). Additionally, during data import you can select a spline configuration file for 3D topography plots. You find some commonly used spline configuration files in the same folder (again, please check the channel order). Users can create custom spline configuration files and add them to this folder for their usage.
Clean the existing variables in the MATLAB workspace:
clear; clc;
Add EEGLAB to the MATLAB path and open the EEGLAB GUI:
addpath('<your path to the eeglab main folder>');
eeglab;
Add WTools (specifically the "sh" subfolder) to the MATLAB path and open the WTools GUI:
addpath('<your path to the wtools main folder>/sh');
wtools;
As a result, the Wtools GUI will pop up:
Outside the WTools folder, create a main folder where you want to save the project (e.g. "WTools_tutorial").
In the WTools GUI, click on "New Project". Name the new project (e.g. "TF_analysis"):
Save the project folder (i.e. "TF_analysis") in the main folder that you previously created (i.e. "WTools_tutorial"):
As a result, this reminder will pop up (please click "Ok"):
The project folder (i.e. "TF_analysis") now contains two subfolders:
- "pop_cfg": configuration subfolder where WTools automatically saves and updates all project settings
- "Export": subfolder where you must manually copy the data to analyze (as per the reminder above). In this tutorial, please copy the sample data (i.e. "04 export.mat", "11 export.mat", "27 export.mat").
Click on "Import EEG", select the correct format (here, EGI):
Note: Before this step, please be sure that the data to be imported are stored in a format that is compatible with the EEGLAB plugin of interest, which is called by the WTools import routine (rely on EEGLAB guidelines). See section "Project setting / Step 1: Prepare data" for more information.
Select conditions. You can select a subset or all (here, we click on "Select all"):
Assign topoplot configuration (here, GSN-HydroCel-129.sfp) and decide if you want to additionally select a spline configuration for 3D scalp maps (here we do, and we select Infant-GSN-HydroCel-129.spl).
Decide whether to perform re-referencing (here we do, so click "Ok"):
Decide how to re-reference (here we re-reference to average, so click "Ok"):
Decide if you need to cut some channels (here we do, so click "Ok"):
Specifically, we need to cut channels 125, 126, 127, 128:
Enter trigger latency (here, 500 ms):
Data will be automatically imported into subject-specific folders (here: "04", "11", "27"). You can follow the progress in the MATLAB Command Window.
Note: at the end of the WTools import process, we suggest opening the data in EEGLAB (use .set files in the subject-specific folders) to double-check that parameters, channel locations and display of raw data are as expected.
Aims: Add new data to the project as they come in. Optional.
Walkthrough: Click on "Subjects Manager".
Important: This step works only after a project has already been created and initial data have already been imported and analysed (i.e. you have performed wavelet transformation on one subject at least). After new subjects have been imported into WTools using the "Import EEG" routine, you can add them to the project. This way, you can later perform group-level analyses and plots using all the subjects included in the project. The corresponding configuration files in the cfg_pop folder will be automatically updated (see settings below).
Select all the subjects that you want to include in the project for later group-level analyses and plots. The list of available subjects will get longer as you import more subjects into WTools using "Import EEG". For example, you see the following window after having imported only the first two sample subjects. If you then import the third subject separately, it would also show up here, and you could combine all three subjects.
Aims: Compute wavelets at all desired frequencies. Perform continuous wavelet transformation by convolving the signals (each EEG channel, each epoch) with each wavelet. Average all transformed epoch for each channel.
Walkthrough: Click on "Wavelet Transform".
Select subjects to analyse. You can select a subset or all (here, click on "Select all"):
Select conditions to analyse. You can select a subset or all (here, click on "Select all"):
Enter the settings for the wavelet transformation. Here, process the entire temporal window that is available (from -500 ms to 1498 ms, in steps of 1ms) in the frequency range between 10 Hz and 90 Hz (in steps of 1 Hz) of all available channels and epochs.
The option "Log-10-Transform" applies a (base 10) logarithmic transformation to the data matrix after the wavelet transformation of all epochs and their average. When log-10 data are plotted they are converted back to non-log scale, straight in percent change relative to baseline. Linear (standard) total-induced oscillations data and log-10 transformed total-induced oscillations data cannot co-exist in the same WTools project.
The option "Compute Evoked-Oscillations" computes evoked oscillations instead of total-induced oscillations. Total-induced oscillations are computed by wavelet transformation of each epoch and then averaging all of them together: in this way, the oscillatory activity non-phase-locked to the onset of the stimulus is preserved. Total-induced oscillations are richer measures compared to evoked oscillations. Evoked oscillations are computed by averaging all the epochs together and then running the wavelet transformation on the average (i.e. it is the wavelet transformation of the ERP): in this way, the oscillatory activity non-phase-locked to the stimulus onset is averaged out and lost before the wavelet transformation. Evoked oscillations are less rich measures compared to total-induced oscillations, and are a bit more sensitive to low-level features of the stimulus. Total-induced oscillations data and evoked oscillations data can co-exist in the same WTools project.
Crucially, normalize the wavelets such that their amplitude remains constant throughout the frequency range (tick "Normalize wavelet"). Finally, enter the wavelet cycle (here 7).
You can follow the progress of the wavelet transformation in the MATLAB Command Window. Outputs will be saved into condition-specific subfolders (here: "GD", "GA", "IDS","ADS") of the "Wavelets" folder.
Let us have a closer look at our example output. The .mat file " 04_ADS-avWT" contains the following variables:
- Fa = frequency values for wavelet transformation
- Fs = sampling frequency
- chanlocs = imported channel locations
- WT = wavelet transformation matrix with dimensions: channels × frequency × time
- nepoch = number of epochs for this specific condition and subject
- tim = time values for wavelet transformation
- wavetyp = wavelet type
Aims: Chop the edges to cut out distortions. Calculates the baseline at each frequency (average amplitude of the specified pre-stimulus time window) and subtracts it from the whole segment.
Walkthrough: Click on "Chopping & Baseline".
Select subjects and conditions to analyse.
Enter the settings for chopping the left and right edges of each epoch to cut out distortions introduced by the wavelet transformation. Here, the segment that we retain for later analysis includes 200 ms before and 1200 ms after stimulus onset, resulting in 1400 ms long segments. Given that the original segment lasted [-500 1500] ms, WTools will chop 300 ms at each edge of the epoch.
Specify the pre-stimulus time window to perform baseline correction (here, 200 ms pre-stimulus window). Leave "No Baseline Correction" unticked to perform the correction.
Outputs will be saved into the subject-specific folders (here: "04", "11", "27").
Aims: Calculate the difference between two conditions. Optional.
Walkthrough: Click on "Difference".
Select subjects to analyse.
Compute the differences of interest. Differences to be computed are added to the list on the right. If you added a difference by mistake, you can select and delete it using the "Delete difference" button. Here, calculate the differences GD-GA and IDS-ADS:
Outputs will be saved into the subject-specific folders (here: "04", "11", "27").
Aims: Perform grand average of all measures available (individual conditions, differences between conditions) across subjects. Possible only with two or more subjects.
Walkthrough: Click on "Grand Average".
To make sure to perform the grand average using all the subjects, WTools first asks if new subjects have been imported and should be included in the computation. If you click "Ok", WTools will run the "Subjects Manager" routine (see section "Project setting / Step 5: Add new data to existing project"). If all available subjects have already been added and you are ready to perform the grand average, click "Cancel":
Enter the settings for the grand average. Tick "Use all transformed subjects?" to include all the available subjects (otherwise WTools will ask to select which subjects must be included).
Tick "Compute SS matrix for SE plotting" if you later want to use standard error (SE) plotting functions (i.e. "X Average SE" and "Channels Average SE"). For each condition, WTools will store a file (with extension .ss) that contains the individual average for each participant, instead of the average of all participants (i.e. the grand average). Individual data are then used to plot the SE bars for a given condition in a time-frequency window. Plotting two conditions on the same graph and looking at the difference between their SE bars helps to highlight likely significant effects. For example, if the SE bars of the two conditions do not overlap between 300 and 500 ms in the frequency range 8-12 Hz on frontal channels, it suggests that there might be a statistically significant difference there.
Select the conditions (and, if computed, the condition differences) for which WTools will calculate the grand average. You can select a subset or all (here, we click on "Select all"):
Outputs will be saved into the "grand" folder.
Aims: Plot time-frequency graphs for all desired channels in a topographical arrangement.
Walkthrough: Select the condition to plot. You can select individual data from the corresponding subject-specific folder or average group data from the "grand" folder.
Enter the time and frequency ranges of interest, set the plot scale, tick the box "Draw contours" if you want the plot to show contours, tick the box "Plot all channels" if you want to plot the time-frequency graph for all channels in topographical arrangement (otherwise, WTools will ask which channels you want to select):
Aims: Plot one time-frequency graph which is the average of the desired subset of channels.
Walkthrough: Select the condition to plot. You can select individual data from the corresponding subject-specific folder or average group data from the "grand" folder.
Enter the time and frequency ranges of interest, set the plot scale, and tick the box "Draw contours" if you want the plot to show contours:
Select the channels to average for the time-frequency graph. Here, we ask for the average of channels 15 and 22, corresponding to Fpz and Fp2 respectively:
Aims: Plot one scalp map, corresponding to various possibilities: one time point at one certain frequency; average of time points at a certain frequency; average of a frequency range at one time point. Also plot a series of scalp maps, either for time or frequency series.
Walkthrough: Select the condition to plot. You can select individual data from the corresponding subject-specific folder or average group data from the "grand" folder.
Here, we request the scalp map for time point [300] at frequency [25]:
Here, we request the scalp map for the average of time points in range [280 360] at frequency [25]:
Here, we request the scalp map for the average of frequencies in range [15 30] at time point [300]:
Here, we request a series of scalp maps for the time series [280:10:360] at a certain frequency [25]:
Here, we request a series of scalp maps for the frequency series [10:5:50] at a certain time point [300]:
Aims: Plot one 3D scalp map, corresponding to various possibilities: one time point at one certain frequency; average of time points at a certain frequency; average of a frequency range at one time point. No possibility of scalp map series.
Walkthrough: Select the condition to plot. You can select individual data from the corresponding subject-specific folder or average group data from the "grand" folder.
The GUI follow the same logic as 2D scalp maps (previous section).
Note: you can plot 3D scalp maps only if you have selected a spline configuration file during the import process (see section "Project setting / Step 4: Import data").
Aims: Extract numeric values for each desired subject, condition and channel, computing the average value both in a time window and in a frequency range (via a double average). Numbers are stored in a text-tabulated file (.tab) that can be treated by third-party statistical packages.
Walkthrough: To make sure to extract numeric values using all the subjects, WTools first asks if new subjects have been imported and should be included in the computation.
If you click "Ok", WTools will run the "Subjects Manager" routine (see section "Project setting / Step 5: Add new data to existing project"). If all available subjects have already been added and you are ready to extract the values, click "Cancel":
Enter the settings to extract numeric values for the desired subjects, conditions and channels (select them using the buttons at the top of the GUI). Here, we extract values for the time window [280 360] and frequency range [15 30]:
A text-tabulated file with extracted values will be saved into the "stat" folder. Rows correspond to subjects, and columns correspond to conditions and channels (see headers).