comparison toolboxes/MIRtoolbox1.3.2/somtoolbox/som_cplane.m @ 0:e9a9cd732c1e tip

first hg version after svn

+function h=som_cplane(varargin) 
+
+%SOM_CPLANE Visualize one 2D component plane, U-matrix or color plane.
+%
+% h=som_cplane(lattice, msize, color, [s], [pos]) 
+% h=som_cplane(topol, color, [s], [pos]) 
+%
+%  som_cplane('hexa', [10 5], 'none');
+%  som_cplane('rect', [10 5], 'r');
+%  som_cplane(sM.topol, sM.codebook(:,1));
+%  U = som_umat(sM); som_cplane('hexaU',sM.topol.msize,U(:));
+%
+%  Input and output arguments ([]'s are optional): 
+%   lattice   (string) 'hexa', 'rect' (component planes)
+%                      'hexaU', 'rectU' (corresponding U-matrices)
+%             (matrix) defines the patch (see function VIS_PATCH).
+%   msize     (vector) 1x2 vector defines grid size (M=prod(msize))
+%             (matrix) Mx2 matrix gives explicit coordinates for each node
+%   topol     (struct) map or topology struct
+%   color              color for the nodes
+%             (matrix) Mx1 matrix gives indexed colors for the units
+%                      Mx3 matrix of RGB triples gives explicit
+%                      color for each unit
+%                      (Note: in case of U-matrix, the number of color
+%                      values is 4*prod(msize)-2*sum(msize)+1, not prod(msize))
+%             (string) ColorSpec gives the same color for each node
+%                      'none' draws black edges only.              
+%   [s]       (matrix) size Mx1, gives individual size scaling for each node 
+%             (scalar) gives the same size for each node, default=1.
+%                      Additional features: see 'type som_cplane' 
+%                      This argument is ignored if the lattice is 'rectU' or 'hexaU'.
+%   [pos]     (vector) a 1x2 vector that determines position of origin, 
+%                      default is [1 1].
+%
+%   h         (scalar) the object handle for the PATCH object
+%
+% Axis are set to the 'ij' mode with equal spacing and turned off if
+% 'pos' is not given. If 'lattice' is 'rect', 'hexa', 'rectU' or
+% 'hexaU' the node (a,b) has coordinates (a,b) (+pos), except on the
+% even numbered rows on the 'hexa' and 'hexaU' grids where the
+% coordinates are (a,b+0.5) (+pos).
+%
+% For more help, try 'type som_cplane' or check out online documentation.
+% See also SOM_PIEPLANE, SOM_PLOTPLANE, SOM_BARPLANE, VIS_PATCH,
+%          SOM_VIS_COORDS
+
+%%%%%%%%%%%%% DETAILED DESCRIPTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% som_cplane
+%
+% PURPOSE
+% 
+% Visualizes a 2D component plane or u-matrix
+%
+% SYNTAX
+%
+%  h = som_cplane(topol, color)
+%  h = som_cplane(lattice, msize, color)
+%  h = som_cplane(lattice, msize, color)
+%  h = som_cplane(..., size) 
+%  h = som_cplane(..., size, pos) 
+%
+% DESCRIPTION
+%
+% Creates some basic visualizations of the SOM grid: the component plane and
+% the unified distance matrix. The routine draws the SOM grid as a patch
+% object according to the specifications given in the input arguments and
+% returns its object handle.
+% 
+% Each unit of the map is presented by a polygon whose color, size, shape
+% and location can be specified in various ways. The usual procedure 
+% is to choose the lattice and map size used in the map training. Then
+% the function creates the standard sheet shaped topological 
+% representation of the map grid with hexagonal or rectangular units.
+% When the values from a map codebook component (or from SOM_UMAT) 
+% are given to the function it produces an indexed coloring for the 
+% units (as in SURF command). Another possibility is to give a fixed 
+% RGB color for each unit explicitly.
+% 
+% Special effects (variable unit size, location or shape) can be produced
+% giving different types of input variables.
+%
+% KNOWN BUGS
+%
+% Using 1x3 or 3x1 grids causes problem, as the MATLAB will treat the color 
+% information vector 1x3 or 3x1 as a single RGB triple. So, using indexed 
+% colors is not possible for this particular map size.
+%
+% It is not possible to specify explicit coordinates for map
+% consistig of just one unit as then the msize is interpreted as
+% map size.
+%
+% REQUIRED INPUT ARGUMENTS
+% 
+% Note: M is the number of map units
+%
+% lattice  The basic shape of the map units 
+%
+%   (string) 'hexa' or 'rect' creates standard component plane; 
+%            'hexaU' or 'rectU' creates standard u-matrix.
+%   (matrix) Lx2 matrix defines the cornes of an arbitary polygon to be used
+%            as the unit marker. (L is the number of patch vertex: L=6 for 
+%            'hexa' and L=4 for 'rect') 
+%
+% msize    The size of the map grid     
+%         
+%   (vector) [n1 n2] vector defines the map size (height n1 units, width 
+%            n2 units, total M=n1 x n2 units). The units will be placed to their 
+%            topological locations to form a uniform hexagonal or rectangular grid.
+%   (matrix) Mx2 matrix defines arbitrary coordinates for the M units
+%            In this case the argument 'lattice' defines the unit form only. 
+%
+% topol    Topology of the map grid
+%
+%   (struct) map or topology struct from which the topology is taken
+% 
+% color    Unit colors
+%           
+%   (string) (ColorSpec) gives the same color for each unit, 'none'
+%            draws black unit edges only.
+%   (vector) Mx1 column vector gives indexed color for each unit using the 
+%            current colormap (see help colormap).   
+%   (matrix) Mx3 matrix of RGB triples as rows gives each unit a fixed color.
+%
+% OPTIONAL INPUT ARGUMENTS
+%
+% Note: M is the number of map units. 
+% Note: if unspecified or given empty values ('' or []) default
+% values are used for optional input arguments.
+% 
+% s        The size scaling factors for the units
+% 
+%   (scalar) scalar gives each unit the same size scaling: 
+%            0   unit disappears (edges can be seen as a dot).
+%            1   by default unit has its normal size (ie. no scaling)
+%            >1  unit overlaps others      
+%   (matrix) Mx1 double: each unit gets individual size scaling
+%
+% pos      Position of origin          
+% 
+%   (vector) This argument exists to be able drawing component planes
+%            in arbitrary locations in a figure. Note the operation:
+%            if this argument is given, the axis limits setting
+%            part in the routine is skipped and the limits setting
+%            will be left to be done by MATLAB's default
+%            operation. 
+%
+% OUTPUT ARGUMENTS
+%
+% h (scalar) handle to the created patch object
+% 
+% OBJECT TAGS     
+%
+% One object handle is returned: field Tag is set to
+%  'planeC'  for component plane     
+%  'planeU'  for U-matrix
+%
+% FEATURES
+%
+% There are some extra features in following arguments
+%
+% size
+%  - MxL matrix: radial scaling: the distance between 
+%    the center of node m and its kth vertex is scaled by
+%    s(m,k).
+%  - Mx1x2 matrix: the uniform scaling is done separately for
+%    x- and y-directions
+%  - MxLx2 matrix: the scaling is done separately to x- and y-
+%    directions for each vertex.
+%
+% color
+%    Each vertex may be given individual color. 
+%    The PATCH object interpolates the colors on the 
+%    face if shading is turned to interp. 
+%  - 1xMxL matrix: colormap index for each vertex
+%  - LxMx3 matrix: RGB color for each vertex
+%
+% Note: In both cases (size and color) the ordering of the patch
+% vertices in the "built-in" patches is the following
+%
+%          'rect'      'hexa'
+%            1 3          1 
+%            2 4         5 2
+%                        6 3
+%                         4
+%
+% The color interpolation result seem to depend on the order 
+% in which the patch vertices are defined. Anyway, it gives 
+% unfavourable results in our case especially with hexa grid: 
+% this is a MATLAB feature.
+%
+% EXAMPLES
+%
+% m=som_make(rand(100,4),'msize',[6 5])         % make a map
+% 
+% % show the first variable plane using indexed color coding
+%          
+% som_cplane(m.topol.lattice,m.topol.msize,m.codebook(:,1));  
+% or som_cplane(m.topol,m.codebook(:,1));  
+% or som_cplane(m,m.codebook(:,1));  
+%
+% % show the first variable using different sized black units
+%  
+% som_cplane(m,'k',m.codebook(:,1));
+% 
+% % Show the u-matrix. First we have to calculate it. 
+% % Note: som_umat returns a matrix therefore we write u(:) to get 
+% % a vector which contains the values in the proper order.
+% 
+% u=som_umat(m); 
+% som_cplane('hexaU', m.topol.msize, u(:)); 
+%
+% % Show three first variables coded as RGB colors
+% % and turn the unit edges off
+% 
+% h=som_cplane(m, m.codebook(:,1:3),1)
+% set(h,'edgecolor','none');
+%
+% % Try this! (see section FEATURES)
+% 
+% som_cplane('rect',[5 5],'none',rand(25,4));
+% som_cplane('rect',[5 5],rand(1,25,4));
+%
+% SEE ALSO
+%
+% 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_umat       Compute unified distance matrix of self-organizing map
+% vis_patch      Define the basic patches used in som_cplane
+% som_vis_coords The default 'hexa' and 'rect' coordinates in visualizations
+
+% Copyright (c) 1999-2000 by the SOM toolbox programming team.
+% http://www.cis.hut.fi/projects/somtoolbox/             
+
+% Version 2.0beta Johan 061099 juuso 151199 juuso 070600
+
+%%% Check & Init  arguments %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+[nargin, lattice, msize, color, s, pos]=vis_planeGetArgs(varargin{:});
+error(nargchk(3, 5, nargin));  % check no. of input args is correct
+
+%% Translation?
+
+if nargin < 5 | isempty(pos)
+  pos=NaN;              % "no translation" flag
+elseif ~vis_valuetype(pos,{'1x2'}),
+  error('Position of origin has to be given as an 1x2 vector.');
+end
+
+%% Patchform %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+switch class(lattice)
+case 'char'             % built-in patchforms
+  pos=pos-1;
+  switch lattice
+  case {'hexa', 'hexaU'}
+    patchform=vis_patch('hexa');
+  case {'rect', 'rectU'}
+    patchform=vis_patch('rect');
+  otherwise
+    error([ 'Lattice ' lattice ' not implemented!']);
+  end
+case { 'double', 'sparse'}
+  if vis_valuetype(lattice,{'nx2'}),
+    patchform=lattice; % users patchform
+    lattice='rect';    
+  else
+    error('Patchform matrix has wrong size');
+  end
+otherwise
+  error('String or matrix expected for lattice.');
+end
+
+l=size(patchform,1);     % number of vertices    
+planeType=lattice(end);  % 'U' if umatrix otherwise something else
+
+if ~vis_valuetype(msize,{ '1x2', 'nx2'}),
+  error('msize has to be given as 1x2 or nx2 vectors.');
+end
+
+%% msize or coordinates %%%%%%%%%%%%%%%%%%%%%%%
+
+if size(msize,1)>1 
+  % msize is coordinate matrix Nx2?
+  
+  if planeType == 'U',  % don't accept u-matrix
+    error('U-matrix visualization doesn''t work with free coordinates.');
+  end
+  
+  % set number of map unit and unit coordinates 
+  munits=size(msize,1);
+  unit_coords=msize; msize=[munits 1];
+  
+  if isnan(pos),         % no translation is done here 
+    pos=[0 0];           % using [0 0] in order to prevent 
+  end	                 % axis tightening in
+                         % vis_PlaneAxisProperties (arbitary coords!) 
+else
+  % msize is built-in lattice
+  
+  unit_coords=som_vis_coords(lattice,msize);
+  
+  % Calculate matrices x and y which 'moves' nodes 
+  % to the correct positions:
+  % For U-matrix, the size has to be recalculated
+  if planeType == 'U',
+    xdim=2*msize(1)-1;ydim=2*msize(2)-1;
+  else
+    xdim=msize(1);ydim=msize(2);
+  end
+  munits=xdim*ydim;
+  
+  % Feature warning
+  if munits == 3  
+    warning('Problems with 1x3 and 3x1 maps. See documentation.');
+  end
+end
+
+%% Color matrix %%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+if ~isnumeric(color) & ~ischar(color),
+  error('Color matrix is invalid.');
+else
+  d=size(color);           
+  switch length(d)       
+  case 2   %% Flat colors
+    if ischar(color) % Check for string 'none'
+      if strcmp(color,'none'), 
+	color=NaN;
+      end
+    else               
+      if ~(d(1)== 1 & d(2) == 3) & ...
+	    ~(d(1) == munits & (d(2)==1 | d(2)==3))
+	error('Color data matrix has wrong size.');
+      elseif d(1)~=1 & d(2)==3 
+	if any(color>1 | color<0)
+	  error('Color data matrix has invalid RGB values.');
+	end
+	color=reshape(color,[1 munits 3]);  % RGB colors
+      elseif d(2)==1
+	color=color';                       % indexed
+      end
+    end
+  case 3   %% Interpolated colors
+    if d(1) == 1 & d(2) == munits & d(3) == l,  
+      color=reshape(color, l, munits);
+    elseif ~(d(1) == l & d(2) == munits & d(3) == 3) 
+      error('Color data matrix has wrong size.');
+    end
+  otherwise
+    error('Color data matrix has too many dimensions.');
+  end
+end
+
+%% Size matrix? %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+if nargin < 4 | isempty(s),  
+   s=1;      % default value for s (no scaling)
+elseif ~isnumeric(s)
+  error('Size matrix is not numeric.');
+end
+
+%%Determine the type of size matrix
+d=size(s);                  
+switch length(d)
+case 2  
+  if (d(1)==1 & d(2)==1),
+    % Each node gets the same, uniform scaling.
+    s=s'; sx=s; sy=s;	
+  elseif (d(1)==munits & d(2)==l),
+    % Each vertex is scaled radially respetc to the 
+    % node center.
+    s=s'; sx=s; sy=s;          
+  elseif d(1)==munits & d(2)==1  
+    % Each node gets an individual uniform scaling.
+    sx=repmat(s',l,1); sy=sx;
+  else
+    error('Size matrix has wrong size.');
+  end
+case 3  
+  if d(1)==munits & d(2)==1 & d(3)==2,     
+    % Each node is individually and uniformly 
+    % scaled separately to x- and y-directions.
+    sx=repmat(shiftdim(s(:,:,1))',l,1);   
+    sy=repmat(shiftdim(s(:,:,2))',l,1);   
+  elseif d(1)==munits & d(2)==l & d(3)==2,
+    % Each vertex is scaled separately to x- and y-directions
+    % with respect to the node center.
+    sx=shiftdim(s(:,:,1))';                
+    sy=shiftdim(s(:,:,2))';              
+  else
+    error('Size matrix has wrong size.');
+  end
+otherwise 
+  error('Size matrix has too many dimensions.');
+end
+
+% Size zero would cause division by zero. eps is as good (node disappears)
+% I tried first NaN, it works well otherwise, but the node is 
+% then not on the axis and some commands may the work oddly. 
+% The edge may be visible, though.
+
+sx(sx==0)=eps;                    
+sy(sy==0)=eps;                
+
+% Rescale sizes for u-matrix
+if planeType=='U', 
+   sx=sx/2;sy=sy/2; 
+end
+
+%%%% Action %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+% Making grid. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+% Translation for each patch
+
+x=repmat(unit_coords(:,1)',l,1);
+y=repmat(unit_coords(:,2)',l,1);
+
+% patch vertex coordiantes 
+
+nx=repmat(patchform(:,1),1,munits); 
+ny=repmat(patchform(:,2),1,munits); 
+
+% NB: The hexagons are not uniform in order to get even  
+% y-coordinates for the nodes. This is handled by setting _axis scaling_ 
+% so that the hexa-nodes look like uniform hexagonals. See 
+% vis_PlaneAxisProperties
+
+%% Make and scale the final input for PATCH:
+
+% 1: combine translation and scaling of each patch 
+x=(x./sx+nx).*sx; y=(y./sy+ny).*sy;  
+
+%% 2: translation of origin (pos)
+if ~isnan(pos)
+   x=x+pos(1);y=y+pos(2);    % move upper left corner 
+end                         % to pos
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+%% Set axes properties  
+%% Command view([0 90]) shows the map in 2D properly oriented
+
+ax=newplot;                               % set new plot
+vis_PlaneAxisProperties(ax,lattice,msize,pos);
+
+%% Draw the map! 
+
+if ~isnan(color)
+   h_=patch(x,y,color);         
+else
+   h_=patch(x,y,'k');                     % empty grid 
+   set(h_,'FaceColor','none');
+end
+
+%% Set object tag
+
+if planeType=='U'
+   set(h_,'Tag','planeU');                      
+else
+   set(h_,'Tag','planeC');
+end	
+
+%%% Build output %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+if nargout>0, h=h_; end                   % Set h only, 
+                                          % if there really is output
+