WTools v2.0 tutorial
Here, we provide a step-by-step tutorial to download, install and execute WTools v2.0
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
- Click on WTools v2.0 ZIP
Let's assume that Matlab is installed together with EEGLab (> 2019) and that the EEGLAB path has been added to the Matlab paths. There are 2 ways to install and then execute WTools:
Install as a standalone application
- Unzip the WTools package
- Run Matlab and, from the command console, change directory to the WTools package
- Type wtools
Install as an EEGLab plugin
- Unzip the WTools package
- Copy the unzipped package into the EEGLab plugins directory
- Run EEGlab
- From the EEGLab GUI navigate to Tools->WTools
WTools depends on specific EEGLAB plugins for data importation. Each plugin is responsible for handling a particular data format, as outlined in the EEGLAB tutorials, to which the data must be encoded. Alternatively, users can convert a dataset into EEGLAB format using EEGLAB directly and then import the resulting .set and .fdt files with WTools.
Data must adhere to an event-related within-subject design, with a single trigger per segment/epoch indicating the onset of the key event.
For WTools to import a data file successfully, the file name must adhere to a specific format. For each supported acquisition system, the file name should align with the specified regular expressions:
| System | RegExp | Description | Examples |
|---|---|---|---|
| EEP | ^(?<subject>\d+).*\.cnt$ |
At least one digit + any character + '.cnt' | 12.cnt, 01 whatever 12.cnt |
| EEGLab | ^(?<subject>\d+).*\.set$ |
At least one digit + any character + '.set' | 12.set, 01_whatever.set |
| EGI | ^(?<subject>\d+).*\.mat$ |
At least one digit + any character + '.mat' | 12.mat, 12 1000.mat |
| BRV | ^(?<subject>\d+).*\.mat$ |
At least one digit + any character + '.mat' | 12.mat, 3whatver.mat |
- The digits prefix represents the subject number, so avoid having 2 different data files with the same subject number.
- EEP is supported only on MS Windows.
Ensure that you are aware of the channel location file that corresponds to your data, as this information will be required during the data import process. You can locate some of the most commonly used channel location files within the WTools package directory WTResources/WTDevices/WTChannelsLayouts. It is important to verify that the order of the channel locations aligns with your data to avoid inaccuracies in your topographies.
Clean the existing variables in the MATLAB workspace:
clear; clc;
Then, you can run WTools either by typing the command wtools or via the EEGLAB GUI:
As a result, the WTools GUI will pop up:
Note: Before this step, please be sure that the data to be imported is 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.
Outside the WTools folder, create a parent folder where you want to save the project folder (e.g. "WTools_tutorial").
In the WTools GUI, click on "New". Name the new project (e.g. "TF_analysis"). Save the project folder (i.e. "TF_analysis") in the parent folder that you previously created (i.e. "WTools_tutorial").
A confirmation window will pop up (please click "Ok"):
The project folder (i.e. "TF_analysis") now contains four subfolders:
- "Config": subfolder where WTools saves and updates all project settings;
- "Import": subfolder where WTools imports the data to analyze. In this tutorial, you will import the sample data (i.e. "04 export.mat", "11 export.mat", "27 export.mat");
- "Analysis": subfolder where WTools saves the imported data and stores all analysis outputs.
- "Logs": subfolder where WTools saves log files (see section "Application control and configuration" for more information).
WTools will then ask you to select the correct import format (here, EGI):
Either directly follow from the previous step or manually click on "Import -> EEGLab".
Select files from your File Explorer. Confirm that you are importing files in EGI format:
Confirm which subjects you want to import (here, we click on "Select all"):
Select conditions. You can select a subset or all (here, we click on "Select all").
The following step is to confirm/update the channel locations layout that EEGLab automatically associates with the imported data or, if the data source system is EEGLab itself, has been assigned previously. WTools displays such a layout and asks to accept/reject it:
The picture of the layout provides a qualitative description and does not show specific details like the values of the coordinates of each electrode. The title of the picture, which indicates the name of the layout file, can however help in discriminating between layouts with the same set of channels but different coordinates. For data imported from a different source, EEGLAB automatically associates a layout file, as mentioned before, so its name will refer to one of the layouts embedded in EEGLAB. When instead the data are imported from EEGLab, you might have already edited the channels layout and replaced it with your own: in such a case, to avoid confusion, it's suggested to use different layout names from the ones used by EEGLAB.
If you reject the layout, WTools asks you to pick one from its pre-defined internal set. If you want to add your layout to that set, you have to copy it to the WTools package directory WTools/WTDevices/WTChannelsLayouts.
Once you have made a selection, WTools performs some checks:
- If the number of channels in the layout is minor than the number of channels in the data, the layout can't be applied and you'll be asked to select another one (or you can quit the import)
- If the number of channels in the layout matches the data, WTools applies the layout as it is.
- If the number of channels is greater than the number of channels in the data, WTools proposes to adjust the layout.
If you agree to adjust the layout, you have 2 possibilities:
- You can let WTools do that automatically, by matching the layout with the one already associated with the data, based on the channel labels. This option makes sense only if the 2 layouts have the same format. The operation is successful only when all the pre-assigned labels are matched in the new layout. The correspondence between the channels and the data is not modified in this case, but their position on the scalp is updated with the one defined in the new layout.
- You can edit the layout and select which extra channels to prune. WTools displays the list of the layout channels, and you have to make a selection. The relative order of the channels in the list, which determines how they are paired with the data, cannot be changed. In such a case, the channel labels do not matter for the operation to be successful. The only factor that counts is the number of channels left after the pruning. The channels are paired with the data through their corresponding index in the adjusted layout. So be careful: you can potentially remove any channel to reach the desired amount, therefore, you must not make mistakes.
Whichever your choice, if the operation is successful, the edited layout is displayed for confirmation. If you accept it, it'll be saved in the Support directory of your project.
EEGlab removes the Cz channel (or reference channel) automatically when it imports data from EGI. WTools reintroduces it (as a 0 data channel) to allow channels re-referencing based on the average.
GSN-HydroCel-129.sfpStandard-10-5-Cap385.elp: standard labels (International 10-5 system) 385-channel layout, it can be used with any recording system with standard labels up to 385 channelsANT-23Ch.ced: standard labels (International 10-20 system) 23-channel layout, specific for ANT recording systemBiosemi-35Ch.sfp: standard labels (International 10-20 system) 35-channel layout, specific for Biosemi recording system
It is best to preprocess your dataset(s) directly in EEGLab and save them in EEGLab format (.set), then import the EEGLab file(s) in WTools. If your data has standard labels, select
Standard-10-5-Cap385.elp(compatible with any recording system), and it will automatically detect the available channels in your dataset. If data does not have standard labels or if not using GSN-HydroCel-129, the user must find a suitable layout for their recording system.
Once the channel layout has been assigned/accepted, you might want to cut some channels (here we do, so click "Ok"):
In this tutorial, we need to cut these channels: 125, 126, 127, 128. Please select those from the list.
Decide whether to perform re-referencing (here we do, so click "Ok"):
Decide how to re-reference (here we re-reference to the average):
The operations related to the channels are performed in the following order:
- Channel layout editing
- Removal of unused channels
- Channels re-referencing
Consequently, if you cut channel X from the data and later choose to apply a by-channel average re-referencing, channel X will not be part of the channel average calculation. Moreover, if you decide to re-reference based on a subset of channels, channel X will not even appear in the list of channels you may select for that purpose. Particular attention must be paid to data imported from EGI systems: as said before, the reference channel (Cz channel) is re-introduced by WTools on purpose to perform a proper channel-by-channel average re-referencing. Thus, you should avoid cutting this channel in such a case.
Enter trigger latency (here, 500 ms):
Select which trials to analyze. By default, all trials are considered. However, the user can specify a subset of trials or even a specific single trial. Here, we select all trials, so we leave the following as it is:
Data will be automatically imported into subject-specific subfolders (here: "04", "11", "27") of the "Analysis" folder. You can follow the progress in the MATLAB Command Window.
Notice that the required import settings might differ slightly depending on the source data system. In the example above, trigger latency and trials range definition are specific to the import from EGI systems. When importing from EEGLab, you are not asked to fill in such details.
-
You can always import additional subjects later (see "Subjects Manager" below).
-
At the end of the WTools import process, we suggest opening the data in EEGLAB (use .set files in the subject-specific subfolders) to double-check that parameters, channel locations and display of raw data are as expected.
-
About the order of the trial segments: they are re-numbered based on their order as returned by
fieldnames(data). The order of the original data structure will remain in the imported data. Notice, however, that you might have datasets with removed segments, like the following:- dataset 1:
segment_1, segment_5, segment_6, segment_9 - dataset 2:
segment_3, segment_4, segment_7, segment_8
- dataset 1:
For both datasets, trials will be re-numbered as segment1, segment2, segment3, segment4.
This choice is based on the following rationale. First, when one gets to import data into WTools, they must have already selected the segments they want to transform in the TF domain, meaning that all the other (noise-contaminated) segments must have already been cut out. That's why numbers are not continuous. Thus, one is left with all the segments they want to analyse, and only those. Losing the original segment numbers is, therefore, no real damage. Second, segments are divided per experimental condition. As long as segments do not mix between conditions as a consequence of renumbering them on a continuum, the user is safe. This is exactly what WTools does. Finally, continuous re-numbering is good for importing data into older versions of EEGLAB; otherwise, importing would stop as soon as EEGLAB encounters numerical gaps.
Aims: Add new data to the project as it comes in. Optional.
Walkthrough: Click on "Subjects Manager".
Important: This step works only after a project has already been created and data from at least one subject has already been imported (using the import routine) and analyzed (using the wavelet transformation routine). After new subjects have been imported and analyzed, you can rebuild the single-subject list (Subjects Analysis) and the group-level list (Subjects Grand Analysis) for subsequent analyses and plots. The corresponding configuration files in the "Config" folder will be automatically updated.
The list of available subjects will get longer as you import and analyze more subjects. For example, you see the following window after having imported and analyzed only the first two sample subjects. If you then processed the third sample 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 epochs for each channel.
Walkthrough: Click on "Wavelet Transform".
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 1 ms) in the frequency range between 10 Hz and 90 Hz (in steps of 1 Hz) of all available channels and epochs.
Edge padding should not be normally performed if you have designed your protocol correctly, so the relative field should be left as by default. However, in case you need to apply some padding, check below the FWHM/2 button functionality, which brings essential information to make a proper choice of the padding size.
Set Compute Evoked-Oscillations to compute 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 cannot co-exist in the same WTools project.
Set Transform Power if you want WTools to perform the analysis based on the power of the wavelet transform rather than on its module (which is the default). When working with the power, the Morlet wavelets are automatically normalised to unit energy.
Set Save Re/Im Components to save the Real and Imaginary components of the wavelet transform: that might be useful if you plan to run on your own some analysis where the phase of the transform matters.
Select the number of Wavelet Cycles. Usually, the default value, 7, is good enough for the analysis. However, you have the choice to choose a different value if you need (please check the literature to know the impact of your choice).
Above the Wavelet Cycles field, there's a button: FWHM/2. Press it to get a plot of the Wavelet Full Width at Half Maximum (FWHM). Such a plot depends not only on the number of cycles but also, though very minimally, on whether you are running the analysis on the transform power or not. It shows how the temporal extension of the wavelets at half of their maximum varies across frequencies. You will usually be interested in the value at the lower frequencies, because it affects the minimum padding size necessary to avoid introducing distortions in the transform at the edges of the signal, if any padding is applied at all.
Notice that before performing the transform, the DC component is removed from the signals.
Once the transform params have been defined, proceed by:
- Selecting the subjects to analyse. You can select a subset or all (here, click on "Select all").
- Selecting the conditions to analyse. You can select a subset or all (here, click on "Select all").
You can follow the progress of the wavelet transformation in the MATLAB Command Window. For each subject, outputs will be saved into condition-specific subfolders (here: "GD", "GA", "IDS", "ADS") of the "WaveletTransform" subfolder.
Let us have a closer look at one 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
- nEpochs = number of epochs for this specific condition and subject
- tim = time values for wavelet transformation
- waveType = wavelet type
Aims: Chop the edges to cut out distortions. Calculate the baseline at each frequency (average amplitude of the specified pre-stimulus time window) and subtract it from the whole segment.
Walkthrough: Click on "Chop & Baseline".
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.
You can perform a baseline correction by checking one or both of Baseline Subtraction and Baseline Normalisation. In such a case, you must define the pre-stimulus time window for the estimation of the baseline (here, a 200-ms pre-stimulus window). The baseline correction refers to the temporal domain of the signals before the chopping. Depending on the selection, the signals (either the power or the module of the transform, depending on your initial choice of the transform parameters) are
- subtracted from the baseline
- divided by the absolute value of the baseline
- both (first subtracted, then divided)
Select subjects and conditions to analyse.
Outputs will be saved into the subject-specific subfolders (here: "04", "11", "27") of the "Analysis" folder.
Aims: Calculate the difference between two conditions. Optional.
Walkthrough: Click on "Conditions Difference".
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:
Select subjects to analyse.
Outputs will be saved into the subject-specific subfolders (here: "04", "11", "27") of the "Analysis" folder.
Aims: Perform grand average of all measures available (individual conditions, differences between conditions) across subjects. Possible only with two or more subjects.
Note: make sure to perform the grand average after you have imported and analyzed all the intended subjects. If you need to add more subjects, use the "Subjects Manager" routine (see section "Project setting / Step 5: Add new data to existing project").
Walkthrough: Click on "Grand Average".
Enter the settings for the grand average. Tick "Use all processed subjects" to include all the available subjects (otherwise, WTools will ask to select which subjects must be included).
Tick "Compute per subject average (for std err plots)" to compute subject-specific averages. This will allow plotting across-participants' standard errors (see functions "Average + StdErr" and "Chans Avg + StdErr"). 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.
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 "GrandAvg" subfolder of the "Analysis" folder.
Please read below if you need to re-run an analysis or incorporate new subject data into the same project.
Ideally, an analysis should be conducted only once per project. This is because WTools does not retain user-set parameters throughout processing; the data files it produces do not store this information. While the parameters are saved in configuration files, they can be altered if the analysis is repeated, leading to discrepancies between the parameters and the output data that are not overwritten by the new processing.
For instance, if you opt to include new subjects in the analysis and conduct the analysis solely on those with different parameters compared to the initial analysis, you may end up with inconsistent output files in the project directories. It can be challenging to differentiate between files generated during the first and second analysis, potentially resulting in errors or inaccurate results. To mitigate this risk, WTools issues repeated warnings and mandates that users revisit the subsequent signal processing steps (Chop & Baseline, Condition Difference, Grand Average), even if parameters remain unchanged.
While this process may be cumbersome and does not eliminate the possibility of inconsistencies, it serves as a deterrent against such practices. Experienced users willing to take the risk and find the WTools alerts bothersome can disable some of them through the corresponding option in the application configuration (see "Application functions").
WTools provides several types of plots to visualise the outcome of the analysis:
- Average
- Average & standard error
- Channels average
- Channels average & standard error
- 2D scalp maps
- 3D scalp maps
Some of these involve multiple hierarchically organized figures. For instance, the Average plot (see below) generates several main (or summary plot) Matlab figures equal to the selected experimental conditions. Each of these main figures contains small-format sub-plots (tiles) displaying the average data per channel, arranged in a 2D layout mirroring the electrode distribution. Clicking on any sub-plot tile opens a new sub-figure that magnifies the content of the selected tile. The sub-figure is displayed on the screen in a position corresponding to the sub-plot tile's location on the main figure, adjusted for different aspect ratios between the main figure and the screen. Because multiple figures can be opened simultaneously, the screen can quickly become cluttered. Also, the tiles on the main figures may overlap when certain channels are nearby in the 2D distribution. To enhance navigation across figures, WTools offers basic mouse and keyboard controls:
| Control device | Scope | Action | Effect |
|---|---|---|---|
| mouse/touch-pad | any main figure | central wheel/2 fingers slid | decrease/increase the tiles size |
| mouse/touch-pad | any sub-figure | left button click/single touch | changes sub-figure grid type |
| keyboard | any main figure | +/- key press | decrease/increase the tiles size |
| keyboard | any main figure | r key press | reset position and size of the relative sub-figures on-screen |
| keyboard | any main figure | h key press | hide the main figure and all the relative sub-figures |
| keyboard | any main figure | a key press | bring all main figures to the front (including hidden ones) |
| keyboard | any main figure | q key press | close all figures and sub-figures |
| keyboard | any sub-figure | m key press | bring to front the relative main-figure |
- Please be aware that not all the controls mentioned above are universally applicable, as some may not be relevant for certain plots.
- On MacOS, keyboard controls seem to be functional only after clicking on the top of the window frame of a figure.
- The main figure of certain plots is resizable, but WTools will keep their original aspect ratio; that does not apply when a figure window switches to full-screen mode or is maximised.
For plots that exhibit a color bar, WTools provides a convenient way to adjust the relative scale edges through 2 sliders appearing normally to the right of the colormap axes (for the 3D scalp map plot, they are placed to the left of the scalp axes). Such plots also include an extra panel on the top of the figure with 3 buttons labelled with the letters I, W and D. They control the ranges of the sliders:
- I button: set the ranges to the initial value defined by the user
- W button: set the ranges to the WTools guess (usually large enough)
- D button: set the ranges accordingly to the data range You can see an example below:
The label of the relevant axis is formatted to provide as much information as possible about what's being visualised. That depends on the options for processing in the previous steps. The label is a dot-separated string of tokens followed by a [dimension] detail. The possible tokens are:
| Token | Description | Dependency |
|---|---|---|
| EO | Evoked Oscillations | Transform parameters |
| Pw | Power | Transform paramaters |
| BS | Baseline Subtraction only | Baseline correction & chopping parameters |
| BN | Baseline Normalisation only | baseline correction & chopping parameters |
| BSN | Baseline Subtraction & Normalisation applied | Baseline correction & chopping parameters |
| (Ratio) | Adimensional measure | Baseline correction & chopping parameters |
| dB | Decibel | Plot parameters |
The possible dimensions:
| Dimension | Description | Dependency |
|---|---|---|
| [μV] | The module (amplitude) of the transform | Transform parameters |
| [μV²] | The power of the transform | Transform parameters |
Notice that although the dimension detail is always appended, when the label contains (Ratio) or dB, it refers to the original signal before the application of the baseline normalisation or the calculation of the Decibel.
All plots include the option for visualising data in decibels. Converting the data into decibels requires calculating the log10, then multiplying it by 10 or 20, depending on whether you are working with the power or the amplitude of the signals. The processed data might well assume values <= 0 (especially after a baseline subtraction operation), hence, to apply the log10, it might be necessary to SHIFT the signals by adding the minimum constant (DC component), which makes them positive. In such an event, each concerned plot will report the additional detail of the entity of the shift either in the title or in the legend. You will usually see a label like DC Shift: {some number}. So be aware of what you are looking at.
You may notice that some checkboxes in the plot parameters selection dialogs are grayed and cannot be modified. Such parameters are simply meant to remind the user of the previous choices that have been made during the processing: so far, there can only be one single configuration active for such parameters, per analysis session. Possibly, in the future, they might become accessible and allow us to choose the relevant option.
Aims: Plot time-frequency graphs for all desired channels in a topographical arrangement.
Walkthrough: Select individual data files from the corresponding subject-specific folder or average group data files from the "GrandAvg" folder (here, we select file "04_GD_bc-avWT.mat").
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):
If you plot all channels in topographical arrangement (see below), you can hover your cursor over the individual graphs and see the corresponding channel label highlighted in red in the top right corner of the figure.
You can also click on any graph to see it pop up in a zoomed-in window.
A DC shift, if necessary, is calculated and applied on a per-channel basis.
Aims: Plot a time-frequency graph which is the average of the desired subset of channels.
Walkthrough: Select individual data files from the corresponding subject-specific folder or average group data files from the "GrandAvg" folder (here, we select file "04_GD_bc-avWT.mat").
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. See the output below:
A DC shift, if necessary, is calculated and applied on a global base, after the calculation of the average across channels.
Aims: Plot mean +/- SEM graph for all desired channels in a topographical arrangement for max 2 conditions.
Walkthrough: Select mean +/- SEM data (.ss files) from the "GrandAvg" subfolder of the "Analysis" folder (here, we select "GD_bc-avWT.ss").
Enter the time and frequency ranges of interest, and tick the box "Plot all channels" if you want to plot the mean +/- SEM graph for all channels in topographical arrangement (otherwise, WTools will ask which channels you want to select). Here we selected all channels and files "GD_bc-avWT.ss" and "GA_bc-avWT.ss":
Below is the detail for channel 35:
- ChansStdDev, ChansAvg = std(mean(DATA, 2), 0, 4);
- ChansStdErr = squeeze(ChansStdDev./sqrt(size(DATA, 4)));
Where DATA is a 4D matrix (channels, frequencies, times, subjects)
A per-channel DC shift, if required, is calculated and applied separately (on a per-channel base) for the average and the standard error, after averaging across frequencies.
Aims: Plot mean +/- SEM graph which represents the average of the desired subset of channels for max 2 conditions.
Walkthrough: Select mean +/- SEM data (.ss files) from the "GrandAvg" subfolder of the "Analysis" folder (here, we select "GD_bc-avWT.ss" and "GA_bc-avWT.ss").
Enter the time and frequency ranges of interest.
Select the channels to average for the mean +/- SEM graph. Here, we ask for the average of channels 15 and 22, corresponding to Fpz and Fp2, respectively.
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 250 and 350 ms in the frequency range 20-50 Hz on frontal channels, it suggests that there might be a statistically significant difference there.
- ChansStdDev, ChansAvg = std(mean(mean(DATA, 1), 2), 0, 4);
- ChansStdErr = squeeze(ChansStdDev./sqrt(size(DATA, 4)));
Where DATA is a 4D matrix (channels, frequencies, times, subjects)
A DC shift, if required, is calculated and applied separately (on a global base) for the average and the standard error, after averaging first across channels and then across frequencies.
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 individual data files from the corresponding subject-specific folder or average group data files from the "GrandAvg" folder (here, we select file "04_GD_bc-avWT.mat").
We request the scalp map for time point [300] at frequency [35]:
Here, we request the scalp map for the average of time points in range [250 350] at frequency [35]:
Here, we request the scalp map for the average of frequencies in range [30 40] at time point [300]:
Here, we request a series of scalp maps for the time series [200:10:250] at a certain frequency [35] and we inspect specifically the 200ms time by clicking on the relative image in the main plot:
Here, we request a series of scalp maps for the frequency series [25:5:50] at a certain time point [300] and we inspect specifically the 25Hz frequency by clicking on the relative image in the main plot:
A DC shift, if necessary, is calculated and applied depending on the definition of the times and frequencies plot parameters:
- in case of time series, on a per time base after average across the frequency range
- in case of frequency series, on a per frequency base after average across the time range
- in case of no series, on a global base, after average across frequency and time range
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 due to computational load.
Walkthrough: Select the spline configuration file (you need to select it only once per project, then it is saved in the project configuration settings). Here, we select Infant-GSN-HydroCel-129.spl.
Select individual data from the corresponding subject-specific subfolder or average group data from the "GrandAvg" subfolder of the "Analysis" folder (here, we select subject "04"). Select the condition to plot (here, we select "GD"). The GUI follows the same logic as for 2D scalp maps (previous section). As an example, we request the scalp map for time point [300] at frequency [35]:
A DC shift, if necessary, is calculated and applied on a global base, after averaging across time & frequencies.
For adult data, you can select one of the following configuration files:
- GSN-HydroCel-129.spl: for 128-channels EGI MEGSTIM recording system
- ANT-23Ch.spl: for 23-channels ANT recording system
- Biosemi_35Ch.spl: for 35-channels Biosemi recording system
For infant data, you can select one of the following configuration files:
- Infant-GSN-HydroCel-129.spl: for 128-channels EGI MEGSTIM recording system
- Infant-ANT-23Ch.spl: for 23-channels ANT recording system
- Infant-Biosemi-35Ch.spl: for 35-channels Biosemi recording system
For all infant layouts, we provide a head model of a 9-month infant that has been derived from the [Neurodevelopmental MRI Database (https://jerlab.sc.edu/projects/neurodevelopmental-mri-database/) (file
ANTS9-0Months1-5T_head.nii.gz). For head models of different developmental ages, users have the option to create custom spline configuration files and include them in this folder for their specific requirements. Feel free to reach out for more information (see Contact details).The spline file is paired with the imported data through the channel labels (from the channels layout). Before applying a spline file, WTools checks whether it fits the data channels layout. If some issues or differences are detected, a report is produced (together with a detailed log). If no channels match, the pairing is not possible, and the spline is rejected. In other cases, the spline has to be adjusted to fit the channel layout, and you are asked to validate/accept the result of the correction applied:
By inspecting the report and the log file, you can determine if you have possibly selected the wrong spline file. If so, you can choose another one. In the example above, the selected spline matches only one data channel out of 125, so it is an error.
Aims: Extract numeric values for each desired subject, condition and channel, computing the average value both in a time range 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: Enter the desired time range (here, [200 400] ms) and frequency range (here, [30 40] Hz). Select the desired subjects and conditions (by default, all subjects and conditions are included).
A text-tabulated file with the extracted values will be saved in the "Statistics" folder. Rows correspond to subjects, and columns correspond to conditions and channels (see headers).
Aims: Configure/monitor WTools
On the main application panel:
-
Log level: set the log level for the current MATLAB session. About log levels:
- ERROR: prints errors only
- WARNING: additionally prints warnings
- INFO: additionally prints processing steps (recommended as default)
- DEBUG: additionally prints information relevant to debugging
-
Status label on the main panel: show the current status of WTools
- IDLE: WTools is ready to accept any user input
- BUSY: WTools is performing some processing, and you should wait until it goes back to IDLE
-
Configure: define the general configuration settings of the toolbox. Note: you need to restart the toolbox to enable the changes.
- Help: open the WTools wiki page.
With the log level control in the main panel, you select the level of detail of what is printed in the MATLAB command console during the current WTools session. Instead, with Project log and Project log level in the application configuration panel (see picture above), you control whether the log is persisted in the Logs project sub-directory and its level of detail (independently from the console level). WTools creates a new log file every time a project is opened or created.
Eugenio Parise
CIMeC, Center for Mind/Brain Sciences
University of Trento
Corso Bettini 31
38068, Rovereto, Italy
Telephone: +39 0464 808660
E-mail: eugenio.parise@unitn.it