sig_topo_coefs

 sig_topo_coefs() - Plots scalp topographies of regression analysis results.  
                    Only works for analyses applied to voltages averaged across 
                    time windows.  Topographies can be visualized as mean 
                    regression coefficients, t-scores, or Cohen's d.
             
 Usage:
  >> sig_topo_coefs(regress_results_or_fname,varargin)

 Required Inputs:
  regress_results_or_fname - A MATLABmk "regress_results" structure variable or the 
                             filename of a MATLABmk regress_results structure that has
                             been saved to disk. If you specifiy a filename be
                             sure to include the file's path, unless the file is
                             in the current working directory.  regress_results
                             variables are produced by the functions
                             rm_regress.m and items_regress.m.

 Optional Inputs:
  fig_id           - [integer] The index # of the MATLAB figure in which
                     the diagram will be produced.  Useful for overwriting
                     old figures. {default: lowest unused index}
  statistic        - ['coefs','t', or 'd'] If 'coefs' estimated regression 
                     coefficients will be visualized (i.e., averaged across
                     participants for by-subjects analysis).  If 't', 
                     coefficient t-scores will be shown.  If 'd', Cohen's 
                     d of coefficients will be shown. {default: 'coefs'}
  predictors       - [cell array of strings] The names of all the
                     non-intercept predictors in the regression analysis 
                     that will be used to label each topography. If not 
                     specified, the predictor names stored in regress_results 
                     variable will be used.  This option exists in case the
                     predictor names in regress_results variable aren't that
                     readable (e.g., they consist of abbreviations).
  title_on         - [0 or 1] If 1, the bin # and bin descriptor will be
                     printed at the top of the figure. {default: 1}
  one_scale        - [0 or 1] If 1, all topographies will be plot using
                     the same color scale (useful for comparing effect 
                     sizes across topographies).  If 0, each topography
                     will be plot using a color scale tailored to it
                     (provides maximal resolution of topography
                     distribution).  {default: 1 if plotting in coefs, 0 if 
                     plotting t-scores or Cohen's d}
  color_min_max    - [min max] The minimum an maximum value of the 
                     topography color scale (e.g., [-4 4]). This is useful
                     for making the color scale the same across multiple
                     figures. Note, this option has no effect if one_scale
                     optional input is set to 0. If not used, color limits
                     are set to +/- absolute maximum of the data. 
                     {default: not used}
  verblevel        - An integer specifiying the amount of information you want
                     this function to provide about what it is doing during runtime.
                     Options are:
                      0 - quiet, only show errors, warnings, and EEGLAB reports
                      1 - stuff anyone should probably know
                      2 - stuff you should know the first time you start working
                          with a data set {default value}
                      3 - stuff that might help you debug (show all
                          reports)

 Global Variable:
   VERBLEVEL = matlabMK level of verbosity (i.e., tells functions
               how much to report about what they're doing during
               runtime) set by the optional function argument 'verblevel'

 Notes:
 -The printed/exported figure will have the same dimensions as the figure
 on the display.  Thus you can undo figure clutter by re-sizing it.

 Author:
 David Groppe
 Kutaslab, 7/2010

0001 % sig_topo_coefs() - Plots scalp topographies of regression analysis results.
0002 %                    Only works for analyses applied to voltages averaged across
0003 %                    time windows.  Topographies can be visualized as mean
0004 %                    regression coefficients, t-scores, or Cohen's d.
0005 %
0006 % Usage:
0007 %  >> sig_topo_coefs(regress_results_or_fname,varargin)
0008 %
0009 % Required Inputs:
0010 %  regress_results_or_fname - A MATLABmk "regress_results" structure variable or the
0011 %                             filename of a MATLABmk regress_results structure that has
0012 %                             been saved to disk. If you specifiy a filename be
0013 %                             sure to include the file's path, unless the file is
0014 %                             in the current working directory.  regress_results
0015 %                             variables are produced by the functions
0016 %                             rm_regress.m and items_regress.m.
0017 %
0018 % Optional Inputs:
0019 %  fig_id           - [integer] The index # of the MATLAB figure in which
0020 %                     the diagram will be produced.  Useful for overwriting
0021 %                     old figures. {default: lowest unused index}
0022 %  statistic        - ['coefs','t', or 'd'] If 'coefs' estimated regression
0023 %                     coefficients will be visualized (i.e., averaged across
0024 %                     participants for by-subjects analysis).  If 't',
0025 %                     coefficient t-scores will be shown.  If 'd', Cohen's
0026 %                     d of coefficients will be shown. {default: 'coefs'}
0027 %  predictors       - [cell array of strings] The names of all the
0028 %                     non-intercept predictors in the regression analysis
0029 %                     that will be used to label each topography. If not
0030 %                     specified, the predictor names stored in regress_results
0031 %                     variable will be used.  This option exists in case the
0032 %                     predictor names in regress_results variable aren't that
0033 %                     readable (e.g., they consist of abbreviations).
0034 %  title_on         - [0 or 1] If 1, the bin # and bin descriptor will be
0035 %                     printed at the top of the figure. {default: 1}
0036 %  one_scale        - [0 or 1] If 1, all topographies will be plot using
0037 %                     the same color scale (useful for comparing effect
0038 %                     sizes across topographies).  If 0, each topography
0039 %                     will be plot using a color scale tailored to it
0040 %                     (provides maximal resolution of topography
0041 %                     distribution).  {default: 1 if plotting in coefs, 0 if
0042 %                     plotting t-scores or Cohen's d}
0043 %  color_min_max    - [min max] The minimum an maximum value of the
0044 %                     topography color scale (e.g., [-4 4]). This is useful
0045 %                     for making the color scale the same across multiple
0046 %                     figures. Note, this option has no effect if one_scale
0047 %                     optional input is set to 0. If not used, color limits
0048 %                     are set to +/- absolute maximum of the data.
0049 %                     {default: not used}
0050 %  verblevel        - An integer specifiying the amount of information you want
0051 %                     this function to provide about what it is doing during runtime.
0052 %                     Options are:
0053 %                      0 - quiet, only show errors, warnings, and EEGLAB reports
0054 %                      1 - stuff anyone should probably know
0055 %                      2 - stuff you should know the first time you start working
0056 %                          with a data set {default value}
0057 %                      3 - stuff that might help you debug (show all
0058 %                          reports)
0059 %
0060 % Global Variable:
0061 %   VERBLEVEL = matlabMK level of verbosity (i.e., tells functions
0062 %               how much to report about what they're doing during
0063 %               runtime) set by the optional function argument 'verblevel'
0064 %
0065 % Notes:
0066 % -The printed/exported figure will have the same dimensions as the figure
0067 % on the display.  Thus you can undo figure clutter by re-sizing it.
0068 %
0069 % Author:
0070 % David Groppe
0071 % Kutaslab, 7/2010
0072 %
0073 
0074 
0075 %%%%%%%%%%%%%%%% REVISION LOG %%%%%%%%%%%%%%%%%
0076 % 5/6/2010-??
0077 
0078 %%%%%%%%%%%%%%%% FUTURE WORK %%%%%%%%%%%%%%%%%
0079 % -Make it possible plot confidence interval bounds
0080 % -Make it able to deal with regress_results.bins='All';
0081 
0082 function sig_topo_coefs(regress_results_or_fname,varargin)
0083 
0084 p=inputParser;
0085 p.addRequired('regress_results_or_fname',@(x) isstruct(x) || ischar(x));
0086 p.addParamValue('statistic','coefs',@ischar);
0087 p.addParamValue('predictors',[],@iscell);
0088 p.addParamValue('fig_id',[],@(x) isnumeric(x) && (length(x)==1));
0089 p.addParamValue('title_on',1,@(x) isnumeric(x) && (length(x)==1));
0090 p.addParamValue('one_scale',[],@(x) isnumeric(x) && (length(x)==1));
0091 p.addParamValue('color_min_max',[],@(x) isnumeric(x) && (length(x)==2));
0092 p.addParamValue('verblevel',[],@(x) isnumeric(x) && (length(x)==1));
0093 
0094 p.parse(regress_results_or_fname,varargin{:});
0095 
0096 % Manage VERBLEVEL
0097 if isempty(p.Results.verblevel),
0098     VERBLEVEL=2; %not global, just local
0099 else
0100     VERBLEVEL=p.Results.verblevel;
0101 end
0102 
0103 %Load regress_results variable
0104 if ischar(regress_results_or_fname),
0105     fprintf('Loading regress_results struct from file %s.\n',regress_results_or_fname);
0106     load(regress_results_or_fname,'-MAT');
0107     if ~exist('regress_results','var')
0108         error('File %s does not contain a "regress_results" variable.',regress_results_or_fname);
0109     end
0110 %    VerbReport(sprintf('Experiment: %s',GND.exp_desc),2,VERBLEVEL); ??    add?
0111 else
0112     regress_results=regress_results_or_fname;
0113     clear regress_results_or_fname;
0114 end
0115 
0116 if isfield(regress_results,'item_coefs'),
0117     %regress results variable is from items analysis, rename the regression
0118     %coeficient field to "mn_coefs" (the field used for by-subject
0119     %analysis) for convenience
0120     regress_results.mn_coefs=regress_results.item_coefs;
0121 end
0122    
0123 if isempty(p.Results.predictors)
0124    pred_names=regress_results.predictor_names;
0125 else
0126    pred_names=p.Results.predictors; 
0127 end
0128 
0129 [n_chan, n_topos]=size(regress_results.mn_coefs);
0130 if n_chan==1,
0131    error('Regression analysis was performed on only one EEG channel.  You can''t plot that topographically.'); 
0132 end
0133 wdth=floor(sqrt(n_topos));
0134 ht=ceil(n_topos/wdth);
0135 
0136 bin=regress_results.bins;
0137 if isempty(p.Results.fig_id)
0138     fig_h=figure;
0139 else
0140     fig_h=figure(p.Results.fig_id); clf;
0141 end
0142 if length(bin)==1,
0143     set(fig_h,'name',['Bin ' int2str(bin)],'paperpositionmode','auto');
0144 else
0145     set(fig_h,'name',['Bin(s) ' int2str(bin)],'paperpositionmode','auto');
0146 end
0147 %setting paperpositionmode to 'auto' means that if the figure is manually
0148 %resized, the printed version of the figure will reflect whatever the
0149 %shown size was (at the time of printing)
0150 
0151 if strcmpi(p.Results.statistic,'coefs'),
0152     units='Mean Coefficients';
0153     %Compute mean voltage in each time window
0154 
0155     if isempty(p.Results.one_scale) || (p.Results.one_scale<=0),
0156         one_scale=0;
0157         maplimits='absmax';
0158     else
0159         one_scale=1;
0160         mx=max(max(abs(regress_results.mn_coefs)));
0161         maplimits=[-1 1]*mx;
0162     end
0163 elseif strcmpi(p.Results.statistic,'t');
0164     units='t';
0165     if isempty(p.Results.one_scale) || (p.Results.one_scale>0),
0166         one_scale=1;
0167         mx=max(max(abs(regress_results.t_coefs)));
0168         maplimits=[-1 1]*mx;
0169     else
0170         one_scale=0;
0171         maplimits='absmax';
0172     end
0173 elseif strcmpi(p.Results.statistic,'d');
0174     units='Cohen''s d';
0175     if isempty(p.Results.one_scale) || (p.Results.one_scale>0),
0176         one_scale=1;
0177         mx=max(max(abs(regress_results.d_coefs)));
0178         maplimits=[-1 1]*mx;
0179     else
0180         one_scale=0;
0181         maplimits='absmax';
0182     end
0183 else,
0184    error('Argument ''statistic'' needs to be ''coefs'',''t'', or ''d''.'); 
0185 end
0186 %Now take into account color_min_max argument
0187 if ~isempty(p.Results.color_min_max)
0188     if ~one_scale
0189         error('To use the ''color_min_max'' input argument, the input argument one_scale needs to be set to 1.');
0190     end
0191     maplimits=p.Results.color_min_max;
0192 end
0193 
0194 % Add later? ??
0195 % if VERBLEVEL,
0196 %     if isnan(GND.t_tests(t_test_id).n_perm),
0197 %         fprintf('q level of critical t-scores: %f., FDR method: %s\n', ...
0198 %             GND.t_tests(t_test_id).desired_alphaORq,GND.t_tests(t_test_id).mult_comp_method);
0199 %     else
0200 %         fprintf('Estimated alpha level of critical t-scores: %f.\n', ...
0201 %             GND.t_tests(t_test_id).estimated_alpha);
0202 %     end
0203 % end
0204 
0205 %Set angle of colorbar label
0206 if strcmpi(p.Results.statistic,'t'),
0207     rotation=0;
0208 else
0209     rotation=270;
0210 end
0211 
0212 for a=1:n_topos,
0213     subplot(ht,wdth,a);
0214     time_wind=regress_results.time_wind;
0215     if strcmpi(p.Results.statistic,'coefs'),
0216         mn=regress_results.mn_coefs(:,a);
0217     elseif strcmpi(p.Results.statistic,'t'),
0218         mn=regress_results.t_coefs(:,a);
0219     else
0220         mn=regress_results.d_coefs(:,a);
0221     end
0222 
0223     if ~strcmpi(maplimits,'absmax')
0224         mx_maplimits=max(maplimits);
0225         mn_maplimits=min(maplimits);
0226         if max(mn)>mx_maplimits,
0227             watchit(sprintf('Specified topography color maximium, %g, is less than the maximum value that needs to be displayed, %g. Remedy the problem with color_min_max input argument.', ...
0228                 max(maplimits),max(mn)));
0229         end
0230         if min(mn)<mn_maplimits,
0231             watchit(sprintf('Specified topography color minimium, %g, is greater than the minimum value that needs to be displayed, %g. Remedy the problem with color_min_max input argument.', ...
0232                 min(maplimits),min(mn)));
0233         end
0234     end
0235     sig_chans=find(regress_results.h_coefs_cor(:,a));
0236     topoplotMK(mn,regress_results.chanlocs,'emarker2',{sig_chans,'o',[1 1 1],4}, ...
0237         'maplimits',maplimits);
0238     hh=title(pred_names{a});
0239     if ~one_scale,
0240         hcb=colorbar;
0241         hy=ylabel(hcb,units);
0242         if strcmpi(units,'t'),
0243             set(hy,'rotation',rotation,'verticalalignment','middle','position',[4.9+n_topos*.2 0.03 1.0001]);
0244         else
0245             set(hy,'rotation',rotation,'verticalalignment','middle');
0246         end
0247     end
0248 end
0249 
0250 if one_scale,
0251     hcb=cbar_nudge('vert',0,maplimits);
0252     hy=ylabel(hcb,units);
0253     set(hy,'rotation',rotation,'verticalalignment','middle');
0254 end
0255 
0256 % Plot title of entire figure
0257 if p.Results.title_on,
0258     if length(bin)==1,
0259         h=textsc(['Bin ' int2str(bin) ', ' int2str(regress_results.time_wind(1)) '-' int2str(regress_results.time_wind(2)) ' ms'],'title');
0260     else
0261         h=textsc(['Bins ' int2str(bin) ', ' int2str(regress_results.time_wind(1)) '-' int2str(regress_results.time_wind(2)) ' ms'],'title');
0262     end
0263     set(h,'fontsize',14,'fontweight','bold');
0264 end
0265 
0266 
0267 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0268 %% cbar_nudge (plots colorbar slightly to left of cbar.m
0269 % search for "DG change" to find the line I edited
0270 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0271 function [handle]=cbar_nudge(arg,colors,minmax, grad)
0272 
0273 if nargin < 2
0274   colors = 0;
0275 end
0276 posscale = 'off';
0277 if nargin < 1
0278   arg = 'vert';
0279   ax = [];
0280 else
0281   if isempty(arg)
0282     arg = 0;
0283   end
0284   if arg(1) == 0
0285     ax = [];
0286     arg = 'vert';
0287   elseif strcmpi(arg, 'pos')
0288     ax = [];
0289     arg = 'vert';
0290     posscale = 'on';
0291   else      
0292     if isstr(arg)
0293       ax = [];
0294     else
0295       ax = arg;
0296       arg = [];
0297     end
0298   end
0299 end
0300 
0301 if nargin>2
0302   if size(minmax,1) ~= 1 | size(minmax,2) ~= 2
0303     help cbar
0304     fprintf('cbar() : minmax arg must be [min,max]\n');
0305     return
0306   end
0307 end
0308 if nargin < 4
0309     grad = 5;
0310 end;
0311 
0312 
0313 %%%%%%%%%%%%%%%%%%%%%%%%%%%
0314 % Choose colorbar position
0315 %%%%%%%%%%%%%%%%%%%%%%%%%%%
0316 
0317 if (length(colors) == 1) & (colors == 0)
0318   t = caxis;
0319 else
0320   t = [0 1];
0321 end
0322 if ~isempty(arg)
0323   if strcmp(arg,'vert')  
0324     cax = gca;
0325     pos = get(cax,'Position');
0326     stripe = 0.04; 
0327     edge = 0.01;
0328     %space = .02;
0329     space = -.02; %DG change
0330 
0331     set(cax,'Position',[pos(1) pos(2) pos(3) pos(4)])
0332     rect = [pos(1)+pos(3)+space pos(2) stripe*pos(3) pos(4)];
0333     ax = axes('Position', rect);
0334   elseif strcmp(arg,'horiz')
0335     cax = gca;
0336     pos = get(cax,'Position');
0337     stripe = 0.075; 
0338     space = .1;  
0339     set(cax,'Position',...
0340         [pos(1) pos(2)+(stripe+space)*pos(4) pos(3) (1-stripe-space)*pos(4)])
0341     rect = [pos(1) pos(2) pos(3) stripe*pos(4)];
0342     ax = axes('Position', rect);
0343   end
0344 else
0345   pos = get(ax,'Position');
0346   if pos(3) > pos(4)
0347     arg = 'horiz';
0348   else
0349     arg = 'vert';
0350   end
0351 end
0352   
0353 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0354 % Draw colorbar using image()
0355 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0356 
0357 map = colormap;
0358 n = size(map,1);
0359 
0360 if length(colors) == 1
0361   if strcmp(arg,'vert')
0362       if strcmpi(posscale, 'on')
0363           image([0 1],[0 t(2)],[ceil(n/2):n-colors]');
0364       else
0365           image([0 1],t,[1:n-colors]');
0366       end;
0367       set(ax,'xticklabelmode','manual')
0368       set(ax,'xticklabel',[],'YAxisLocation','right')
0369       
0370   else
0371     image(t,[0 1],[1:n-colors]);
0372     set(ax,'yticklabelmode','manual')
0373     set(ax,'yticklabel',[],'YAxisLocation','right')
0374   end
0375   set(ax,'Ydir','normal','YAxisLocation','right')
0376 
0377 else % length > 1
0378 
0379   if max(colors) > n
0380     error('Color vector excedes size of colormap')
0381   end
0382   if strcmp(arg,'vert')
0383     image([0 1],t,[colors]');
0384     set(ax,'xticklabelmode','manual')
0385     set(ax,'xticklabel',[])
0386   else
0387     image([0 1],t,[colors]);
0388     set(ax,'yticklabelmode','manual')
0389     set(ax,'yticklabel',[],'YAxisLocation','right')
0390   end  
0391   set(ax,'Ydir','normal','YAxisLocation','right')
0392 end
0393 
0394 %%%%%%%%%%%%%%%%%%%%%%%%%
0395 % Adjust cbar ticklabels
0396 %%%%%%%%%%%%%%%%%%%%%%%%%
0397 
0398 if nargin > 2 
0399   if strcmp(arg,'vert')
0400       Cax = get(ax,'Ylim');
0401   else
0402       Cax = get(ax,'Xlim');
0403   end;
0404   CBTicks = [Cax(1):(Cax(2)-Cax(1))/(grad-1):Cax(2)]; % caxis tick positions
0405   CBLabels = [minmax(1):(minmax(2)-minmax(1))/(grad-1):minmax(2)]; % tick labels
0406   
0407   dec = floor(log10(max(abs(minmax)))); % decade of largest abs value
0408   CBLabels = ([minmax]* [ linspace(1,0, grad);linspace(0, 1, grad)]);
0409   %[1.0 .75 .50 .25 0.0; 0.0 .25 .50 .75 1.0]);
0410   if dec<1
0411     CBLabels = round(CBLabels*10^(1-dec))*10^(dec-1);
0412   elseif dec == 1
0413     CBLabels = round(CBLabels*10^(2-dec))*10^(dec-2);
0414   else
0415     CBLabels = round(CBLabels);
0416   end
0417 % minmax
0418 % CBTicks
0419 % CBLabels
0420 
0421   if strcmp(arg,'vert')
0422     set(ax,'Ytick',CBTicks);
0423     set(ax,'Yticklabel',CBLabels);
0424   else
0425     set(ax,'Xtick',CBTicks);
0426     set(ax,'Xticklabel',CBLabels);
0427   end
0428 end
0429 handle = ax;
0430 
0431 %%%%%%%%%%%%%%%%%%
0432 % Adjust cbar tag
0433 %%%%%%%%%%%%%%%%%%
0434 
0435 set(ax,'tag','cbar')