wolffd@0: function h=som_plotplane(varargin)
wolffd@0: 
wolffd@0: %SOM_PLOTPLANE  Visualize the map prototype vectors as line graphs
wolffd@0: %
wolffd@0: % h=som_plotplane(lattice, msize, data, [color], [scaling], [pos])
wolffd@0: % h=som_plotplane(topol, data, [color], [scaling], [pos])
wolffd@0: %
wolffd@0: %  som_plotplane('hexa',[5 5], rand(25,4), jet(25)) 
wolffd@0: %  som_plotplane(sM, sM.codebook)
wolffd@0: %
wolffd@0: % Input and output arguments ([]'s are optional)
wolffd@0: %  lattice   (string) grid 'hexa' or 'rect'
wolffd@0: %  msize     (vector) size 1x2, defines the grid size 
wolffd@0: %            (matrix) size Mx2, defines explicit coordinates: in 
wolffd@0: %             this case the first argument does not matter 
wolffd@0: %  topol     (struct) map or topology struct
wolffd@0: %  data      (matrix) Mxd matrix, M=prod(msize) 
wolffd@0: %  [color]   (matrix) size Mx3, gives an individual color for each graph
wolffd@0: %            (string) ColorSpec gives the same color for each
wolffd@0: %             graph, default is 'k' (black)
wolffd@0: %  [scaling] (string) 'on' or 'off', default is 'on' 
wolffd@0: %  [pos]     (vector) 1x2 vector that determines translation. 
wolffd@0: %             Default is no translation.
wolffd@0: %
wolffd@0: %  h         (vector) the object handles for the LINE objects
wolffd@0: %
wolffd@0: %  If scaling is set on, the data will be linearly scaled in each
wolffd@0: %  unit so that min and max values span from lower to upper edge
wolffd@0: %  in each unit. If scaling is 'off', the proper scaling is left to 
wolffd@0: %  the user: values in range [-.5,.5] will be plotted within the limits of the 
wolffd@0: %  unit while values exceeding this range will be out of the unit. 
wolffd@0: %  Axis are set as in SOM_CPLANE.
wolffd@0: %
wolffd@0: % For more help, try 'type som_plotplane' or check out online documentation.
wolffd@0: % See also SOM_PLANE, SOM_PIEPLANE, SOM_BARPLANE
wolffd@0: 
wolffd@0: %%%%%%%%%%%%% DETAILED DESCRIPTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
wolffd@0: %
wolffd@0: % som_plotplane
wolffd@0: %
wolffd@0: % PURPOSE
wolffd@0: % 
wolffd@0: % Visualizes the map prototype vectors as line graph
wolffd@0: %
wolffd@0: % SYNTAX
wolffd@0: %
wolffd@0: %  h = som_plotplane(topol, data)
wolffd@0: %  h = som_plotplane(lattice, msize, data)
wolffd@0: %  h = som_plotplane(..., color)
wolffd@0: %  h = som_plotplane(..., color, scaling)
wolffd@0: %  h = som_plotplane(..., color, scaling, pos)
wolffd@0: %
wolffd@0: % DESCRIPTION
wolffd@0: %
wolffd@0: %  Visualizes the map prototype vectors as line graph
wolffd@0: %
wolffd@0: % KNOWN BUGS
wolffd@0: %
wolffd@0: %  It is not possible to specify explicit coordinates for map
wolffd@0: %  consistig of just one unit as then the msize is interpreted as
wolffd@0: %  map size.
wolffd@0: %
wolffd@0: % FEATURES
wolffd@0: %
wolffd@0: %  - the colors are fixed: changing colormap in the figure (see
wolffd@0: %    COLORMAP) will not affect the coloring of the plots
wolffd@0: %
wolffd@0: % REQUIRED INPUT ARGUMENTS
wolffd@0: % 
wolffd@0: % lattice  The basic topology
wolffd@0: %
wolffd@0: %   (string) 'hexa' or 'rect' positions the plots according to hexagonal or 
wolffd@0: %            rectangular map lattice.
wolffd@0: %
wolffd@0: % msize    The size of the map grid     
wolffd@0: %         
wolffd@0: %   (vector) [n1 n2] vector defines the map size (height n1 units, width n2 
wolffd@0: %            units, total M=n1 x n2 units). The units will be placed to their 
wolffd@0: %            topological locations in order to form a uniform hexagonal or 
wolffd@0: %            rectangular grid.   
wolffd@0: %   (matrix) Mx2 matrix defines arbitary coordinates for the M units.
wolffd@0: %            In this case the argument 'lattice' has no effect.
wolffd@0: % 
wolffd@0: % topol    Topology of the map grid
wolffd@0: %
wolffd@0: %   (struct) map or topology struct from which the topology is taken
wolffd@0: % 
wolffd@0: % data     The data to be visualized
wolffd@0: %
wolffd@0: %   (matrix) Mxd matrix of data vectors. 
wolffd@0: % 
wolffd@0: % OPTIONAL INPUT ARGUMENTS
wolffd@0: %
wolffd@0: % If unspecified or given empty values ('' or []), default values
wolffd@0: % will be used for optional input arguments.
wolffd@0: % 
wolffd@0: % color    The color of the plots
wolffd@0: %
wolffd@0: %    (string) Matlab's ColorSpec (see help plot) string gives the same color 
wolffd@0: %             for each line.
wolffd@0: %
wolffd@0: %    (matrix) Mx3 matrix assigns an RGB color determined by the Nth row of
wolffd@0: %             the matrix to the Nth plot. 
wolffd@0: %
wolffd@0: %    (vector) 1x3 RGB vector gives the same color for each line.
wolffd@0: %
wolffd@0: % scaling  The data scaling mode
wolffd@0: %
wolffd@0: %    (string) 'on or 'off': if scaling is set on, the data will be
wolffd@0: %             linearly scaled in each unit so that min and max values span from 
wolffd@0: %             lower to upper edge in each unit. If scaling is 'off', the proper 
wolffd@0: %             scaling is left to the user: values in range [-.5,.5] will be plotted 
wolffd@0: %             within the limits of the unit while values exceeding this
wolffd@0: %             range will be out of the unit.
wolffd@0: %
wolffd@0: % pos      Position of the origin          
wolffd@0: %
wolffd@0: %    (vector) This is meant for drawing the plane in arbitary location in a 
wolffd@0: %             figure. Note the operation: if this argument is given, the
wolffd@0: %             axis limits setting part in the routine is skipped and the limits
wolffd@0: %             setting will be left to be done by MATLAB's
wolffd@0: %             defaults. By default no translation is done.
wolffd@0: %
wolffd@0: % OUTPUT ARGUMENTS
wolffd@0: %
wolffd@0: %  h (scalar)  Handle to the created patch object
wolffd@0: %
wolffd@0: % OBJECT TAG     
wolffd@0: %
wolffd@0: % Object property 'Tag' is set to 'planePlot'.       
wolffd@0: %
wolffd@0: % EXAMPLES
wolffd@0: %
wolffd@0: % %%% Create the data and make a map 
wolffd@0: %    
wolffd@0: % data=rand(1000,20); map=som_make(data);
wolffd@0: % 
wolffd@0: % %%% Create a 'gray' colormap that has 64 levels
wolffd@0: %    
wolffd@0: % color_map=gray(64);
wolffd@0: % 
wolffd@0: % %%% Draw plots using red color
wolffd@0: %    
wolffd@0: % som_plotplane(map, map.codebook,'r');
wolffd@0: %
wolffd@0: % %%% Calculate hits on the map and calculate colors so that
wolffd@0: %     black = min. number of hits and white = max. number of hits
wolffd@0: %
wolffd@0: % hit=som_hits(map,data); color=som_normcolor(hit(:),color_map);
wolffd@0: %
wolffd@0: % %%% Draw plots again. Now the gray level indicates the number of hits to 
wolffd@0: %     each node
wolffd@0: %
wolffd@0: % som_plotplane(map, map.codebook, color);
wolffd@0: %
wolffd@0: % SEE ALSO  
wolffd@0: %
wolffd@0: % som_cplane     Visualize a 2D component plane, u-matrix or color plane
wolffd@0: % som_barplane   Visualize the map prototype vectors as bar diagrams.
wolffd@0: % som_pieplane   Visualize the map prototype vectors as pie charts
wolffd@0: 
wolffd@0: % Copyright (c) 1999-2000 by the SOM toolbox programming team.
wolffd@0: % http://www.cis.hut.fi/projects/somtoolbox/             
wolffd@0: 
wolffd@0: % Version 2.0beta Johan 160799 juuso 151199 070600
wolffd@0: 
wolffd@0: %%% Init & Check arguments %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
wolffd@0: 
wolffd@0: [nargin, lattice, msize, data, color, scaling, pos] = vis_planeGetArgs(varargin{:});
wolffd@0: error(nargchk(3, 5, nargin));  % check no. of input args is correct
wolffd@0: 
wolffd@0: s=0.8; % size of plot
wolffd@0: 
wolffd@0: if nargin < 6 | isempty(pos)
wolffd@0:   pos=NaN; 
wolffd@0: end
wolffd@0: 
wolffd@0: if nargin < 5 | isempty(scaling)
wolffd@0:   scaling='on'; 
wolffd@0: elseif ~vis_valuetype(scaling,{'string'}) | ...
wolffd@0:       ~any(strcmp(scaling,{'on','off'})),
wolffd@0:   error('Scaling should be string ''on'' or ''off''.');
wolffd@0: end
wolffd@0: 
wolffd@0: l=size(data,2);
wolffd@0: 
wolffd@0: if ~isnumeric(msize) | ndims(msize) ~= 2 | size(msize,2)~=2, 
wolffd@0:   error('msize has to be 1x2 grid size vector or a Nx2 coordinate matrix.');
wolffd@0: elseif size(msize,1) == 1,
wolffd@0:    xdim=msize(2);
wolffd@0:    ydim=msize(1);
wolffd@0:    N=xdim*ydim;
wolffd@0:    y=repmat(repmat([1:ydim]',xdim,1),1,l);
wolffd@0:    x=reshape(repmat([1:xdim],ydim*l,1),l,N)';
wolffd@0: else
wolffd@0:    x=repmat(msize(:,1),1,l);y=repmat(msize(:,2),1,l);
wolffd@0:    N=size(msize,1);
wolffd@0:    lattice='rect'; 
wolffd@0:    if isnan(pos),
wolffd@0:       pos=[0 0];
wolffd@0:    end
wolffd@0: end
wolffd@0: 
wolffd@0: switch lattice
wolffd@0: case {'hexa', 'rect'}
wolffd@0:   ;
wolffd@0: otherwise
wolffd@0:   error(['Lattice' lattice ' not implemented!']);
wolffd@0: end  
wolffd@0: 
wolffd@0: if ~isnumeric(data) | size(data,1) ~= N
wolffd@0:   error('Data matrix is invalid or has wrong size!');
wolffd@0: end
wolffd@0: 
wolffd@0: if nargin < 4 | isempty(color),
wolffd@0:   color='k';
wolffd@0: elseif vis_valuetype(color, {'colorstyle',[N 3]}),
wolffd@0:   if ischar(color) & strcmp(color,'none'),
wolffd@0:     error('Colorstyle ''none'' not allowed in som_plotplane.');
wolffd@0:   end
wolffd@0: elseif vis_valuetype(color,{'1x3rgb'})
wolffd@0:   ;
wolffd@0: elseif ~vis_valuetype(color,{'nx3rgb',[N 3]},'all'), 
wolffd@0:   error('The color matrix has wrong size or contains invalid RGB values or colorstyle.');
wolffd@0: end
wolffd@0: 
wolffd@0: [linesx, linesy]=vis_line(data,scaling);
wolffd@0: 
wolffd@0: %%%% Action %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
wolffd@0: 
wolffd@0: % Making the lattice.
wolffd@0: % Command view([0 90]) shows the map in 2D properly oriented
wolffd@0: 
wolffd@0: switch lattice
wolffd@0: case 'hexa'
wolffd@0:   t=find(rem(y(:,1),2));                  % move even rows by .5
wolffd@0:   x(t,:)=x(t,:)-.5; 
wolffd@0:   x=(x./s+linesx).*s+.5; y=(y./s+linesy).*s;      % scale with s
wolffd@0: case 'rect' 
wolffd@0:   x=(x./s+linesx).*s; y=(y./s+linesy).*s;         % scale with s
wolffd@0: end
wolffd@0: 
wolffd@0: %% Draw the map! ...
wolffd@0: 
wolffd@0: h_=plot(x',y');
wolffd@0: 
wolffd@0: if size(color,1) == 1
wolffd@0:   set(h_,'Color',color);
wolffd@0: else
wolffd@0:   for i=1:N,
wolffd@0:     set(h_(i,:),'Color',color(i,:));
wolffd@0:   end
wolffd@0: end
wolffd@0: 
wolffd@0: if ~isnan(pos)
wolffd@0:   x=x+pos(1);y=y+pos(2);                    % move upper left corner 
wolffd@0: end                                         % to pos(1),pos(2)
wolffd@0: 
wolffd@0: %% Set axes properties  
wolffd@0: 
wolffd@0: ax=gca;           
wolffd@0: vis_PlaneAxisProperties(ax, lattice, msize, pos);
wolffd@0: 
wolffd@0: %%% Build output %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
wolffd@0: 
wolffd@0: set(h_,'Tag','planePlot');                % tag the lineobject 
wolffd@0: 
wolffd@0: if nargout>0, h=h_; end                   % Set h only, 
wolffd@0:                                           % if there really is output
wolffd@0:                                           
wolffd@0: %% Subfuntion %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
wolffd@0:                                           
wolffd@0: function [x,y]=vis_line(data, scaling)
wolffd@0: 
wolffd@0: s=size(data);
wolffd@0: % normalization between [0,1] if scaling is on
wolffd@0: if strcmp(scaling,'on')
wolffd@0:   mn=repmat(min(data,[],2),1,s(2));  
wolffd@0:   mx=repmat(max(data,[],2),1,s(2));
wolffd@0:   y=-((data-mn)./(mx-mn))+.5;        
wolffd@0: else                       % -sign is beacuse we do axis ij
wolffd@0:   y=-data;
wolffd@0: end
wolffd@0: 
wolffd@0: x=repmat(linspace(-.5, .5, size(data,2)), size(data,1),1);