wolffd@0: function h=som_pieplane(varargin)
wolffd@0: 
wolffd@0: %SOM_PIEPLANE Visualize the map prototype vectors as pie charts
wolffd@0: %
wolffd@0: % h=som_pieplane(lattice, msize, data, [color], [s], [pos])
wolffd@0: % h=som_pieplane(topol, data, [color], [s], [pos])
wolffd@0: %
wolffd@0: %  som_pieplane('hexa',[5 5], rand(25,4), jet(4), rand(25,1)) 
wolffd@0: %  som_pieplane(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, M=msize(1)*msize(2)
wolffd@0: %            (matrix) size Mx2, gives explicit coordinates for each node: in 
wolffd@0: %             this case the lattice does not matter.
wolffd@0: %  topol     (struct) map or topology struct
wolffd@0: %  data      (matrix) size Mxd, Mth row is the data for Mth pie. The 
wolffd@0: %             values will be normalized to have unit sum in each row.
wolffd@0: %  [color]   (matrix) size dx3, RGB triples. The first row is the
wolffd@0: %             color of the first slice in each pie etc. Default is hsv(d).
wolffd@0: %            (string) ColorSpec or 'none' gives the same color for each slice.
wolffd@0: %  [s]       (matrix) size Mx1,  gives an individual size scaling for each node. 
wolffd@0: %            (scalar) gives the same size for each node. Default is 0.8. 
wolffd@0: %  [pos]     (vectors) a 1x2 vector that determines position for the
wolffd@0: %              origin, i.e. upper left corner. Default is no translation.
wolffd@0: %
wolffd@0: %  h         (scalar) the object handle to the PATCH object
wolffd@0: %
wolffd@0: % The data will be linearly scaled so that its sum is 1 in each unit.
wolffd@0: % Negative values are invalid. Axis are set as in som_cplane.
wolffd@0: %
wolffd@0: % For more help, try 'type som_pieplane' or check out online documentation.
wolffd@0: % See also SOM_CPLANE, SOM_PLOTPLANE, SOM_BARPLANE
wolffd@0: 
wolffd@0: %%%%%%%%%%%%% DETAILED DESCRIPTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
wolffd@0: %
wolffd@0: % som_pieplane
wolffd@0: %
wolffd@0: % PURPOSE
wolffd@0: % 
wolffd@0: % Visualizes the map prototype vectors as pie charts.
wolffd@0: %
wolffd@0: % SYNTAX
wolffd@0: %
wolffd@0: %  h = som_pieplane(topol, data)
wolffd@0: %  h = som_pieplane(lattice, msize, data)
wolffd@0: %  h = som_pieplane(..., color)
wolffd@0: %  h = som_pieplane(..., color, s)
wolffd@0: %  h = som_pieplane(..., color, s, pos)
wolffd@0: %
wolffd@0: % DESCRIPTION
wolffd@0: %
wolffd@0: %  Visualizes the map prototype vectors as pie charts.
wolffd@0: %
wolffd@0: % KNOWN BUGS
wolffd@0: %
wolffd@0: % It is not possible to specify explicit coordinates for map
wolffd@0: % consisting of just one unit as then the msize is interpreted as
wolffd@0: % map size.
wolffd@0: %
wolffd@0: %  FEATURES
wolffd@0: % 
wolffd@0: %  - negative values in data cause an error
wolffd@0: %
wolffd@0: %  - the colors are fixed: changing colormap in the figure (see help
wolffd@0: %    colormap) will not affect the coloring of the slices.
wolffd@0: %
wolffd@0: %  - if input variable s has size Nxd it gives each slice an individual
wolffd@0: %    scaling factor. This may be used to create a glyph where
wolffd@0: %    the radius of the slice, not the angle, shows the variable
wolffd@0: %    try, e.g., som_pieplane('rect',[5 4],ones(20,4),'w',rand(20,4));
wolffd@0: %
wolffd@0: % REQUIRED INPUT ARGUMENTS
wolffd@0: % 
wolffd@0: % lattice  The basic shape of the map units 
wolffd@0: %         
wolffd@0: %    (string) 'hexa' or 'rect' positions the pies 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,
wolffd@0: %             width n2 units, total M=n1xn2 units). The units will 
wolffd@0: %             be placed to their topological locations to form a
wolffd@0: %             uniform hexagonal or rectangular grid.
wolffd@0: %    (matrix) Mx2 matrix defines arbitary coordinates for the M units. In 
wolffd@0: %             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. Negative values are invalid.
wolffd@0: %
wolffd@0: % OPTIONAL INPUT ARGUMENTS
wolffd@0: %
wolffd@0: % If value is unspecified or empty ([] or ''), the default values
wolffd@0: % are used for optional input arguments.
wolffd@0: %
wolffd@0: % s       The size scaling factors for the units
wolffd@0: %
wolffd@0: %    (scalar) gives each unit the same size scaling: 
wolffd@0: %             0   unit disappears (edges can be seen as a dot)
wolffd@0: %             ... default size is 0.8
wolffd@0: %             >1  unit overlaps others          
wolffd@0: %    (matrix) Mx1 double: each unit gets individual size scaling 
wolffd@0: %
wolffd@0: % color   The color of the slices in each pie
wolffd@0: %
wolffd@0: %    (string) ColorSpec or 'none' gives the same color for each slice
wolffd@0: %    (matrix) dx3 matrix assigns an RGB color determined by the dth row of
wolffd@0: %             the matrix to the dth slice (variable) in each pie plot
wolffd@0: %
wolffd@0: % pos    Position of origin       
wolffd@0: % 
wolffd@0: %    (vector) size 1x2: this is meant for drawing the plane in arbitary 
wolffd@0: %             location in a figure. Note the operation: if this argument is
wolffd@0: %             given, the axis limits setting part in the routine is skipped and 
wolffd@0: %             the limits setting will be left to be done by
wolffd@0: %             MATLAB's defaults. Default is no translation.
wolffd@0: %
wolffd@0: % OUTPUT ARGUMENTS
wolffd@0: %
wolffd@0: %  h (scalar)  Handle to the created patch object.
wolffd@0: %
wolffd@0: % OBJECT TAGS     
wolffd@0: %
wolffd@0: % One object handle is returned: field Tag is set to 'planePie'       
wolffd@0: % 
wolffd@0: % EXAMPLES
wolffd@0: %
wolffd@0: % %%% Create the data and make a map 
wolffd@0: %    
wolffd@0: % data=rand(100,5); map=som_make(data);
wolffd@0: % 
wolffd@0: % %%% Create a 'jet' colormap that has as many rows as the data has variables
wolffd@0: %    
wolffd@0: % colors=jet(5);
wolffd@0: % 
wolffd@0: % %%% Draw pies
wolffd@0: %    
wolffd@0: % som_pieplane(map, map.codebook, colors);
wolffd@0: % 
wolffd@0: % %%% Calculate the hits of data on the map and normalize them between [0,1]
wolffd@0: %  
wolffd@0: % hit=som_hits(map,data); hit=hit./max(max(hit));
wolffd@0: % 
wolffd@0: % %%% Draw the pies so that their size tells the hit count
wolffd@0: %
wolffd@0: % som_pieplane(map, map.codebook, colors, hit);
wolffd@0: % 
wolffd@0: % %%% Try this! (see section FEATURES) 
wolffd@0: %
wolffd@0: % som_pieplane('rect',[5 4],ones(20,4),'w',rand(20,4));
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_plotplane  Visualize the map prototype vectors as line graphs
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 140799 juuso 310300 070600
wolffd@0: 
wolffd@0: %%% Check & Init arguments %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
wolffd@0: 
wolffd@0: [nargin, lattice, msize, data, color, s, pos] = vis_planeGetArgs(varargin{:});
wolffd@0: error(nargchk(3, 6, nargin));  % check no. of input args is correct
wolffd@0: 
wolffd@0: % check pos
wolffd@0: 
wolffd@0: if nargin < 6 | isempty(pos)
wolffd@0:   pos=NaN;                            % default value for pos (no translation) 
wolffd@0: elseif ~vis_valuetype(pos,{'1x2'})
wolffd@0:   error('Position of origin has to be given as an 1x2 vector');
wolffd@0: end
wolffd@0: 
wolffd@0: % check msize
wolffd@0: 
wolffd@0: if ~vis_valuetype(msize,{'1x2','nx2'}),
wolffd@0:   error('msize has to be 1x2 grid size vector or a Nx2 coordinate matrix.');
wolffd@0: end
wolffd@0: 
wolffd@0: % check data
wolffd@0: 
wolffd@0: if ~isnumeric(data),
wolffd@0:   error('Data matrix must be numeric.');
wolffd@0: elseif length(size((data)))>2
wolffd@0:   error('Data matrix has too many dimensions!');
wolffd@0: else
wolffd@0:   d=size(data,2);
wolffd@0:   N=size(data,1);
wolffd@0: end
wolffd@0: 
wolffd@0: if any(data(:)<0)
wolffd@0:   error('Negative data values not allowed in pie plots!');
wolffd@0: end
wolffd@0: 
wolffd@0: % Check lattice
wolffd@0: if ~ischar(lattice) | ~any(strcmp(lattice,{'hexa','rect'})),
wolffd@0:   error('Invalid lattice.');
wolffd@0: end
wolffd@0: 
wolffd@0: %% Calculate patch coordinates for slices
wolffd@0: 
wolffd@0: for i=1:N,                            
wolffd@0:   [nx,ny]=vis_piepatch(data(i,:));    
wolffd@0:   piesx(:,(1+(i-1)*d):(i*d))=nx;
wolffd@0:   piesy(:,(1+(i-1)*d):(i*d))=ny;
wolffd@0: end
wolffd@0: l=size(piesx,1);
wolffd@0: 
wolffd@0: if size(msize,1) == 1,
wolffd@0:   if prod(msize) ~= N 
wolffd@0:     error('Data matrix has wrong size.');
wolffd@0:   else
wolffd@0:     coord=som_vis_coords(lattice, msize);
wolffd@0:   end
wolffd@0: else
wolffd@0:   if N ~= size(msize,1),
wolffd@0:     error('Data matrix has wrong size.');
wolffd@0:   end
wolffd@0:   coord=msize; 
wolffd@0:   % This turns the axis tightening off,
wolffd@0:   % as now we don't now the limits (no fixed grid)
wolffd@0:   if isnan(pos); pos=[0 0]; end
wolffd@0: end
wolffd@0: x=reshape(repmat(coord(:,1),1,l*d)',l,d*N);
wolffd@0: y=reshape(repmat(coord(:,2),1,l*d)',l,d*N);
wolffd@0: 
wolffd@0: % Check size
wolffd@0: 
wolffd@0: if nargin < 5 | isempty(s),  
wolffd@0:   s=0.8;                              % default value for scaling
wolffd@0: elseif ~vis_valuetype(s, {'1x1', [N 1], [N d]}),
wolffd@0:   error('Size matrix does not match with the data matrix.');
wolffd@0: elseif size(s) == [N 1],
wolffd@0:   s=reshape(repmat(s,1,l*d)',l,d*N);
wolffd@0: elseif all(size(s) ~= [1 1]),
wolffd@0:   s=reshape(repmat(reshape(s',d*N,1),1,l)',l,d*N);
wolffd@0: end
wolffd@0: 
wolffd@0: % Check color
wolffd@0: % C_FLAG is a flag for color 'none' 
wolffd@0: 
wolffd@0: if nargin < 4 | isempty(color)
wolffd@0:   color=hsv(d); C_FLAG=0;       % default n hsv colors
wolffd@0: end
wolffd@0: 
wolffd@0: if ~(vis_valuetype(color, {[d 3], 'nx3rgb'},'all')) & ...
wolffd@0:       ~vis_valuetype(color,{'colorstyle','1x3rgb'}), 
wolffd@0:   error('The color matrix has wrong size or contains invalid values.');
wolffd@0: elseif ischar(color) & strcmp(color,'none'), 
wolffd@0:   C_FLAG=1;        % check for color 'none'
wolffd@0:   color='w';    
wolffd@0: else
wolffd@0:   C_FLAG=0;        % valid color string or colormap
wolffd@0: end
wolffd@0: 
wolffd@0: %% Action %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
wolffd@0: 
wolffd@0: % Size zero would cause division by zero. eps is as good (node disappears)
wolffd@0: % The edge may be visible, though. (NaN causes some other problems)
wolffd@0: 
wolffd@0: s(s==0)=eps;                    
wolffd@0: 
wolffd@0: %% 1. Scaling
wolffd@0: x=(x./s+piesx).*s; y=(y./s+piesy).*s;      
wolffd@0: 
wolffd@0: %% 2. Translation  
wolffd@0: if ~isnan(pos)
wolffd@0:   x=x+pos(1);y=y+pos(2);               
wolffd@0: end
wolffd@0: 
wolffd@0: %% 3. Rearrange dx3 color matrix
wolffd@0: 
wolffd@0: if ~isstr(color) & size(color,1)~=1,
wolffd@0:   color=reshape(repmat(color,N,1),[1 N*d 3]);
wolffd@0: end
wolffd@0: 
wolffd@0: %% Set axes properties  
wolffd@0: ax=newplot;                            % get current axis
wolffd@0: vis_PlaneAxisProperties(ax,lattice, msize, pos);                         
wolffd@0: 
wolffd@0: %% Draw the plane! 
wolffd@0: 
wolffd@0: h_=patch(x,y,color);
wolffd@0: 
wolffd@0: if C_FLAG
wolffd@0:   set(h_,'FaceColor','none');
wolffd@0: end
wolffd@0: 
wolffd@0: set(h_,'Tag','planePie');              % tag the object 
wolffd@0: 
wolffd@0: %%% Build output %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
wolffd@0: 
wolffd@0: if nargout>0, h=h_; end                % Set h only if 
wolffd@0:                                        % there really is output
wolffd@0: %%% Subfunctions %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
wolffd@0: 
wolffd@0: function [x,y]=vis_piepatch(v)
wolffd@0: 
wolffd@0: % Do a pie (see e.g. the MathWorks function PIE). 
wolffd@0: % Origin is at (0,0) and the radius is .5.
wolffd@0: 
wolffd@0: N=25;
wolffd@0: 
wolffd@0: if sum(v)==0, v_is_zero = 1; v(1) = 1; else v_is_zero = 0; end
wolffd@0: 
wolffd@0: v(v==0) = eps; % Matlab 5.2 version of linspace doesn't work otherwise
wolffd@0: 
wolffd@0: phi=[0 2*pi*cumsum(v./sum(v))];
wolffd@0: 
wolffd@0: for i=2:length(phi),
wolffd@0:   [xi,yi]=pol2cart(linspace(phi(i-1),phi(i),N),0.5);
wolffd@0:   x(:,i-1)=[0 xi 0]';
wolffd@0:   y(:,i-1)=[0 yi 0]';
wolffd@0: end
wolffd@0: 
wolffd@0: if v_is_zero, x = x*0; y = y*0; end
wolffd@0: