1. Introduction Installation and requirements... 2

Transcription

1 1 Table of Contents 1. Introduction Installation and requirements Utilization of the CRB analysis plugin through the interactive graphical interfaces 3.1 Initial settings Results inspection, parameters refining and custom analysis How to save results How to launch the CRB analysis from the command line... 10

2 2 1. Introduction The CRB analysis plugin for EEGLAB is a software tool for performing the channel reactivity based (CRB) analysis of either EEG scalp channels or ICA independent components (ICs); it allows to localize alpha responsiveness regions and estimate individual alpha frequencies (IAFs) and channel alpha frequencies (CAFs) through the method described in "Goljahani A, D'Avanzo C, Schiff S, Amodio P, Bisiacchi P, Sparacino G. A novel method for the determination of the EEG individual alpha frequency. NeuroImage, 2012; 60: ". The source code, distributed under the GNU General Public License ( is freely available for download from The plugin allows to easily define initial settings, inspect results, refine CRB algortihm's parameters and save results through intuitive interactive graphical user interfaces (GUIs). The CRB analysis can be launched both from the Tools menu of the EEGLAB graphic interface and directly from the command line with and without graphical supports, e.g. for carrying out batch analyses. This documentation is about the CRB analysis plugin functionalities. The reader is referred to the EEGLAB documentation ( for instructions on e.g. EEGLAB installation, ICs computation, etc.. The documentation is organized as follows. After instructions on installation and requirements (Section 2), first, the utilization of the plugin through the GUIs will be illustrated (Section 3) and, then, command-line options for launching the CRB analysis will be described (Section 4). 2. Installation and requirements For installing the CRB analysis plugin in EEGLAB ( ), it is sufficient to unzip the file downloaded from the link and place the CRBanalysis folder in the plugins subdirectory of the main EEGLAB directory. For utilizing the functions from the command-line (see Section 4), the location of the CRBanalysis folder should be included in the Matlab path. Besides, for utilizing the EEGLAB functions embedded in the code, the paths '...\eeglabroot\functions\sigprocfunc', '...\eeglabroot\functions\popfunc', and '...\eeglabroot \functions\adminfunc ' should be included in the Matlab path. In case they are not, EEGLAB functions will be simply ignored. For utilizing the plugin, Matlab (The Mathworks, Inc.) is required, together with signal processing and statistics toolboxes. Both for launching the CRB analysis from the EEGLAB graphic interface and for utilizing EEGLAB functions embedded in the code, an installation of EEGLAB ( ) is also required. Routines were implemented in Matlab R2011a 64-bit and should theoretically work with all the latest versions of Matlab, 32 and 64 bit, and EEGLAB. Up to now, it has been successfully tested on EEGLAB v b in a 64-bit Windows 7 (Microsoft corporation) environment equipped with 8 GB of RAM. Since Matlab is a cross-platform environment, the plugin should potentially be compatible with 32-bit Windows environments, and Linux and OS X (Apple, Inc.) operating systems as well.

3 3 3. Utilization of the CRB analysis plugin through the interactive graphical interfaces By installing the CRB analysis plugin in EEGLAB, the CRB analysis menu is included in the Tools menu of EEGLAB, as shown in Fig Initial settings Figure 1 By clicking on the CRB analysis menu illustrated in Fig.1, the GUI for defining initial settings, shown in Fig. 2 for a sample dataset, pops up. Figure 2

4 4 Dataset info panel: -contains information on the dataset loaded in EEGLAB, CRB data selection panel: - select channel data for running the CRB analysis on channel data; select component activations for running the CRB analysis on ICA independent components (ICs).; - press the list channels button for running the CRB analysis on a subset of channels selected (Ctrl+click) from the list; press list components for running the CRB analysis on a subset of components selected (Ctrl+click) from the list; - press the plot channel locations button for displaying the EEGLAB topographic plot of channels locations; press the plot components maps button for displaying the the EEGLAB 2-D plot of component maps; Temporal intervals and parameters for the estimation of power spectrum densities (PSDs) panel: - insert in the Reference interval and Test interval forms the reference and test time intervals for estimating the reference and test PSDs; reference and test intervals are needed for carrying out the analysis; - push the channel ERPs button for displaying the EEGLAB channel ERPs plot; push the component ERPs button for displaying the EEGLAB component ERPs plot Parameters for Psd estimation subpanel: - the psd estimation method is the Welch method; - select the window type from the Window type list; -insert the window length and percentage of windows overlap for the reference PSD estimation in the reference interval's window length(ms) and overlap (%) form; by default, the window length is equal to the reference interval and the percentage of overlap is zero; -insert the window length and percentage of windows overlap for the test PSD estimation in the test interval's window length(ms) and overlap (%) form; by default, the window length is equal to the reference interval and the percentage of overlap is zero; -insert the number of PSD samples to be estimated in the Number of PSD samples form; the Corresponding frequency quantum is computed as the ratio between the data sample rate and the number of PSD samples; by default the number of PSD samples is such as the frequency quantum is not greater than 0.1 Hz. -insert in the frequency limits (Hz) form the frequency interval (values in Hz separated by comma) for resting and test PSDs estimation; by default it is equal to the interval 0 to one fourth of the data sampling rate.

5 5 CRB analysis parameters panel: - insert the values of parameters needed for applying the CRB algorithm in the corresponding forms; please, please refer to Section 3.3 of Goljahani et al, NeuroImage, 2012 for guidelines on parameters settings; - insert optional parameters in the Additional optional parameters form, e.g. 'scan_interval';'0,30' for setting the scanning interval of the scanning phase of the algorithm to the interval (0,30) Hz (see Goljahani et al, NeuroImage, 2012 for the Steps and phases of the CRB algorithm); -check Perform only Step 1 for executing only the Step 1 of the CRB algorithm; results will comprise the responsiveness intervals, the relative rho and CAF values, etc., but the selection of channels/components won't be executed; By pressing the run CRB analysis button, the CRB analysis will be carried out on the selected data and the GUI for saving results, illustrated in Section 3.3, will be displayed. By pressing the show results button, the CRB analysis will be carried out on the selected data and the results will be shown in the GUI for numerical values inspection, described in section 3.2. If include spectra plots is checked, also spectra plots with highlighted responsiveness regions will be displayed in GUI for spectra plot inspection, described in section 3.2. The plots will be limited to the frequency interval inserted in the frequency range in Hz form and to the channels/components selected from the list obtained by pressing select channels/components to plot. 3.2 Results inspection, parameters refining and custom analysis Results of the CRB analysis can be inspected by exploring both a table of numerical values in the GUI for numerical values inspection, Fig. 3 for a sample dataset, and plots of channels/component spectra in the GUI for spectra plots inspection, Fig. 4 for a sample dataset, with responsiveness intervals localized by the CRB algorithm highlighted in grey. Figure 3

6 6 Figure 4 GUI for numerical values inspection: - the table contains, for each channel/ic, the selected flag, which denotes whether the channel/ic was selected (1) or not (0) by the CRB algorithm, the channel alpha frequency, CAF, and reactivity index, ρ, values relative to the responsiveness interval (f_1,f_2), the powers of the signal in the responsiveness band (f_1,f_2) during the reference (ref power) and test (test power) intervals, and their relative percentage variation (rel. power var. (%)) computed as (test power - ref power)/ref power x 100 (ERD% in Pfurtscheller and Lopes da Silva, Clin. Neurophysiol., 1999). NaN values are inserted if the algorithm didn't localize any responsiveness interval. The first (selected), fourth (f_1) and fifth (f_2) columns of the table can be edited for custom analysis. If the user is interested in computing rho, CAF, reference and test powers, and relative power variation percentage for a custom set of channels and responsiveness intervals, it is sufficient to set to one their selected value and insert the intervals boundaries (Hz) in the columns f_1 and f_2. By pressing twice the Recompute with new table values button, new values are computed and inserted in the table. The IAF is, finally, computed as the median of the CAFs relative to the channels/ics selected by the user. - the CRB analysis parameters panel allows to refine CRB algorithm's parameters; by inserting new parameter values and pressing the Recompute with new parameter values button, results are recomputed

7 7 and the table is updated with new values; please refer to Section 3.3 of Goljahani et al, NeuroImage, 2012 for guidelines on parameters settings; - press the Restore initial values button for restoring initial values after having modified the table either by manually modifying it or by re-computing results with new parameter values; - press the Plot channel locations button for displaying the EEGLAB topographic plot of channel locations; - press the plot spectra button for launching the GUI for spectra plots inspection with reference and test PSDs plotted together with responsiveness intervals, CAFs and IAF values reported in the table for the channels/ics selected from the list displayed by pressing the Select channels/ics to plot button; the frequency range of the plots can set by inserting the interval's boundaries in the form Frequency range to plot (Hz); - press the save results button for saving results through the interactive GUI described in section 3.3. GUI for spectra plots inspection - each plot in the GUI depicts, for the channel/ic in the title, the reference (red) and test (blue) PSDs, the responsiveness interval, shaded in gray, the CAF, as a vertical thin solid black line, the IAF, as a vertical thick solid black line, and the local IAF, as a vertical thin dashed black line. The latter is computed as the median of the channels/ics selected by the CRB algorithm among those chosen for plotting. The checking of the checkbox in the right upper corner of the plots denotes the channel/ic was selected by the algorithm. If the user is interested in evaluating the effect on the IAF value of discarding or including a channel/ic, it is sufficient to check, respectively uncheck, the checkbox next to its plot. Accordingly, the IAF and local IAF values, textually reported at the bottom of the GUI, are updated. At the bottom of the GUI it is also reported the local average responsiveness interval, local ave alpha, computed by averaging the boundaries of the responsiveness intervals of the channels/ics with the checkbox checked among those plotted. If you are interested in obtaining ρ and CAF values relative to responsiveness intervals different from those highlighted in the plots, a drag and drop mechanism is provided. Position the cursor at any point of the plot with the abscissa at one of the boundaries of the new responsiveness interval, press the left button of the mouse and release it at the other boundary of the interval. The new interval shades gray, CAF and rho values relative to the new interval are computed and their values is updated. If the channel/ic was among those selected by the algorithm or the user, also IAF, local IAF and local average responsiveness intervals are updated. By pressing the Synchronize with table data button, table values relative to the plotted channels are updated with new CAFs, ρs and powers values. Note that for updating the IAF value at the bottom of the GUI for numerical values inspection and finalize the table update the Recompute with new table values button GUI for numerical values inspection in the has to be pressed. - check the topographic plots checkbox for turning to a topographic plot, if channel locations information are available; - utilize the XLim form for modifying the frequency range of the plots; - check the Equalize YLim checkbox for making the all the y axis range of the plots equal to the interval inserted in the range form; - press the Restore initial values for restoring initial values and plotting ranges.

8 8 3.2 How to save results The GUI for saving results is shown in Fig.5. Figure 5 - check the save results in a.txt file checkbox for saving results in a text file. Results will be arranged as in the table of the GUI for numerical values inspection, Fig. 3, with an additional first column reporting the IAF value. Insert the name of the txt file in the insert file name form. Insert the file path in the filepath. If needed, the browse button can be pressed for graphically browsing directories. If the filepath form is left empty, the file is placed in the current directory. - check the save results as a CRB struct in a.mat file for saving results in a Matlab mat file. Results will be embedded in the CRB struct with the following fields: Table 1 CRB. results cell matrix containing results arranged in a table as in the.txt case colnames cell vector of strings containing the names of the columns of the CRB.results cell matrix rownames cell vector of strings containing the names of the rows (chennel/ic labels) of the CRB.results cell matrix results_num numerical matrix containing the numerical results in the cell matrix CRB.results L. struct with CRB channels/ics selection (Step 2) parameters and results rho_min minimum ρ values under which no activity is considered to be present (see Section ) of Goljahani et

9 9 al., NeuroImage, 2012 r fraction of the maximum channels/ics reactivity indexes that renders a channel/ic with a smaller ρ value out of range for the subject (see section of Goljahani et al., NeuroImage, 2012 ) p percentile value for computing the subject's specific threshold ρ sub (eq. (3) of Goljahani et al, NeuroImage, rho_sub 2012) for selecting channels/ics subject's specific threshold ρ sub (see eq. (3) of Goljahani et al, NeuroImage, 2012) for selecting channels/ics rhos_thresh minimum ρ value for selecting channels/ics at Step 2 of the algorithm (see eq. (2) of Goljahani et al, NeuroImage, 2012) indexes numerical vector of channels/ics indexes selected by the CRB algorithm If the include average spectra checkbox is selected, the.mat file will include also the spectra struct with the following fields Table 2 spectra. ave_refspectra numerical matrix (Number of channels/ics x Number of frequency points) containing average reference spectra ave_testpsectra numerical matrix (Number of channels/ics x Number of frequency points) containing average test spectra f numerical vector (Number of frequency points x1) of frequency points labels cell vector (Number of channels/ics x 1) of strings Besides CRB and spectra, the strcuct par containing all the parameters utilized for running the CRB routines is also saved in the mat file. The struct is described in Section 4. - check the save results in the CRB field of the EEG struct checkbox for saving results in the CRB field of the EEGLAB EEG struct. The fields of the CRB struct are as in Table 1, with the inclusion of the struct par, Table 3, as its field and of the struct spectra, Table 2, if the include average spectra checkbox is selected.

10 10 4. How to launch the CRB analysis from the command line The CRB analysis can also be launched from the Matlab command line through the functions pop_crbanalysis() and CRBanalysis(). Depending on the input arguments, pop_crbanalysis() may display interactive GUIs for, e.g., defining initial or saving settings, and calls CRBanalysy(), which is the core function that runs the CRB algorithm on the input data. The function EEG=pop_CRBanalysis(EEG,typeproc,par): - launched with no arguments - pop_crbanalysis() - displays the function's help - launched with the EEGLAB EEG struct as its first argument - EEG=pop_CRBanalysis(EEG) - first displays the GUI for initial settings, Fig. 2, then calls the CRBanalysis() with the parameters defined by the user, and, finally, displays the GUI for saving results, Fig. 5, for defining the saving modalities; - launched with the EEGLAB EEG struct as its first argument and the typeproc flag, equal to 0 for processing ICs and to 1 for processing channel data, as its second argument - EEG=pop_CRBanalysis(EEG,typeporc) - first displays the GUI for initial settings, Fig. 2, then calls the CRBanalysis() with the parameters defined by the user, and, finally, displays the GUI for saving results, Fig. 5, for defining the saving modalities; - launched with the EEGLAB EEG struct as its first argument, the typeproc flag, equal to 0 for processing ICs and to 1 for processing channel data, as its second argument, and the struct par as its third argument - EEG=pop_CRBanalysis(EEG,typeporc,par) - GUIs are displayed or not depending on the settings embedded in the par struct. The properties of the par struct are summarized in Table 3. Table 3 par. chanlocs struct - optional - EEG chanlocs structure labels cell vector of strings - optional - data channels/ics labels CRB_dataindexes numerical vector - indexes of the channels/ics to submit to CRB analysis - default: 1: Number of channels executeandsave flag (0/1) - optional - flag for executing and saving results without showing them in interactive GUIs - default: 1; if par.executeandsave==1 and par.savepar is not empty, data are saved without displaying any GUI, otherwise the GUI for saving results. showresults flag (0/1) - optional - flag for showing results in the GUI for numerical values inspection, Fig. 3, before saving them - default: 0

11 11 spectraplots plotspar. CRBpar. savepar. flag (0/1) - optional - flag for plotting spectra in the GUI for spectra plots inspection, Fig. 4, before saving results - default: 0 struct - optional - struct with settings for plotting spectra in the GUI for spectra plots inspection indexes numerical vector - optional - indexes of data to plot among those submitted to CRB analysis labels cell vector of strings - optional - plots labels freq_range numerical vector - optional - frequency range to plot struct of parameters for applying the CRB analysis, see Table 4 struct of settings for saving results; if par.savepar is empty, the GUI for saving results pops up txt flag (0/1) - optional - flag for saving results in a txt file; txtpar. filename string - needed if par.savepar.txt==1 - txt file name filepath string - optional - txt file path - default: '.' (current directory) mat flag (0/1) - optional - flag for saving results in a mat file; matpar. filename string - needed if par.savepar.mat==1 - mat file name filepath string - optional - mat file path - default: '.' (current directory) includeavespectra flag (0/1) - optional - flag for saving average spectra in the mat file -

12 12 CRBfield includestspectra flag (0/1) - optional - flag for saving results in the CRB field of the EEG struct; default: 0 flag (0/1) - optional - flag for saving single trial spectra in the mat file - default: 0 CRBfieldpar. includeavespectra flag (0/1) - optional - flag for saving average spectra in the CRB field - default: 0 includestspectra flag (0/1) - optional - flag for saving single-trial spectra in the CRB field - default: 0 Note that pop_crbanalysis() can be launched by only setting the CRBpar field values marked as NEEDED in Table 4. Moreover, by also defining the saving settings in the the savepar field, the CRB analysis is run and results are saved without displaying any GUI. Once data have been extracted from EEG by utilizing par.typeproc and par.crb_dataindexes values, the function CRBanalysis() is called. CRBanalysis can also be directly launched from the command-line as [CRB spectra]= CRBanalysis(data,CRBpar), where - data is a numerical matrix (Number of channels/ics x Number of time points x Number of epochs) or a cell vector of two numerical matrix (Number of channels/ics x Number of frequency points), depending on the settings in CRBpar; - CRBpar is the struct of CRB algorithms's parameters described in Table 4; -CRB and spectra are the struct described in Table 1 and 2. Table 4 CRBpar. spectraldata flag (0/1) - optional - if CRBpar.spectraldata==0, the input parameter data is a numerical matrix, otherwise it is a cell vector containing the matrix of average reference spectra and average test spectra - default: 0 onlyspectra flag (0/1) - optional - if CRBpar.onlyspectra==1, only spectra

13 13 are computed and the output CRB is left empty - default: 0 onlystepone flag (0/1) - optional -flag for performing only Step 1 of the CRB algorithm - default: 0 customanalysis flag (0/1) - optional -flag for carrying out custom analysis singletrialspectra flag (0/1) - optional - if CRBpar.onlyspectra==1 the fields singletrial_refspectra and singletrial_testpsectra are included in the spectra output - default: 0 labels cell vector of strings - optional - labels of channels/ics timeintervals struct - NEEDED if CRBpar.spectraldata==0 t spectrapar ref_int test_int struct - NEEDED if CRBpar.spectraldata==1 - strcut of parameters for reference and test spectra computation srate method win_type ref_winlength ref_winoverlap test_winlength test_winoverlap numerical vector- NEEDED if CRBpar.spectraldata==0 - data time vector (ms) numerical vector- NEEDED if CRBpar.spectraldata==0 - reference interval (ms) numerical vector- NEEDED if CRBpar.spectraldata==0 - test interval (ms) scalar - optional string - 'Welch' string {'Hanning','Hamming','None'} - optional - window type for PSDs estimation - default: 'Hanning' scalar - optional - length of the window for reference PSD estimation - default: length of the reference interval scalar - optional - percentage of windows overlap for reference PSD estimation - default: 0 scalar - optional - length of the window for test PSD estimation - default: length of the test interval scalar - optional - percentage of windows overlap for test PSD estimation - default: 0

14 14 custom algpar freq_lim Nfft struct - optional - CRB parameters (see Section 3.1) - default values are reported on the right scan_interval alpha_interval w_size w_shift lambda epsilon rho_min r p lambda_left epsilon_left struct - NEEDED if CRBpar.customanalyis==1. bands - numerical matrix (length of par.custom.indexes x 2) - NEEDED if CRBpar.customanalyis==1- user's defined bands for computing rho and CAF values. indexes - numerical vector - NEEDED if CRBpar.customanalysis==1 - indexes of channels selected for carrying out custom analysis and copmuting the IAF numerical vector - NEEDED if spectraldata==1 - spectra frequency range scalar- optional - number of PSD frequency samples to estimate CRBpar.spectrapar. freq_lim [8 13] (conventional alpha interval) (regularization factor for windows below the conventional alpha band; 1 is equivalent to not having any regularization) 0 ( parameter for selecting as lower boudaries of responsiveness intervals closure points that are not intersections; 1 is equivalent to looking for intersections) Note that the CRBanalysis() can be launched on a data matrix by only setting the timeintervals field.