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