function [S,m,l,t,s]=som_grid(varargin)%SOM_GRID Visualization of a SOM grid%% [sGrid,m,l,t,s]=som_grid(sGrid, ['argID', value, ...])% [sGrid,m,l,t,s]=som_grid(topol, ['argID', value, ...])% [sGrid,m,l,t,s]=som_grid(lattice, msize, ['argID', value, ...])%% Input and output arguments ([]'s are optional)%  sGrid    (struct) som_grid struct (see output arguments)%  topol    (struct) map or topol struct for giving the topology%           (cell array) of form {'lattice', msize, ['shape']}. %                    Default value for 'shape' is 'sheet'.%  lattice  (string) 'hexa', 'rect' %           (matrix) size M x M, defines topological connections             %  msize    (vector) 1x2 vector defines the grid size, M=msize(1)*msize(2)%  ['argID',(string) Other arguments can be given as 'argID', value   %   value]  (varies) pairs. See list below for valid values.%%  sGrid    (struct) with fields S.msize, S.shape, S.lattice, S.coord, S.marker, %                    S.markersize, S.markercolor, S.line, S.linewidth, S.linecolor,%                    S.surf, S.label, S.labelsize, S.labelcolor%  m        (matrix) handels to LINE objects (unit markers) %  l        (matrix) handles to LINE objects (lines connecting the units)%  t        (matrix) handles to TEXT objects (labels)%  s        (scalar) handle  to SURF object  (surface between units)%%  Here are the valid argument IDs (case insensitive) and%  associated values: %  'Coord'       Mx2 or Mx3 matrix of coordinates %                (default: according to lattice as in som_cplane)%  'Marker'      string 'o','+','x','*','v','^','<','>','h','s','d','p','.', %                'none' or Mx1 cell or char array of these strings %                Default: 'o'.  %  'MarkerSize'  scalar or Mx1 matrix of double. Default: 6.%  'MarkerColor' ColorSpec or Mx3 matrix of RGB triples. Default: 'k'.%  'Line'        string '-',':','--' or '-.' or 'none'. Default: '-'.%  'Surf'        [], Mx1 or Mx3 matrix of RGB triples %                to define surface values. Default: [] = no surf. %                Note: shading is turned to 'interp'.%  'LineWidth'   scalar or MxM matrix, default: 0.5%  'LineColor'   ColorSepc, MxMx3 matrix of RGB triples or a cell array %                of form {r g b} where r,g, and b are MxM  %                (sparse) matrices of R,G, and B values%  'Label'       Mx1 char array, cell array of strings size MxL %                or [] to indicate no labels, default: [] = no labels.%  'LabelSize'   scalar%  'LabelColor'  ColorSpec or string 'none', default: 'g'.%% For more help, try 'type som_grid' or check out online documentation.% See also SOM_CONNECTION, SOM_SHOW, SOM_CPLANE, SOM_SET, SCATTER, SCATTER3.%%%%%%%%%%%%%%% DETAILED DESCRIPTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% som_grid%% PURPOSE % %  To visualize the SOM grid in various ways % % SYNTAX%%  [sGrid,m,l,t,s]=som_grid(sGrid)%  [sGrid,m,l,t,s]=som_grid(sTopol)%  [sGrid,m,l,t,s]=som_grid(sMap)%  [sGrid,m,l,t,s]=som_grid({lattice, msize, [shape]}) %  [sGrid,m,l,t,s]=som_grid(lattice, msize)%  [sGrid,m,l,t,s]=som_grid(..., ['argID', value, ...])%% DESCRIPTION %% The SOM can be defined as a set of units (neurons) and their% topological relations.  This function is used to visualize these in% various ways. The units may be drawn using different markers and% colors, in different sizes and in different locations in 2D or% 3D. However the topological neighborhood is limited to be% 2-dimensional. The connections between these units may be drawn using% lines having different thicknesses and colors. Labeling text may be% plotted on the units. It is possible also to draw a surface between% the units. The surface coloring is either indexed (one value per% unit) or fixed RGB (a 1x3 RGB triple per unit).%% REQUIRED INPUT ARGUMENTS %% Note: M is the number of map units.% % The first (or first two) argument may have various different types of values%%   1. sGrid   (struct) som_grid struct (the output of this function)%  %     The struct initiates the visualization. The argID-value -pairs%     are used to alter the initiation.%%   Following argument types may be used to give the topology for the grid% %   2. sTopol  (struct) som_topol struct %   3. sMap    (struct) som_map struct (only topology matters)%   4. {lattice, msize} or {lattice, msize, sheet} (cell array) %       - lattice must be 'hexa' or 'rect'%       - msize must be a 1x2 vector%       - shape (if specified) must be string 'sheet', 'cyl' or 'toroid'%         If shape is not given it is 'sheet' by default.%   5. lattice (string or matrix) AND msize (1x2 vector) as two separate arguments%       - lattice may be string 'rect' or 'hexa' or a connection matrix%         (see SOM_CONNECTION) to define a free topology. This connection%         matrix is of size MxM and its element i,j (i<j) is set%         to 1 if there is a connection between units i and j, otherwise to %         zero. Shape is set to 'sheet' by default. Shape does not have any %         meaning if a free topology is specified, anyway.%       - msize must be a 1x2 vector%%  In cases 2...5 the sGrid structure is initiated by default values%  which are set in SOM_SET. These include black markers 'o' (6pt),%  light gray conncection lines (graph edges), unit coordinates%  according to the lattice ('hexa','rect'), no labels, and no%  surface.%%  OPTIONAL INPUT ARGUMENTS %   %  Note: M is the number of map units.%   %  Here is a list of the valid arguments IDs and the associated%  values (identifiers are case insensitive):%%  'Coord'     Unit coordinates%              This defines the coordinates of the units. Default: the%              topological coordinates (calculated as in function%              SOM_VIS_COORDS and SOM_CPLANE). If the topology is free%              (lattice is a connection matrix) this argument is obligatory!%     (matrix) size Mx2 of 2D coordinates for each unit%     (matrix) size Mx3 of 3D coordinates for each unit% % 'Marker'       Unit markers, default is 'o'.%     (string) 'o','+','x','*','v','^','<','>','h','s','d', 'p','.', or 'none'%              give the same marker for each unit. %     (cell array) of size Mx1 of previous strings gives individual %              markers for each unit.%     % 'MarkerSize'   Size (pt) of unit markers, default is 6 (pt).%     (scalar) gives the same size for every unit.  %     (matrix) Mx1 gives an individual size for each unit marker.  %%  'MarkerColor' Unit marker colors, default is 'k'%     (ColorSpec) gives the same color each unit. %     (matrix) Mx3 of RGB triples gives individual color for each unit%              Note that indexed coloring - like in SOM_CPLANE - is%              not possible. If indexed coloring is needed, you can%              use SOM_NORMCOLOR to calculate RGB colors that%              emulate indexed coloring. However, the colors for the%              units are fixed, so changing colormap will not%              change the colors.%  %  'Line'        Line type, default is '-'.%     (string) '-',':','--' or '-.' or 'none'. Only one linetype in%              grid is allowed.  %%  'LineWidth'   Width of the topological connection lines (edges)  %     (scalar) gives the same width for each line. Default is 0.5.%     (matrix) MxM sparse (or full) matrix gives individual width for %              each connection. The element (i,j), i<j, gives the line width for %              connection between nodes i and j. (The sparse form is%              recommended for saving memory, a full matrix works as well,%              of course). Note that only the elements satisfying i<j%              matter - as the elememts for which j >= i are ignored in%              order to avoid ambiguous situations if the matrix would be %              non-symmetric. The "connections to oneself" is not drawn. %%              Line width zero is valid and causes the line to disappear.%           %  'LineColor'   Color of connection lines, default is [0.9 0.9 0.9].%     (ColorSpec) gives the same color for each line%     (matrix) MxMx3 matrix of RGB triples gives individual width for %              each connection. The element (i,j,:), i<j, gives the RGB triple for %              line between nodes i and j.     %     (cell array) of three sparse (or full) matrices {r,g,b} where %              r(i,j), g(i,j) and b(i,j) gives the R,G, and B values in the RGB%              triple for the line between nodes i and j. (The motivation for this%              form is the fact that a 3D arrays can't use sparse format in %              Matlab version 5.1.)%  %              Note that only the elements satisfying i<j matter - the elememts %              for which j >= i are ignored in order to avoid ambiguous situations %              if the matrix was non-symmetric. The "connections to oneself"%              is not drawn. %    %%  'Label'       Labels for units, default is [].%     (empty)  [] means no labels.%     (char array) of size Mx1. Element (i,:) has the label for unit i.     %     (cell array) of size MxL consisting of sets of labels. Element {i,:} %              contains the labeling for unit i. %               In case of multiple labels, the labels for one unit are shown %               in one column centered at that unit.%    %   'LabelSize'   Text size of labels (points), default is 10.%     (scalar) Default is 10.%%   'LabelColor'  Color of labels, default is 'c' (cyan).%     (ColorSpec) gives the same color for each label string 'xor'%                 sets the colors automatically so that they differ%                 from the background (using Matlab's built-in xor-color feature.)%    %  'Surf'         Surface between nodes, default is [].%     (empty)  [] gives no surface%     (vector) Mx1 gives an indexed interpolated color surface between %              units using the actual colormap.%     (matrix) Mx3 matrix of RGB triples gives a interpolated color surface %              between units using fixed RGB colors.%    %              Note that the interpolation is done using Matlab's built-in%              color interpolation for SURF objects.%% OUTPUT ARGUMENTS%%  sGrid    (struct) with fields S.msize, S.shape, S.lattice, S.coord, S.marker, %                    S.markersize, S.markercolor, S.line, S.linewidth, S.linecolor,%                    S.surf, S.label, S.labelsize, S.labelcolor%%  m        (matrix) handels to LINE objects (unit markers) %%  l        (matrix) handles to LINE objects (lines connecting the units)% %  t        (matrix) handles to TEXT objects (labels)%%  s        (scalar) handle  to SURF object  (surface between units)%% EXAMPLES%% % Make map of size 15x10 on random data:% %    map=som_make(rand(1000,4),'msize',[15 10], 'lattice', 'hexa');%% % Draw the grid using two frist varable values as coordinates% % and store the sGrid struct in varable S:%%    S=som_grid(map, 'coord', map.codebook(:,[1 2]))%% %Define some things: % %% % Create a cell array of size 150x1 that divides map in to two label classes% % 'circles' and 'squares'%   %    L(1:75,1)='o'; L(76:150,1)='s'; L = cellstr(L);%    % % Create a coloring according to the 3rd variable according to current% % colormap: %    %    C = som_normcolor(map.codebook(:,3));% % % Change the visualization: use black lines, unit markers in M and unit% % color in C, and set unit size to 10:%%    S=som_grid(S, 'linecolor', 'k', 'marker', L, 'MarkerColor',C, ...%     'MarkerSize', 10);%% % Do a new visualization, use indexed color surface calcualted from the% % first variable, coordinates according to the lattice (default) but % % no markers nor lines:% %    S=som_grid(map,'line','none','marker','none','surf',map.codebook(:,1));%% % Set coordinates according to three last varables%%    som_grid(S,'coord',map.codebook(:,2:4));%% % Create a random connection matrix R1 and the usual hexagonal% % neighborhood connection matrix R2: % %    R1=sparse(rand(150,150)>0.9); %    R2=som_connection(map);%% % Show these connections. Note that coordinates _must_ now be given% % explicitly: we form default topological coordinates using% % som_unit_coords.%%    som_grid(R1,map.topol.msize,'coord',som_unit_coords(map));%    som_grid(R2,map.topol.msize,'coord',som_unit_coords(map));%    % % Show connections (R1 AND R2)%    som_grid(R2.*R2,map.topol.msize,'coord',som_unit_coords(map));% % OBJECT TAGS%%  No tags are set.%% SEE ALSO%%  som_show        The basic map visualization routine%  som_cplane      The basic component plane visualization%  som_connection  The basic topological connections%  scatter         Scatter plots%  scatter3        3-dimensional scatter plots % Copyright (c) 1999-2000 by the SOM toolbox programming team.% http://www.cis.hut.fi/projects/somtoolbox/             % Version 2.0beta Johan 061099 juuso 151199 310300%% Init %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%True=1; False=0;                % const.m=[]; l=[]; t=[]; s=[];         % default values for outputsRef=som_set('som_grid');        % reference structnum_of_args=length(varargin);   % numb. of vararginsif num_of_args==0,  S=som_set('som_grid');  return;endswitch class(varargin{1})case 'struct'  S=varargin{1};  first_identifier=2;  if ~isfield(S,'type'),    error('Input struct is invalid: field ''type'' is missing.');  end  switch  S.type  case 'som_grid'    S=varargin{1};    first_identifier=2;  case 'som_map'    Ref.lattice=S.topol.lattice;    Ref.msize=S.topol.msize;    Ref.shape=S.topol.shape;    S=Ref;    first_identifier=2;  case 'som_topol'    Ref.lattice=S.lattice;    Ref.msize=S.msize;    Ref.shape=S.shape;    S=Ref;    first_identifier=2;  otherwise    error('Input struct has to be of type som_grid, som_map or som_topol.');  endcase 'cell'  S=varargin{1};  first_identifier=2;  if vis_valuetype(S,{'topol_cell_no_shape'}),    Ref.lattice=S{1};    Ref.msize=S{2};  elseif vis_valuetype(S,{'topol_cell'}),    Ref.lattice=S{1};    Ref.msize=S{2};    Ref.shape=S{3};  else    error(['The cell value for 1st argument has to be {lattice, msize}' ...	  'or {lattice, msize, shape}.']);   end  S=Ref; case{'double','sparse','char'}   % Set defaults  S=Ref;  first_identifier=3;   if num_of_args<2,    error('Not enough input arguments.');  end  S.lattice=varargin{1};  S.msize=varargin{2};otherwise  error('Invalid input arguments!');end  %% Check input args %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%for i=first_identifier:2:num_of_args,  if ischar(varargin{i}) & isfield(Ref,lower(varargin{i})),    if i+1>num_of_args,      error('Invalid identifier-value pairs or wrong argument order.');    else      S=setfield(S,lower(varargin{i}),varargin{i+1});    end  elseif ischar(varargin{i}),     error(['Identifier ''' varargin{i} ''' is unknown.']);  else    error('Invalid identifier-value pairs or wrong argument order.');  endend % msizeif ~vis_valuetype(S.msize,{'1x2'}),  error('msize has to be a 1x2 vector.');end