function unit_coord=som_vis_coords(lattice, msize)
%SOM_VIS_COORDS The default 'hexa' and 'rect' coordinates in visualizations
% 
% function unit_coord=som_vis_coords(lattice, msize)
%
%   coord=vis_unit_coords('hexa',[10 7])
%
% INPUT ARGUMENTS ([]'s are optional)
% 
%  lattice   (string) 'hexa', 'rect', 'hexaU' or 'rectU'
%  msize     (vector)  grid size in a 1x2 vector    
%
% OUTPUT ARGUMENTS
% 
%  unit_coord (matrix) Mx2 matrix of unit coordinates
% 
% This function may be used to calculate the coordinates according
% to the lattice for the 'hexa' and 'rect' topologies. 'hexaU' and
% 'rectU' calculates the coordinates of both units and the
% connections for u-matrix visualizations 
%
% For more help, try 'type som_unit_coords' or check out the helpdesk.
% See also: som_unit_coords, som_cplane, som_grid

%%%%%%%%% DETAILED DESCRIPTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% PURPOSE 
% 
% Returns coordinates of the map units for map visualization
%
% SYNTAX
%
% unit_coord=som_vis_coords(lattice, msize)
%
% DESCRIPTION
%
% This function calculates the coordinates of map units in 'hexa'
% and 'rect' topologies for visualization purposes. It differs from 
% SOM_UNIT_COORDS in the sense, that hexagonal lattice is
% calculated in a 'wrong' way in order to get integer coordinates
% for the units. Another difference is that it may be used to calculates the
% coordinates of units _and_ the center points of the lines
% connecting them (edges). This property may be used for drawing u-matrices. 
%
% The unit number 1 is set to (ij) coordinates (1,1)+shift
%                 2                            (2,1)+shift
%
%  ... columnwise
% 
%             n-1th                        (n1-1,n2)+shift
%             nth                            (n1,n2)+shift
%
% where grid size = [n1 n2] and shift is always zero for 'rect' lattice 
% For 'hexa' lattice shift is +0.5 if n1 is even otherwise zero.
%
% For 'rectU' and 'hexaU' the unit coordinates are the same and the 
% coordinates for connections are set according to these. In this
% case the ordering of the coordinates is the following: 
%
%  Let
%   U=som_umat(sMap); 
%   Uc=som_vis_coords(sMap.topol.lattice, sMap.topol.msize); 
%  and 
%   U=U(:);  % this makes the matrix U to a column vector 
%  Now the kth row of matrix Uc, i.e. Uc(k,:), contains the coordinates 
%  for value U(k). 
%
% REQUIRED INPUT ARGUMENTS 
%
% lattice   The local topology of the units
%
%   (string) 'hexa', 'rect', 'hexaU' or 'rectU'
% 
% msize     Grid size (only 2 dim)    
%
%   (vector) a 1x2 vector defining the grid size
%
% OUTPUT ARGUMENTS
% 
% unit_coord (Mx2 matrix) the unit coordinates
%
% FEATURES
% 
% Only 'sheet' shaped maps are considered. If coordinates for
% 'toroid' or 'cyl' topologies are required, you must use
% SOM_UNIT_COORDS instead. 
%
% EXAMPLES
%
% Though this is mainly a subroutine for visualizations it may be
% used, e.g., in the following manner:
%
% % This makes a hexagonal lattice, where the units are rectangular
% % instead of hexagons.
%    som_cplane('rect',vis_unit_coords('hexa',[10 7]),'none');
%
% % Let's make a map and calculate a u-matrix: 
%    sM=som_make(data,'msize',[10 7],'lattice','hexa');
%    u=som_umat(sM); u=u(:);
% % Now, these produce equivalent results:
%    som_cplane('hexaU',[10 7],u);
%    som_cplane(vis_patch('hexa'/2,som_vis_coords('hexaU',[10 7]),u);
%
% SEE ALSO
%
% SOM_GRID       Visualization of a SOM grid
% SOM_CPLANE     Visualize a 2D component plane, u-matrix or color plane
% SOM_BARPLANE   Visualize the map prototype vectors as bar diagrams.
% SOM_PLOTPLANE  Visualize the map prototype vectors as line graphs
% SOM_PIEPLANE   Visualize the map prototype vectors as pie charts
% SOM_UNIT_COORDS Locations of units on the SOM grid

% Version 2.0alpha Johan 201099
% Copyright (c) 1999 by the SOM toolbox programming team.
% http://www.cis.hut.fi/projects/somtoolbox/             

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

if ~vis_valuetype(msize,{'1x2'}),
  error('msize must be a 1x2 vector.')
end

if vis_valuetype(lattice,{'string'})
  switch lattice
  case {'hexa', 'rect'}
    munits=prod(msize);
    unit_coord(:,1)=reshape(repmat([1:msize(2)],msize(1),1),1,munits)';
    unit_coord(:,2)=repmat([1:msize(1)]',msize(2),1);
    if strcmp(lattice,'hexa')
      % Move even rows by .5
      d=rem(unit_coord(:,2),2) == 0;   
      unit_coord(d,1)=unit_coord(d,1)+.5;
    end
  case {'hexaU','rectU'}
    msize=2*msize-1; munits=prod(msize);
    unit_coord(:,1)=reshape(repmat([1:msize(2)],msize(1),1),1,munits)';
    unit_coord(:,2)=repmat([1:msize(1)]',msize(2),1);
    if strcmp(lattice,'hexaU')
      d=rem(unit_coord(:,2),2) == 0;   
      unit_coord(d,1)=unit_coord(d,1)+.5;
      d=rem(unit_coord(:,2)+1,4) == 0; 
      unit_coord(d,1)=unit_coord(d,1)+1;
    end
    unit_coord=unit_coord/2+.5;
  otherwise
    error([ 'Unknown lattice ''' lattice '''.']);
  end
else
  error('Lattice must be a string.');
end
