function [H, xx, xw]= plot_barWithAntenna(y, y_sem, varargin)
%PLOT_BARWITHANTENNA - Bar plot with antennas, e.g., to show the SEM.
%
%Synopsis:
% [H, X]= plot_barWithAntenna(Y, Y_SEM, <OPT>)
%
%Input:
% Y:     Heights of the bars, DOUBLE [MxN]
% Y_SEM: Length of the antenna, DOUBLE [MxN]
% OPT:   Structure or property/value list of optional properties:
%  .Clf          - Clear figure before plotting, BOOL (default 1)
%  .ColOrder     - Colormap of N colors, default blue to white, DOUBLE [Nx3]
%                  (generated by cmap_bluewhite(N, 'min_val',0.15)
%  .AntennaType  - Specifies how anntennas are drawn, options are 'o','oo',
%                  'T','I', CHAR (default 'o')
%  .AntennaColor - Color of antennas, with 'auto' meaning same colors as
%                  bars, DOUBLE [Nx3] or 'auto' (default)
%  .AntennaSpec  - Line specifications for antennas
%
%Output:
% H: handles to graphic objects
% X: horizonal position of the middle of the bars
%
%Description:
% This function makes a bar plot in which a (symmetric) interval around
% each value is visualized by antennas. The typically application is
% that the values itself are the means of some observed variable and
% the intervals around each mean are given as the standard deviation
% (STD) or the standard error of the mean (SEM).
%
%Examples:
% Y= diag([5 6 2])*rand(3,6)+1;
% Y_SEM= rand(3,6)+0.2;
% H= bar_with_antenna(Y, Y_SEM);
% set(gca, 'XTickLabel','Group 1|Group 2|Group 3');
% legend(H.bar, str_cprintf('bar %d',1:6));
%
% [H, xx]= bar_with_antenna(Y(1,:), Y_SEM(1,:), 'ColOrder',cmap_rainbow(6), 'AntennaColor',[0 0 0]);
% set(gca, 'XTick',xx, 'XTickLabel',1:6);
% H= bar_with_antenna(Y, Y_SEM, 'AntennaType','oo');
%
% H= bar_with_antenna(Y(1,:), Y_SEM(1,:), 'AntennaType','I', 'AntennaColor','auto', 'DrawMarker',1);
% delete(H.bar);

% Benjamin Blankertz
% Modified Laura Acqualagna 04.15: Adjusted for handling new graphcs of Matlab versions later than 8.4 

[nGroups, nCol]= size(y);
cmap_default= cmap_bluewhite(nCol, 'MinVal',0.15);

props = {'Clf',             1,              '!BOOL';
         'ColOrder',        cmap_default,   '!DOUBLE[- 3]';
         'AntennaType',     'o',            '!CHAR(o oo T TT I none)';
         'AntennaColor',    'auto',         '!CHAR(auto)|DOUBLE[- 3]';
         'AntennaSpec',     {},             'CELL';
         'AntennaWidth',    .5,             'DOUBLE[1]';
         'DrawMarker',      0,              '!BOOL';
         'MarkerSpec',      {},             'CELL';
         };

if nargin==0,
  H= props; return
end

misc_checkType(y,'!DOUBLE[- -]');
misc_checkType(y_sem,'!DOUBLE[- -]');
opt= opt_proplistToStruct(varargin{:});
[opt, isdefault]= opt_setDefaults(opt, props);
opt_checkProplist(opt, props);


if nargin<2 || isempty(y_sem),
  opt.AntennaType= 'none';
end

if ismember(opt.AntennaType, {'oo','TT','I'},'legacy'),
  [opt, isdefault]= opt_overrideIfDefault(opt, isdefault, ...
                                          'AntennaColor',0.5*[1 1 1]);
end
if isequal(opt.AntennaColor, 'auto'),
  opt.AntennaColor= opt.ColOrder;
end

if opt.Clf,
  clf;
end

if nGroups==1,  %% work-around for case nGroups=1
  H.bar= bar([y; y]);
else
  H.bar= bar(y);
end


hold on;
for c= 1:nCol,
 if verLessThan('matlab', '8.4') % old Matlab versions before 2014b
 xdata= get(get(H.bar(c),'Children'),'XData');
 xw= xdata(3,1)-xdata(1,1);
 xtmp= mean(xdata);
 else
 set(H.bar(c), 'FaceColor',opt.ColOrder(c,:));
 xtmp =  H.bar(c).XData + [H.bar(c).XOffset];
 xw=H.bar(c).BarWidth/(length(H.bar)*2-1); % BarWidth refers to the overall width of the group. 
 %To get width of single bar, divide BarWidth for number of bars + number of spaces between bars.
 end
 if nGroups==1,  %% work-around for case nGroups=1
   xtmp= xtmp(1);
 end
 xx(c,:)= xtmp;
 xtw= xw*opt.AntennaWidth/2;
 switch(opt.AntennaType),
  case 'o',
   h1= line([xx(c,:); xx(c,:)], ...
            [y(:,c), y(:,c)+y_sem(:,c)]');
   h2= line([xx(c,:); xx(c,:)], ...
            [y(:,c)+y_sem(:,c), y(:,c)+y_sem(:,c)]');
   H.antenna(:,c)= [h1; h2];
  case 'T',
   h1= line([xx(c,:); xx(c,:)], ...
            [y(:,c), y(:,c)+y_sem(:,c)]');
   h2= line([xx(c,:)-xtw; xx(c,:)+xtw], ...
            [y(:,c)+y_sem(:,c), y(:,c)+y_sem(:,c)]');
   H.antenna(:,c)= [h1; h2];
  case 'oo',
   H.antenna(:,c)= line([xx(c,:); xx(c,:)], ...
                        [y(:,c)-y_sem(:,c), y(:,c)+y_sem(:,c)]');
  case {'I','TT'},
   h1= line([xx(c,:); xx(c,:)], ...
            [y(:,c)-y_sem(:,c), y(:,c)+y_sem(:,c)]');
   h2= line([xx(c,:)-xtw; xx(c,:)+xtw], ...
            [y(:,c)+y_sem(:,c), y(:,c)+y_sem(:,c)]');
   h3= line([xx(c,:)-xtw; xx(c,:)+xtw], ...
            [y(:,c)-y_sem(:,c), y(:,c)-y_sem(:,c)]');
   H.antenna(:,c)= [h1; h2; h3];
  case 'none',
   H.antenna(:,c)= NaN;
 end
 if verLessThan('matlab', '8.4')
     if ~any(isnan(H.antenna(:,c))), 
       ci= 1+mod(c-1, size(opt.AntennaColor,1));
       set(H.antenna(:,c), 'Color',opt.AntennaColor(ci,:));
     end
 else %in the new version the previous check cannot be done in one line, if condition has been removed
       ci= 1+mod(c-1, size(opt.AntennaColor,1));
       set(H.antenna(:,c), 'Color',opt.AntennaColor(ci,:));
 end
end

switch(opt.AntennaType),
 case 'o',
  ii= nGroups+[1:nGroups];
  set(H.antenna(ii,:), 'Marker','o', 'MarkerSize',8, 'MarkerFaceColor','w');
 case 'oo',
  set(H.antenna, 'Marker','o', 'MarkerSize',8, 'MarkerFaceColor','w');
end
 if verLessThan('matlab', '8.4')
     if ~any(isnan(H.antenna(:,c))),
      set(H.antenna, 'LineWidth',4, opt.AntennaSpec{:});
     end
 else
     set(H.antenna, 'LineWidth',4, opt.AntennaSpec{:});
 end
set(gca, 'YGrid','on', 'TickLength',[0 0]);

if opt.DrawMarker,
  for c= 1:nCol,
    H.marker(:,c)= plot(xx(c,:)', y(:,c), 'd');
    ci= 1+mod(c-1, size(opt.AntennaColor,1));
    set(H.marker(:,c), 'Color',opt.AntennaColor(ci,:));
  end
  set(H.marker, 'MarkerSize',12, 'LineWidth',4, 'MarkerFaceColor','w', ...
                opt.AntennaSpec{:}, opt.MarkerSpec{:});
end

% Adjust XLim such that there is one bar-width space at the borders,
set(gca, 'XLim',reshape(xx([1 end]),[1 2])+[-1 1]*xw*1.5);
hold off;
