Writing an EEGLAB plugin

Why do I need this step?

A plugin is simpler than you might expect. It is a folder inside the EEGLAB plugins folder, holding two files:

• A file whose name starts with eegplugin_. EEGLAB runs it at every startup, and its only job is to add the item to the menu.
• A function whose name starts with pop_. This is the tool itself: it opens a window when arguments are missing, and it returns the command string that reproduces the same result, so it appears in the command history.

The second rule is what makes your tool part of your script. Every click on your item appears in eegh as a line of code, as you learned in the command history lesson.

In this lesson we write a plugin called chanvar: it plots the standard deviation of each channel and colors in red the channels far from the rest. A quick check tool, before or after the bad channels lesson.

How do I do it in EEGLAB?

First: create the plugin folder

1. Type in the command window:

pluginDir = fullfile(fileparts(which('eeglab')), 'plugins', 'chanvar1.0');
mkdir(pluginDir); cd(pluginDir);

The folder name carries the version: EEGLAB reads chanvar1.0 as a plugin named chanvar, version 1.0.

Second: write the pop_ function

2. Type edit pop_chanvar.m, paste this code, and save:

function com = pop_chanvar(EEG, zThresh)
% POP_CHANVAR - Plot the standard deviation of each channel and
%               highlight channels far from the others.
%
% Usage:
%   >> pop_chanvar(EEG);           % ask for the threshold in a window
%   >> pop_chanvar(EEG, zThresh);  % plot directly
%
% Inputs:
%   EEG     - EEGLAB dataset
%   zThresh - robust z-score above which a channel is highlighted
%             (default in the window: 3)
%
% Output:
%   com     - command string for the EEGLAB history

com = '';
if nargin < 1
    help pop_chanvar;
    return;
end

% Missing threshold: ask for it
if nargin < 2
    res = inputgui('geometry', {[2 1]}, ...
        'uilist', { {'style', 'text', 'string', 'Robust z-score threshold'}, ...
                    {'style', 'edit', 'string', '3'} }, ...
        'title', 'Channel variance -- pop_chanvar()');
    if isempty(res), return; end   % user pressed Cancel
    zThresh = str2double(res{1});
end

% Standard deviation of each channel over all samples (and epochs)
data = double(reshape(EEG.data, EEG.nbchan, []));
sd   = std(data, 0, 2);

% Robust z-score based on the median absolute deviation
medSd = median(sd);
z = (sd - medSd) / (1.4826 * median(abs(sd - medSd)));
flagged = find(z > zThresh);

% Plot
figure('Name', 'Channel variance');
bar(sd, 'FaceColor', [0.6 0.6 0.6]); hold on;
if ~isempty(flagged)
    bar(flagged, sd(flagged), 'FaceColor', [0.85 0.2 0.2]);
end
set(gca, 'XTick', 1:EEG.nbchan, 'XTickLabel', {EEG.chanlocs.labels});
xtickangle(90);
ylabel('Standard deviation (\muV)');
title(sprintf('%s: %d channel(s) above z = %g', EEG.setname, ...
    numel(flagged), zThresh), 'Interpreter', 'none');
if ~isempty(flagged)
    fprintf('Channels above threshold: %s\n', ...
        strjoin({EEG.chanlocs(flagged).labels}, ' '));
end

% Command that reproduces this call
com = sprintf('pop_chanvar(EEG, %g);', zThresh);

Third: write the eegplugin_ file

3. Type edit eegplugin_chanvar.m, paste this code, and save:

function vers = eegplugin_chanvar(fig, trystrs, catchstrs)
% EEGPLUGIN_CHANVAR - Add "Channel variance" to the EEGLAB Plot menu.

vers = 'chanvar1.0';

% Find the Plot menu of the main EEGLAB window
plotmenu = findobj(fig, 'tag', 'plot');

% Check the data, run the function, then add its command to the history
cmd = [trystrs.check_data 'LASTCOM = pop_chanvar(EEG);' catchstrs.add_to_hist];
uimenu(plotmenu, 'Label', 'Channel variance', 'CallBack', cmd, 'Separator', 'on');

Fourth: try the plugin

4. Close the EEGLAB window and type eeglab again, because EEGLAB looks for plugins only at startup. The command window prints a line containing adding "chanvar" v1.0.
5. Load D1 as in “Starting point”, but from the GUI: File › then Load existing dataset.
6. Open Plot › then Channel variance. Your window appears with 3 in it. Click Ok. The plot appears.
7. Type eegh. The last line is pop_chanvar(EEG, 3);. Your tool is now part of the command history like any official tool.

How do I write it as code?

The pop_ function also works from a script, without the menu. This test checks the basic rule: the string the function returns reproduces the same result.

eeglab nogui
eeglabRoot = fileparts(which('eeglab'));
EEG = pop_loadset('eeglab_data.set', fullfile(eeglabRoot, 'sample_data'));

% The plugin folder is on the path even without the GUI
assert(exist('pop_chanvar', 'file') == 2, 'pop_chanvar not found: check the plugins folder');

% Call with all arguments: no window, direct plot
com = pop_chanvar(EEG, 3);
disp(com);   % pop_chanvar(EEG, 3);

% Running the returned command must reproduce the same figure
eval(com);

Which value should I choose?

How do I check it worked?

• When you start eeglab, the command window prints a line containing adding "chanvar" v1.0.
• The Plot › then Channel variance item exists and opens a window with the threshold box.
• After clicking Ok, a bar plot appears with one bar per channel (32 in D1).
• eegh shows pop_chanvar(EEG, 3);, and the script above runs without error.

What mistakes do people make?

• Putting the two files outside the plugins folder. EEGLAB does not look anywhere else, so the item does not appear.
• A pop_ function that returns nothing. Without com, nothing is recorded in eegh, so your click cannot be repeated in your script.
• A command string that does not reproduce the result. If the user types 2.5 in the window, the string must be pop_chanvar(EEG, 2.5);, not the default value. That is why com is built from the values actually used.
• Expecting the item to appear with eeglab nogui. In this mode EEGLAB adds the plugin folder to the path but does not run eegplugin_, so there are no menus. This is normal.
• Testing the plugin from the menu only. EEGLAB catches errors coming from menus. To trace an error, type dbstop if error and call the function from the command window (advice from the official documentation).

Going further

• EEGLAB Tutorial: https://eeglab.org/tutorials/contribute/design_plugin.html (Contribute > Create an EEGLAB plugin)
• EEGLAB Tutorial: https://eeglab.org/tutorials/ConceptsGuide/EEGLAB_functions.html (Concepts guide > EEGLAB functions)