function  keys_out = scatter1(X,Y,G,m,ms)

% SCATTER1 -- Scatterplot of several color-coded groups
%
%  SCATTER1(X,Y) makes a basic scatterplot of (column) vectors X and Y.
%  Unlike the MATLAB function SCATTER, this doesn't make a separate 
%  patch for each data point; it basically is simply:  plot(X,Y,'.')
%
%  SCATTER1(X,Y,G) plots different groups in different colors.
%  G must be a vector (or matrix) with the same number of rows as X and Y.
%  Each unique row-value defines a "group", see UNIQUE(G,'rows').
%
%  SCATTER1(...,M) uses marker M for all groups. Default M='.'.
%  SCATTER1(...,M,MS) sets MarkerSize to MS points. Default MS=6.
%
%  keys = SCATTER1(...)  returns a matrix of group keys.
%
%  See also SCATTER, SCATTER3, PLOT, JITTER, UNIQUE.

% Original coding by Alex Petrov, Ohio State University
% $Revision: 1.0 $  $Date: 2003/03/14 18:06 $
%
% Part of the utils toolbox version 1.1 for MATLAB version 5 and up.
% http://alexpetrov.com/softw/utils/
% Copyright (c) Alexander Petrov 1999-2006, http://alexpetrov.com
% Please read the LICENSE and NO WARRANTY statement in ../utils_license.m

%-- Handle input arguments
if (nargin<3)  G = [] ; end      % one all-encompassing group
if (nargin<4)  m = '.' ; end     % default marker symbol
if (nargin<5)  ms = 6 ; end      % default marker size

%-- Partition into groups
if (~isempty(G))
   if (size(G,1)~=length(X))
      error('The group indicator G must have the same rows as X and Y.') ;
   end
   [keys,foo,integer_keys] = unique(G,'rows') ;
   N_groups = size(keys,1) ;
   %- use the ColorOrder property; recycle if N_groups>N_colors
   colors = get(gca,'ColorOrder') ;  % MATLAB default is a 7x3 RGB array
   colors = repmat(colors,ceil(N_groups/size(colors,1)),1) ;
else
   N_groups = 1 ;
   keys = [] ;
end

%-- Plot the scatterplot(s)
if (N_groups==1)
   h = plot(X,Y,m) ;
   set(h,'MarkerSize',ms) ;
else
   %- Save the hold state, see p. 8-43 in "Using MATLAB Graphics, Ver. 5"
   cax = newplot ;
   ax_nextplot = lower(get(cax,'NextPlot')) ;
   cfig = get(cax,'Parent') ;
   fig_nextplot = lower(get(cfig,'NextPlot')) ;
   %- Set HOLD ON and plot each group in turn
   hold on ; box on ;
   for k = 1:N_groups ;
      idx = find(integer_keys==k) ;
      h = plot(X(idx),Y(idx),m) ;
      %set(H(k),'Color',colors(k,:),'MarkerSize',ms) ;
      set(h,'MarkerSize',ms,'Color',colors(k,:)) ;
   end
   %- Restore the hold state
   set(cax,'NextPlot',ax_nextplot) ;
   set(cfig,'NextPlot',fig_nextplot) ;
end

if (nargout~=0)
   keys_out = keys ;
end

%--- Return KEYS
%%%%% End of file SCATTER1.M

