% STD_DIPPLOT - Commandline function to plot cluster component dipoles. Dipoles for each

% named cluster is displayed in a separate figure. To view all the clustered

% components in the STUDY on the same figure (in a separate subplot), all

% STUDY clusters must be requested.

% To visualize dipoles, they first must be stored in the EEG dataset structures

% using DIPFIT. Only components that have dipole locations will be displayed,

% along with the cluster mean dipole (in red).

% Usage:

% >> [STUDY] = std_dipplot(STUDY, ALLEEG, clusters);

% Inputs:

% STUDY - EEGLAB STUDY set comprising some or all of the EEG datasets in ALLEEG.

% ALLEEG - global EEGLAB vector of EEG structures for the dataset(s) included in

% the STUDY. ALLEEG for a STUDY set is typically created using LOAD_ALLEEG.

%

% Optional inputs:

% 'clusters' - [numeric vector | 'all'] -> specific cluster numbers to plot.

% 'all' -> plot all clusters in STUDY.

% {default: 'all'}.

% 'comps' - [numeric vector] -> indices of the cluster components to plot.

% 'all' -> plot all the components in the cluster

% {default: 'all'}.

% 'mode' - ['together'|'apart'|'multicolor'] Display all requested cluster on one

% figure ('together') or separate figures ('apart').

% 'together'-> plot all 'clusters' individually in one multi-pane figure (without the gui).

% 'apart' -> plot each cluster in a separate figure.

% 'multicolor' -> plot all clusters in one figure,

% Note that this parameter has no effect if the 'comps' option (above) is used.

% {default: 'together'}

% 'figure' - ['on'|'off'] plots on a new figure ('on') or plots on current

% figure ('off'). If 'figure','off' does not display gui controls,

% Useful for incomporating a cluster dipplot into a complex figure.

% {default: 'on'}.

% 'groups' - ['on'|'off'] use different colors for different groups.

% {default: 'off'}.

% 'dipcolor' - [cell vector] color for dipoles in each cluster. (multicolor mode)

% 'dipsize' - [numeric vector] size for each cluster. (multicolor mode)

% {default if unspecified: will automatically color/size each

% cluster}

% Outputs:

% STUDY - the input STUDY set structure modified with plotted cluster

% mean dipole, to allow quick replotting (unless cluster means

% already exists in the STUDY).

% Example:

% >> [STUDY] = std_dipplot(STUDY,ALLEEG, 'clusters', 5, 'mode', 'apart', 'figure', 'off');

% % Plot cluster-5 component dipoles (in blue), plus their mean dipole (in red),

% % on an existing (gui-less) figure.

%

% See also POP_CLUSTEDIT, DIPPLOT

%

% Authors: Hilit Serby, Arnaud Delorme, Scott Makeig, SCCN, INC, UCSD, June, 2005

% 'groups' added by Makoto Miyakoshi on June 2012.

% 'multicolor' mode added by John Iversen to draw all clusters on

% a single panel, with each cluster indicated by different color/size dipoles.

% Copyright (C) Hilit Serby, SCCN, INC, UCSD, June 08, 2005, hilit@sccn.ucsd.edu

%

% This file is part of EEGLAB, see http://www.eeglab.org

% for the documentation and details.

%

% Redistribution and use in source and binary forms, with or without

% modification, are permitted provided that the following conditions are met:

%

% 1. Redistributions of source code must retain the above copyright notice,

% this list of conditions and the following disclaimer.

%

% 2. Redistributions in binary form must reproduce the above copyright notice,

% this list of conditions and the following disclaimer in the documentation

% and/or other materials provided with the distribution.

%

% THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"

% AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE

% IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE

% ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE

% LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR

% CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF

% SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS

% INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN

% CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)

% ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF

% THE POSSIBILITY OF SUCH DAMAGE.

function STUDY = std_dipplot(STUDY, ALLEEG, varargin)

% Set default values

cls = []; % plot all clusters in STUDY

figureon = 1; % plot on a new figure

mode = 'apart';

STUDY = pop_dipparams(STUDY, 'default');

opt_dipplot = {'projlines',STUDY.etc.dipparams.projlines, 'axistight', STUDY.etc.dipparams.axistight, 'projimg', STUDY.etc.dipparams.projimg, 'dipolelength', 0, 'density', STUDY.etc.dipparams.density};

dipcolor = [];

dipsize = [];

%, 'spheres', 'on'

groupval = 'off';

nosphere = true;

for k = 3:2:nargin

switch varargin{k-2}

case 'clusters'

if isnumeric(varargin{k-1})

cls = varargin{k-1};

if isempty(cls)

cls = 2:length(STUDY.cluster);

end

else

if ischar(varargin{k-1}) && strcmpi(varargin{k-1}, 'all')

cls = 2:length(STUDY.cluster);

else

error('std_dipplot: ''clusters'' input takes either specific clusters (numeric vector) or keyword ''all''.');

end

end

if length(cls) == 1, mode = 'apart'; else mode = 'together'; end

case 'comps'

if strcmpi(STUDY.etc.dipparams.density, 'on')

disp('Single dipole should not be plotted using dipole density, reverting to dipole plotting');

opt_dipplot{end} = 'off';

end

STUDY = std_plotcompdip(STUDY, ALLEEG, cls, varargin{k-1}, opt_dipplot{:});

return;

case 'plotsubjects', % do nothing

case 'mode', mode = varargin{k-1};

case 'groups', groupval = varargin{k-1};

case 'figure'

if strcmpi(varargin{k-1},'off')

if strcmpi(STUDY.etc.dipparams.density, 'on')

disp('Cannot plot dipole density within figure, reverting to dipole plotting');

opt_dipplot{end} = 'off';

end

opt_dipplot{end + 1} = 'gui';

opt_dipplot{end + 1} = 'off';

figureon = 0;

end

case 'dipcolor'

dipcolor = varargin{k-1};

case 'dipsize'

dipsize = varargin{k-1};

case 'spheres'

opt_dipplot = { opt_dipplot{:}, 'spheres', varargin{k-1} };

nosphere = false;

end

end

if nosphere

opt_dipplot = { opt_dipplot{:}, 'spheres', 'on' };

end

if strcmpi(mode, 'together')

if strcmpi(STUDY.etc.dipparams.density, 'on')

disp('Cannot plot dipole density within figure, reverting to dipole plotting');

opt_dipplot{end} = 'off';

end

end

% select clusters to plot

% -----------------------

if isempty(cls)

tmp =[];

cls = 2:length(STUDY.cluster); % plot all clusters in STUDY

for k = 1: length(cls)

% don't include 'Notclust' clusters

if ~strncmpi('Notclust',STUDY.cluster(cls(k)).name,8) && ~strncmpi('ParentCluster',STUDY.cluster(cls(k)).name,13)

tmp = [tmp cls(k)];

end

end

cls = tmp;

end

if strcmpi(mode, 'apart') % case each cluster on a separate figure

for clus = 1: length(cls) % For each cluster requested

if length(STUDY.cluster(cls(clus)).comps) > 0 % check there are comps in cluster

max_r = 0;

clear cluster_dip_models;

len = length(STUDY.cluster(cls(clus)).comps);

ndip = 0;

dip_ind = [];

if ~isfield(STUDY.cluster(cls(clus)),'dipole')

STUDY = std_centroid(STUDY,ALLEEG, cls(clus) , 'dipole');

elseif isempty(STUDY.cluster(cls(clus)).dipole)

STUDY = std_centroid(STUDY,ALLEEG, cls(clus) , 'dipole');

end

for k = 1:len

abset = STUDY.datasetinfo(STUDY.cluster(cls(clus)).sets(1,k)).index;

subject = STUDY.datasetinfo(STUDY.cluster(cls(clus)).sets(1,k)).subject;

if ~isfield(ALLEEG(abset), 'dipfit')

warndlg2(['No dipole information available in dataset ' ALLEEG(abset).filename ' , abort plotting'], 'Aborting plot dipoles');

return;

end

comp = STUDY.cluster(cls(clus)).comps(k);

cluster_dip_models(k).posxyz = ALLEEG(abset).dipfit.model(comp).posxyz;

cluster_dip_models(k).momxyz = ALLEEG(abset).dipfit.model(comp).momxyz;

cluster_dip_models(k).rv = ALLEEG(abset).dipfit.model(comp).rv;

if strcmpi(ALLEEG(abset).dipfit.coordformat, 'spherical')

if isfield(ALLEEG(abset).dipfit, 'hdmfile') %dipfit 2 spherical model

load('-mat', ALLEEG(abset).dipfit.hdmfile);

max_r = max(max_r, max(vol.r));

else % old version of dipfit

max_r = max(max_r,max(ALLEEG(abset).dipfit.vol.r));

end

end

comp_to_disp{k} = [subject ', ' 'IC' num2str(comp) ];

if ~isempty(cluster_dip_models(k).posxyz)

ndip = ndip +1;

dip_ind = [dip_ind k];

end

end % finished going over cluster comps

STUDY.cluster(cls(clus)).dipole = computecentroid(cluster_dip_models);

cluster_dip_models(end + 1) = STUDY.cluster(cls(clus)).dipole;

% additional options

% ------------------

dip_color = cell(1,ndip+1);

dip_color(1:ndip) = {'b'};

dip_color(end) = {'r'};

options = opt_dipplot;

options{end+1} = 'mri';

options{end+1} = ALLEEG(abset).dipfit.mrifile;

options{end+1} = 'coordformat';

options{end+1} = ALLEEG(abset).dipfit.coordformat;

options{end+1} = 'dipnames';

options{end+1} = {comp_to_disp{dip_ind } [STUDY.cluster(cls(clus)).name ' mean']};

options{end+1} = 'color';

options{end+1} = dip_color;

% if 'groups'==1, overwrite cluster_dip_models, dip_color and dipnames in option -makoto

if strcmpi(groupval, 'on')

[cluster_dip_models, options] = dipgroups(ALLEEG, STUDY, cls, comp_to_disp, cluster_dip_models, options);

break

end

if strcmpi(ALLEEG(abset).dipfit.coordformat, 'spherical')

options{end+1} = 'sphere';

options{end+1} = max_r;

else

options{end+1} = 'meshdata';

options{end+1} = ALLEEG(abset).dipfit.hdmfile;

end

%enable both lines and images to be projected; increase #dipole limits

if ndip < 20 && strcmpi(options{1}, 'projlines') && length(cls) == 1

options{2} = 'on';

end

if ndip < 20 && strcmpi(options{5}, 'projimg') && length(cls) == 1

options{6} = 'on';

end

% Dealing with projection lines

if strcmpi(options{2},'on')

projlinesvect = ones(1,length(cluster_dip_models));

elseif strcmpi(options{2},'off') && strcmp(STUDY.etc.dipparams.centrline,'on')

projlinesvect = zeros(1,length(cluster_dip_models));

projlinesvect(end) = 1;

elseif strcmpi(options{2},'off')

projlinesvect = zeros(1,length(cluster_dip_models));

end

options{2} = projlinesvect;

if figureon

dipplot(cluster_dip_models, options{:});

fig_h = gcf;

set(fig_h,'Name', [STUDY.cluster(cls(clus)).name ' - ' num2str(length(unique(STUDY.cluster(cls(clus)).sets(1,:)))) ...

' sets - ' num2str(length(STUDY.cluster(cls(clus)).comps)) ' components (' num2str(ndip) ' dipoles)' ],'NumberTitle','off');

else

dipplot(cluster_dip_models, options{:},'view', [0.5 -0.5 0.5]);

for gind = 1:length(options) % remove the 'gui' 'off' option

if ischar(options{gind})

if strfind(options{gind}, 'gui')

break;

end

end

end

options(gind:gind+1) = [];

dipinfo.dipmod = cluster_dip_models;

dipinfo.op = options;

diptitle = [STUDY.cluster(cls(clus)).name ', ' num2str(length(unique(STUDY.cluster(cls(clus)).sets(1,:)))) ' sets -' ...

num2str(length(STUDY.cluster(cls(clus)).comps)) ' components (' num2str(ndip) ' dipoles)' ];

dipinfo.title = diptitle;

set(gcf, 'UserData', dipinfo);

set(gca,'UserData', dipinfo);

rotate3d off;

axcopy(gca, ['dipinfo = get(gca, ''''UserData''''); dipplot(dipinfo.dipmod, dipinfo.op{:}); set(gcf, ''''Name'''', dipinfo.title,''''NumberTitle'''',''''off''''); ']);

end

end % finished the if condition that cluster isn't empty

end % finished going over requested clusters

end

if strcmpi(mode, 'together') % case all clusters are plotted in the same figure (must be a new figure)

N = length(cls);

rowcols(2) = ceil(sqrt(N)); % Number of rows in the subplot figure.

rowcols(1) = ceil(N/rowcols(2));

fig_h = figure;

orient tall

set(fig_h,'Color', 'black');

set(fig_h,'Name', 'All clusters dipoles','NumberTitle','off');

set(fig_h, 'resize','off');

for l = 1:N

len = length(STUDY.cluster(cls(l)).comps);

max_r = 0;

clear cluster_dip_models;

if ~isfield(STUDY.cluster(cls(l)),'dipole')

STUDY = std_centroid(STUDY,ALLEEG, cls(l), 'dipole');

elseif isempty(STUDY.cluster(cls(l)).dipole)

STUDY = std_centroid(STUDY,ALLEEG, cls(l), 'dipole');

end

for k = 1: len

abset = STUDY.datasetinfo(STUDY.cluster(cls(l)).sets(1,k)).index;

if ~isfield(ALLEEG(abset), 'dipfit')

warndlg2(['No dipole information available in dataset ' num2str(abset) ' , abort plotting'], 'Aborting plot dipoles');

return;

end

comp = STUDY.cluster(cls(l)).comps(k);

cluster_dip_models(k).posxyz = ALLEEG(abset).dipfit.model(comp).posxyz;

cluster_dip_models(k).momxyz = ALLEEG(abset).dipfit.model(comp).momxyz;

cluster_dip_models(k).rv = ALLEEG(abset).dipfit.model(comp).rv;

if strcmpi(ALLEEG(abset).dipfit.coordformat, 'spherical')

if isfield(ALLEEG(abset).dipfit, 'hdmfile') %dipfit 2 spherical model

load('-mat', ALLEEG(abset).dipfit.hdmfile);

max_r = max(max_r, max(vol.r));

else % old version of dipfit

max_r = max(max_r,max(ALLEEG(abset).dipfit.vol.r));

end

end

end % finished going over cluster comps

STUDY.cluster(cls(l)).dipole = computecentroid(cluster_dip_models);

cluster_dip_models(end + 1) = STUDY.cluster(cls(l)).dipole;

dip_color = cell(1,length(cluster_dip_models));

dip_color(1:end-1) = {'b'};

dip_color(end) = {'r'};

options = opt_dipplot;

options{end + 1} = 'gui';

options{end + 1} = 'off';

options{end+1} = 'mri';

options{end+1} = ALLEEG(abset).dipfit.mrifile;

options{end+1} = 'coordformat';

options{end+1} = ALLEEG(abset).dipfit.coordformat;

options{end+1} = 'color';

options{end+1} = dip_color;

if strcmpi(ALLEEG(abset).dipfit.coordformat, 'spherical')

options{end+1} = 'sphere';

options{end+1} = max_r;

else

options{end+1} = 'meshdata';

options{end+1} = ALLEEG(abset).dipfit.hdmfile;

end

% Dealing with projection lines

if strcmpi(options{2},'on')

projlinesvect = ones(1,length(cluster_dip_models));

elseif strcmpi(options{2},'off') && strcmp(STUDY.etc.dipparams.centrline,'on')

projlinesvect = zeros(1,length(cluster_dip_models));

projlinesvect(end) = 1;

elseif strcmpi(options{2},'off')

projlinesvect = zeros(1,length(cluster_dip_models));

end

options{2} = projlinesvect;

hsbplot = subplot(rowcols(1),rowcols(2),l);

% Creating new axis for title only

set(hsbplot,'visible','off');

htitle = title([ STUDY.cluster(cls(l)).name ' (' num2str(length(unique(STUDY.cluster(cls(l)).sets(1,:)))) ' Ss, ' num2str(length(STUDY.cluster(cls(l)).comps)),' ICs)'],'color','white','Visible', 'on');

if rowcols(1)> 1, set(htitle,'Position', get(htitle,'Position')+ [0 0.05 0].*get(htitle,'Position') ); end

axes('Position', get(hsbplot,'Position'),'Color', 'black');

dipplot(cluster_dip_models, options{:});

%diptitle = [STUDY.cluster(cls(l)).name ', ' num2str(length(unique(STUDY.cluster(cls(l)).sets(1,:)))) 'Ss'];

%title(diptitle, 'Color', 'white');

% Complex axcopy

%if l == 1

% for gind = 1:length(options) % remove the 'gui' 'off' option

% if ischar(options{gind})

% if strfind(options{gind}, 'gui')

% break;

% end

% end

% end

% options(gind:gind+1) = [];

%end

%dipinfo.dipmod = cluster_dip_models;

%dipinfo.op = options;

%dipinfo.title = diptitle;

%set(gcf, 'UserData', dipinfo);

%set(gca,'UserData', dipinfo);

%axcopy(gcf, ['dipinfo = get(gca, ''''UserData''''); dipplot(dipinfo.dipmod, dipinfo.op{:}); set(gcf, ''''Name'''', dipinfo.title,''''NumberTitle'''',''''off'''');']);

end %finished going over all clusters

set(fig_h, 'resize','on');

end % finished case of 'all' clusters

% ========================================================================================

% multicolor mode

% all clusters are plotted in the same axis, with each cluster indicated by color/size

% also enable 'data cursor' so that in data tip mode, clicking on a dipole

% will display its name

if strcmpi(mode, 'multicolor')

N = length(cls);

%%%%%%%%%%%%%%%%%%%%% color list %%%%%%%%%%%%%%%%%%%%%

% This color list was developed for std_envtopo

% modified from dipgroups below

colors{1} = [1 1 1]; % White

colors{2} = [1 1 0]; % Yellow

colors{3} = [1 0 1]; % Fuchsia

colors{4} = [1 0 0]; % Red

colors{5} = [0.875 0.875 0.875]; % Silver

colors{6} = [0.5 0.5 0.5]; % Gray

colors{7} = [0.5 0.5 0]; % Olive

colors{8} = [0.5 0 0.5]; % Purple

colors{9} = [0.5 0 0]; % Maroon

colors{10} = [0 1 1]; % Aqua

colors{11} = [0 1 0]; % Lime

colors{12} = [0 0.5 0.5]; % Teal

colors{13} = [0 0.5 0]; % Green

colors{14} = [0 0 1]; % Blue

colors{15} = [0 0 0.5]; % Navy

colors{16} = [0 0 0]; % Black

% Choosing and sorting 13 colors for clusters: Red, Green, Blue,

% Fuchsia, Lime, Aqua, Maroon, Olive, Purple, Teal, Navy, Gray, and White

colors = colors([4 13 14 3 11 10 9 7 8 12 15 6 1 ]);

fig_h = figure;

orient tall

set(fig_h,'Color', 'black');

set(fig_h,'Name', 'All clusters dipoles','NumberTitle','off');

set(fig_h, 'resize','off');

idx = 0; %cumulative dipole index

centroidIdx = [];

clear cluster_dip_models;

for l = 1:N %loop over clusters

len = length(STUDY.cluster(cls(l)).comps);

max_r = 0;

%color, size for every cluster can be passed as arguments, or

%automatically iterate through a set of colors/sizes

if ~isempty(dipcolor)

clusterColors{l} = dipcolor{idx};

else

colorIndex = mod(l-1, length(colors))+1;

clusterColors{l} = colors{colorIndex};

end

if ~isempty(dipsize)

clusterSizes(l) = dipsize(idx);

else

%after rotating through color list once, change size of dipole

if l <= length(colors)

clusterSizes(l) = 30;

elseif l <= 2*length(colors)

clusterSizes(l) = 20;

else

clusterSizes(l) = 15;

end

end

if ~isfield(STUDY.cluster(cls(l)),'dipole')

STUDY = std_centroid(STUDY,ALLEEG, cls(l), 'dipole');

elseif isempty(STUDY.cluster(cls(l)).dipole)

STUDY = std_centroid(STUDY,ALLEEG, cls(l), 'dipole');

end

clustStartIdx = idx + 1;

for k = 1:len %loop over components within a cluster

idx = idx + 1;

abset = STUDY.datasetinfo(STUDY.cluster(cls(l)).sets(1,k)).index;

subjname = STUDY.datasetinfo(STUDY.cluster(cls(l)).sets(1,k)).subject;

if ~isfield(ALLEEG(abset), 'dipfit')

warndlg2(['No dipole information available in dataset ' num2str(abset) ' , abort plotting'], 'Aborting plot dipoles');

return;

end

comp = STUDY.cluster(cls(l)).comps(k);

cluster_dip_models(idx).posxyz = ALLEEG(abset).dipfit.model(comp).posxyz;

cluster_dip_models(idx).momxyz = ALLEEG(abset).dipfit.model(comp).momxyz;

cluster_dip_models(idx).rv = ALLEEG(abset).dipfit.model(comp).rv;

if strcmpi(ALLEEG(abset).dipfit.coordformat, 'spherical')

if isfield(ALLEEG(abset).dipfit, 'hdmfile') %dipfit 2 spherical model

load('-mat', ALLEEG(abset).dipfit.hdmfile);

max_r = max(max_r, max(vol.r));

else % old version of dipfit

max_r = max(max_r,max(ALLEEG(abset).dipfit.vol.r));

end

end

dip_color{idx} = clusterColors{l};

dip_size(idx) = clusterSizes(l);

dip_label{idx} = sprintf('Cls %d (%s IC%d)',cls(l), subjname, comp);

end % finished going over cluster comps

%add the cluster centroid

clustEndIdx = idx;

STUDY.cluster(cls(l)).dipole = computecentroid(cluster_dip_models(clustStartIdx:clustEndIdx));

idx = idx + 1;

centroidIdx(end+1) = idx;

cluster_dip_models(idx) = STUDY.cluster(cls(l)).dipole;

dip_color(idx) = {'k'};

dip_size(idx) = 10;

dip_label{idx} = sprintf('Cls %d centroid',cls(l));

clusterLabels{l} = sprintf('Cls %d',cls(l));

end %loop over clusters

options = opt_dipplot;

options{end + 1} = 'gui';

options{end + 1} = 'off';

options{end+1} = 'mri';

options{end+1} = ALLEEG(abset).dipfit.mrifile;

options{end+1} = 'coordformat';

options{end+1} = ALLEEG(abset).dipfit.coordformat;

options{end+1} = 'color';

options{end+1} = dip_color;

options{end+1} = 'dipolesize';

options{end+1} = dip_size;

options{end+1} = 'dipnames';

options{end+1} = dip_label;

if strcmpi(ALLEEG(abset).dipfit.coordformat, 'spherical')

options{end+1} = 'sphere';

options{end+1} = max_r;

else

options{end+1} = 'meshdata';

options{end+1} = ALLEEG(abset).dipfit.hdmfile;

end

% Dealing with projection lines

if strcmpi(options{2},'on')

projlinesvect = ones(1,length(cluster_dip_models));

elseif strcmpi(options{2},'off') && strcmp(STUDY.etc.dipparams.centrline,'on')

projlinesvect = zeros(1,length(cluster_dip_models));

projlinesvect(centroidIdx) = 1;

elseif strcmpi(options{2},'off')

projlinesvect = zeros(1,length(cluster_dip_models));

end

options{2} = projlinesvect;

dipplot(cluster_dip_models, options{:});

set(fig_h, 'resize','on');

%data cursor will show component label

datacursormode on

dcm = datacursormode(gcf);

set(dcm,'Enable','on', 'UpdateFcn', @componentText)

end % multicolor. Supporting functions at end of file

% ========================================================================================

% STD_PLOTCOMPDIP - Commandline function, to visualizing cluster components dipoles.

% Displays the dipoles of specified cluster components with the cluster mean

% dipole on separate figures.

% To visualize dipoles they first must be stored in the EEG dataset structures

% using DIPFIT. Only components that have a dipole locations will be displayed,

% along with the cluster mean dipole in red.

% Usage:

% >> [STUDY] = std_plotcompdip(STUDY, ALLEEG, cluster, comps);

% Inputs:

% STUDY - EEGLAB STUDY set comprising some or all of the EEG datasets in ALLEEG.

% ALLEEG - global EEGLAB vector of EEG structures for the dataset(s) included in the STUDY.

% ALLEEG for a STUDY set is typically created using LOAD_ALLEEG.

% cluster - single cluster number.

%

% Optional inputs:

% comps - [numeric vector] -> indices of the cluster components to plot.

% 'all' -> plot all the components in the cluster {default: 'all'}.

%

% Outputs:

% STUDY - the input STUDY set structure modified with plotted cluster

% dipole mean, to allow quick replotting (unless cluster mean

% already existed in the STUDY).

%

% Example:

% >> cluster = 4; comps= 1;

% >> [STUDY] = std_plotcompdip(STUDY,ALLEEG, cluster, comps);

% Plots component 1 dipole in blue with the cluster 4 mean dipole in red.

%

% See also pop_clustedit, dipfit, std_dipplot

%

% Authors: Hilit Serby, Arnaud Delorme, Scott Makeig, SCCN, INC, UCSD, June, 2005

% Copyright (C) Hilit Serby, SCCN, INC, UCSD, June 08, 2005, hilit@sccn.ucsd.edu

%

% This file is part of EEGLAB, see http://www.eeglab.org

% for the documentation and details.

%

% Redistribution and use in source and binary forms, with or without

% modification, are permitted provided that the following conditions are met:

%

% 1. Redistributions of source code must retain the above copyright notice,

% this list of conditions and the following disclaimer.

%

% 2. Redistributions in binary form must reproduce the above copyright notice,

% this list of conditions and the following disclaimer in the documentation

% and/or other materials provided with the distribution.

%

% THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"

% AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE

% IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE

% ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE

% LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR

% CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF

% SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS

% INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN

% CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)

% ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF

% THE POSSIBILITY OF SUCH DAMAGE.

function STUDY = std_plotcompdip(STUDY, ALLEEG, cls, comp_ind, varargin)

if ~exist('cls')

error('std_plotcompdip: you must provide a cluster number as an input.');

end

if isempty(cls)

error('std_plotcompdip: you must provide a cluster number as an input.');

end

if nargin == 3 % no components indices were given

% Default plot all components of the cluster

[STUDY] = std_dipplot(STUDY, ALLEEG, 'clusters', cls);

return

end

for ci = 1:length(comp_ind)

abset = STUDY.datasetinfo(STUDY.cluster(cls).sets(1,comp_ind(ci))).index;

comp = STUDY.cluster(cls).comps(comp_ind(ci));

subject = STUDY.datasetinfo(STUDY.cluster(cls).sets(1,comp_ind(ci))).subject;

if ~isfield(ALLEEG(abset), 'dipfit')

warndlg2(['No dipole information available in dataset ' num2str(abset) ' , abort plotting'], 'Aborting plot dipoles');

return;

end

if length(comp_ind) == 1 && isempty(ALLEEG(abset).dipfit.model(comp).posxyz)

warndlg2(strvcat('There is no dipole information available in', ...

[ 'dataset ' num2str(abset) ' for this component, abort plotting']), 'Aborting plot dipoles');

return;

end

if ~isfield(STUDY.cluster(cls),'dipole')

STUDY = std_centroid(STUDY,ALLEEG, cls , 'dipole');

elseif isempty(STUDY.cluster(cls).dipole)

STUDY = std_centroid(STUDY,ALLEEG, cls , 'dipole');

end

comp_to_disp = [subject ' / ' 'IC' num2str(comp) ];

cluster_dip_models.posxyz = ALLEEG(abset).dipfit.model(comp).posxyz;

cluster_dip_models.momxyz = ALLEEG(abset).dipfit.model(comp).momxyz;

cluster_dip_models.rv = ALLEEG(abset).dipfit.model(comp).rv;

cluster_dip_models(2) = STUDY.cluster(cls).dipole;

if strcmpi(ALLEEG(abset).dipfit.coordformat, 'spherical')

if isfield(ALLEEG(abset).dipfit, 'hdmfile') %dipfit 2 spherical model

load('-mat', ALLEEG(abset).dipfit.hdmfile);

max_r = max(vol.r);

else

max_r = max(ALLEEG(abset).dipfit.vol.r);

end

dipplot(cluster_dip_models, 'sphere', max_r, 'mri', ALLEEG(abset).dipfit.mrifile,'coordformat', ALLEEG(abset).dipfit.coordformat , ...

'normlen' ,'on', 'pointout' ,'on','color', {'b', 'r'}, 'dipnames', {comp_to_disp [ STUDY.cluster(cls).name ' mean' ] },...

'spheres', 'on', 'verbose', 'off', varargin{:});

else

dipplot(cluster_dip_models, 'meshdata', ALLEEG(abset).dipfit.hdmfile, 'mri', ALLEEG(abset).dipfit.mrifile,'coordformat', ALLEEG(abset).dipfit.coordformat , ...

'normlen' ,'on', 'pointout' ,'on','color', {'b', 'r'}, 'dipnames', {comp_to_disp [STUDY.cluster(cls).name ' mean']}, ...

'spheres', 'off', 'verbose', 'off', varargin{:});

end

fig_h = gcf;

set(fig_h,'Name', [subject ' / ' 'IC' num2str(comp) ', ' STUDY.cluster(cls).name],'NumberTitle','off');

end

% -----------------------

% load all dipoles and

% compute dipole centroid

% DEVELOPMENT: this function

% should be the only one to

% access dipole information

% -----------------------

function STUDY = std_centroid(STUDY,ALLEEG, clsind, tmp);

for clust = 1:length(clsind)

max_r = 0;

len = length(STUDY.cluster(clsind(clust)).comps);

tmppos = [ 0 0 0 ];

tmpmom = [ 0 0 0 ];

tmprv = 0;

ndip = 0;

for k = 1:len

fprintf('.');

comp = STUDY.cluster(clsind(clust)).comps(k);

abset = STUDY.cluster(clsind(clust)).sets(1,k);

if ~isfield(ALLEEG(abset), 'dipfit')

warndlg2(['No dipole information available in dataset ' num2str(abset) ], 'Aborting compute centroid dipole');

return;

end

if ~isempty(ALLEEG(abset).dipfit.model(comp).posxyz)

ndip = ndip +1;

posxyz = ALLEEG(abset).dipfit.model(comp).posxyz;

momxyz = ALLEEG(abset).dipfit.model(comp).momxyz;

if size(posxyz,1) == 2

if all(posxyz(2,:) == [ 0 0 0 ])

posxyz(2,:) = [];

momxyz(2,:) = [];

end

end

tmppos = tmppos + mean(posxyz,1);

tmpmom = tmpmom + mean(momxyz,1);

tmprv = tmprv + ALLEEG(abset).dipfit.model(comp).rv;

if strcmpi(ALLEEG(abset).dipfit.coordformat, 'spherical')

if isfield(ALLEEG(abset).dipfit, 'hdmfile') %dipfit 2 spherical model

load('-mat', ALLEEG(abset).dipfit.hdmfile);

max_r = max(max_r, max(vol.r));

else % old version of dipfit

max_r = max(max_r,max(ALLEEG(abset).dipfit.vol.r));

end

end

end

end

centroid{clust}.dipole.posxyz = tmppos/ndip;

centroid{clust}.dipole.momxyz = tmpmom/ndip;

centroid{clust}.dipole.rv = tmprv/ndip;

if strcmpi(ALLEEG(abset).dipfit.coordformat, 'spherical') && (~isfield(ALLEEG(abset).dipfit, 'hdmfile')) %old dipfit

centroid{clust}.dipole.maxr = max_r;

end

STUDY.cluster(clsind(clust)).dipole = centroid{clust}.dipole;

end

fprintf('\n');

% --------------------------------

% new function to compute centroid

% was programmed to debug the function

% above but is now used in the code

% --------------------------------

function dipole = computecentroid(alldipoles)

max_r = 0;

len = length(alldipoles);

dipole.posxyz = [ 0 0 0 ];

dipole.momxyz = [ 0 0 0 ];

dipole.rv = 0;

ndip = 0;

count = 0;

warningon = 1;

for k = 1:len

if size(alldipoles(k).posxyz,1) == 2

if all(alldipoles(k).posxyz(2,:) == [ 0 0 0 ])

alldipoles(k).posxyz(2,:) = [];

alldipoles(k).momxyz(2,:) = [];

end

end

if ~isempty(alldipoles(k).posxyz)

dipole.posxyz = dipole.posxyz + mean(alldipoles(k).posxyz,1);

dipole.momxyz = dipole.momxyz + mean(alldipoles(k).momxyz,1);

dipole.rv = dipole.rv + alldipoles(k).rv;

count = count+1;

elseif warningon

disp('Some components do not have dipole information');

warningon = 0;

end

end

dipole.posxyz = dipole.posxyz/count;

dipole.momxyz = dipole.momxyz/count;

dipole.rv = dipole.rv/count;

if isfield(alldipoles, 'maxr')

dipole.maxr = alldipoles(1).max_r;

end

function [cluster_dip_models, options] = dipgroups(ALLEEG, STUDY, cls, comp_to_disp, cluster_dip_models, options);

% first, extract the subject number

for n = 1:length(comp_to_disp)

subjectnum(n,1) = str2num(comp_to_disp{n}(1:3));

end

% second, extract group info

for n = 1:length(subjectnum)

subj_group{n,1} = ALLEEG(1,subjectnum(n)).group;

end

% third, replace the group names with numbers

for n = 1:length(subj_group)

for m = 1:length(STUDY.group)

if strcmp(subj_group{n,1}, STUDY.group{1,m})

subj_groupnum(n,1) = m;

break

end

end

end

% fourth, compute centroid for each group

for n = 1:length(STUDY.group)

samegroupIC = find(subj_groupnum==n);

cluster_dip_models(1,length(subj_groupnum)+n) = computecentroid(cluster_dip_models(1, samegroupIC));

end

% fifth, use subj_groupnum as a type of dipole color

%%%%%%%%%%%%%%%%%%%%% color list %%%%%%%%%%%%%%%%%%%%%

% This color list was developed for std_envtopo

% 16 colors names officially supported by W3C specification for HTML

colors{1,1} = [1 1 1]; % White

colors{2,1} = [1 1 0]; % Yellow

colors{3,1} = [1 0 1]; % Fuchsia

colors{4,1} = [1 0 0]; % Red

colors{5,1} = [0.75 0.75 0.75]; % Silver

colors{6,1} = [0.5 0.5 0.5]; % Gray

colors{7,1} = [0.5 0.5 0]; % Olive

colors{8,1} = [0.5 0 0.5]; % Purple

colors{9,1} = [0.5 0 0]; % Maroon

colors{10,1} = [0 1 1]; % Aqua

colors{11,1} = [0 1 0]; % Lime

colors{12,1} = [0 0.5 0.5]; % Teal

colors{13,1} = [0 0.5 0]; % Green

colors{14,1} = [0 0 1]; % Blue

colors{15,1} = [0 0 0.5]; % Navy

colors{16,1} = [0 0 0]; % Black

% Silver is twice brighter because silver is used for a background color

colors{5,1} = [0.875 0.875 0.875];

% Choosing and sorting 12 colors for line plot, namely Red, Blue, Green, Fuchsia, Lime, Aqua, Maroon, Olive, Purple, Teal, Navy, and Gray

selectedcolors = colors([4 13 14 3 11 10 9 7 8 12 15 6]);

% determine the new dip colors

for n = 1:length(subj_groupnum)

dip_color{1,n}=selectedcolors{subj_groupnum(n,1)+1};

end

for n = 1:length(STUDY.group)

dip_color{1,end+1}= selectedcolors{n+1};

end

for n = 1:length(options)

if strcmp(options{1,n}, 'color')

options{1,n+1} = dip_color;

elseif strcmp(options{1,n}, 'dipnames')

dipnames = options{1,n+1};

for m = 1:length(STUDY.group)

dipnames{1,length(subj_groupnum)+m}= [STUDY.group{1,m} ' mean'];

end

options{1,n+1} = dipnames;

end

end

% ========================================================================================

% multicolor mode support functions

function str = componentText(~,obj)

% look up component name--used in data cursor callback in 'multicolor' mode

try

str = obj.Target.UserData.name;

h=findall(gcf,'type','hggroup');

h(1).FontSize = 14;

catch

str = '';

end