Daniel@0: function h=som_show(sMap, varargin)
Daniel@0: 
Daniel@0: % SOM_SHOW Basic SOM visualizations: component planes, u-matrix etc.
Daniel@0: %
Daniel@0: % h = som_show(sMap, ['argID', value, ...])
Daniel@0: % 
Daniel@0: %  som_show(sMap);
Daniel@0: %  som_show(sMap,'bar','none');
Daniel@0: %  som_show(sMap,'comp',[1:3],'umat','all');
Daniel@0: %  som_show(sMap,'comp',[1 2],'umat',{[1 2],'1,2 only'},'comp',[3:6]);   
Daniel@0: %  som_show(sMap,'size',m,'bar','vert','edge','off');
Daniel@0: %
Daniel@0: % Input and output arguments ([]'s are optional):
Daniel@0: %  sMap        (struct) map struct
Daniel@0: %  [argID,     (string) Additional parameters are given as argID, value
Daniel@0: %    value]    (varies) pairs. See below for list of valid IDs and values.
Daniel@0: %
Daniel@0: %  h           (struct) struct with the following fields:
Daniel@0: %   .plane     (vector) handles to the axes objecets (subplots)
Daniel@0: %   .colorbar  (vector) handles to the colorbars. Colorbars for empty
Daniel@0: %                       grids & RGB color planes do not exist: the
Daniel@0: %                       value for them in the vector is -1.
Daniel@0: %   .label     (vector) handles to the axis labels
Daniel@0: %
Daniel@0: % Here are the valid argument IDs and corresponding values. M is
Daniel@0: % the number of map units
Daniel@0: %  'comp'               Which component planes to draw, title is
Daniel@0: %                       the name of the component (from sMap.comp_names) 
Daniel@0: %              (vector) a vector of component indices
Daniel@0: %              (string) 'all' (or '' or []) for all components
Daniel@0: %  'compi'              as 'comp' but uses interpolated shading
Daniel@0: %  'umat'               Show u-matrix calculated using specified 
Daniel@0: %                       components 
Daniel@0: %              (vector) a vector of component indeces
Daniel@0: %              (string) 'all' (or '' or []) to use all components
Daniel@0: %              (cell)   of form {v, str} uses v as the vector, and put
Daniel@0: %                       str as title instead of the default 'U-matrix'
Daniel@0: %  'umati'              as 'umat' but uses interpolated shading of colors 
Daniel@0: %  'empty'     (string) Make an empty plane using given string as title
Daniel@0: %  'color'              Set arbitrary unit colors explicitly  
Daniel@0: %              (matrix) size Mx1 or Mx3, Mx1 matrix uses indexed
Daniel@0: %                       coloring;  Mx3 matrix (RGB triples as rows)
Daniel@0: %                       defines fixed unit colors
Daniel@0: %              (cell)   of from {color, str}. 'color' is the Mx1
Daniel@0: %                       or Mx3 RGB triple matrix and 'str' is title 
Daniel@0: %                       string
Daniel@0: %  'colori'             as 'color' but uses interpolated shading of colors 
Daniel@0: %  'norm'      (string) 'n' or 'd': Whether to show normalized 'n' or 
Daniel@0: %                       denormalized 'd' data values on the
Daniel@0: %                       colorbar. By default denormalized values are used.
Daniel@0: %  'bar'       (string) Colorbar direction: 'horiz', 'vert' (default)
Daniel@0: %                       or 'none'
Daniel@0: %  'size'               size of the units
Daniel@0: %              (scalar) same size for each unit, default is 1
Daniel@0: %              (vector) size Mx1, individual size for each unit
Daniel@0: %  'edge'      (string) Unit edges on component planes 'on'
Daniel@0: %                       (default) or 'off'
Daniel@0: %  'footnote'  (string) Footnote string, sMap.name by default
Daniel@0: %  'colormap'  (matrix) user defined colormap 
Daniel@0: %  'subplots'  (vector) size 1 x 2, the number of subplots in y- and
Daniel@0: %                       and x-directions (as in SUBPLOT command)
Daniel@0: %
Daniel@0: % If identifiers 'comp', 'compi', 'umat', 'umati', 'color', 'colori'
Daniel@0: % or 'empty' are not specified at all, e.g. som_show(sMap) or
Daniel@0: % som_show(sMap,'bar','none'), the U-matrix and all component planes
Daniel@0: % are shown.
Daniel@0: %
Daniel@0: % For more help, try 'type som_show' or check out online documentation. 
Daniel@0: % See also SOM_SHOW_ADD, SOM_SHOW_CLEAR, SOM_UMAT, SOM_CPLANE, SOM_GRID.
Daniel@0: 
Daniel@0: %%%%%%%%%%%% DETAILED DESCRIPTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Daniel@0: %
Daniel@0: % som_show
Daniel@0: %
Daniel@0: % PURPOSE 
Daniel@0: %
Daniel@0: % Shows basic visualizations of SOM: component planes, unified distance
Daniel@0: % matrices as well as empty planes and fixed color planes.
Daniel@0: %
Daniel@0: % SYNTAX
Daniel@0: %
Daniel@0: %  h = som_show(sMap)
Daniel@0: %  h = som_show(sMap, 'argID', value, ...)
Daniel@0: %
Daniel@0: % DESCRIPTION 
Daniel@0: %
Daniel@0: % This function is used for basic visualization of the SOM. Four
Daniel@0: % kinds of SOM planes can be shown: 
Daniel@0: %
Daniel@0: %  1. U-matrix (see SOM_UMAT) which shows clustering structure of
Daniel@0: %     the SOM. Either all or just part of the components can 
Daniel@0: %     be used in calculating the U-matrix.
Daniel@0: %  2. component planes: each component plane shows the values of
Daniel@0: %     one variable in each map unit
Daniel@0: %  3. an empty plane which may be used as a base for, e.g., hit 
Daniel@0: %     histogram visualization or labeling (see SOM_SHOW_ADD)
Daniel@0: %  4. a fixed or indexed color representation for showing color coding or 
Daniel@0: %     clustering
Daniel@0: %
Daniel@0: % The component planes and u-matrices may have colorbars showing the
Daniel@0: % scale for the variable. The scale shows by default the values that
Daniel@0: % variables have in the map struct. It may be changed to show the
Daniel@0: % original data values (estimated by SOM_DENORMALIZE). In this case a
Daniel@0: % small 'd' appears below the colorbar. The orientation of these
Daniel@0: % colorbars may be changed, or they can be removed.
Daniel@0: %
Daniel@0: % By default the u-matrix - calculated using all variables - and all
Daniel@0: % component planes are shown. This is achieved by giving command
Daniel@0: % som_show(sMap) without any further arguments
Daniel@0: %
Daniel@0: % REQUIRED INPUT ARGUMENTS
Daniel@0: %
Daniel@0: % sMap  (struct) Map to be shown. If only this argument is
Daniel@0: %                specified, the function draws first the u-matrix 
Daniel@0: %                calculated using all the variables followed by all
Daniel@0: %                the component planes.
Daniel@0: %
Daniel@0: % OPTIONAL INPUT ARGUMENTS
Daniel@0: % 
Daniel@0: % (M is the number of map units)
Daniel@0: %
Daniel@0: % Optional arguments must be given as 'argID',value -pairs
Daniel@0: % 
Daniel@0: % 'comp'      Defines the variabels to be shown as component planes.
Daniel@0: %    (vector) 1xN or Nx1 vector with integer positive numbers ranging 
Daniel@0: %             from 1 to the number of variables in the map codebook
Daniel@0: %             (dim). This vector determines the variables to be show
Daniel@0: %             as component planes and their order. Note that the same
Daniel@0: %             component plane (the same variable index) is allowed to
Daniel@0: %             occur several times.
Daniel@0: %    (string) 'all' or '' or []. This uses all variables, that is, it's
Daniel@0: %             the same that using value [1:dim] where dim is the
Daniel@0: %             number of variables in the codebook.
Daniel@0: %       
Daniel@0: % 'compi'     Same as 'comp' but uses a Gouraud shaded color plane 
Daniel@0: %             (made using SOM_GRID function) instead of the cell-like
Daniel@0: %             visualization of 'comp' (made using SOM_CPLANE). Note
Daniel@0: %             that the color interpolation doesn't work strictly
Daniel@0: %             correctly on 'hexa' grid, as it uses rectangular grid
Daniel@0: %             (see SURF).
Daniel@0: % 
Daniel@0: % 'umat'      Show U-matrix: value defines the variables to be used
Daniel@0: %             for calculating a u-matrix.
Daniel@0: %    (vector) as in 'comps'. However, multiple occurences of the
Daniel@0: %             same variable (same variable index) are ignored. 
Daniel@0: %    (string) 'all' or '' or []. This uses all variables, that is, 
Daniel@0: %             is the same as using value [1:dim] where dim is the
Daniel@0: %             number of variables in the codebook. 
Daniel@0: %    (cell)   of form {v, str} where v is a valid index vector for 'umat' 
Daniel@0: %             (see above) and str is a string that is used as a title 
Daniel@0: %             for the u-matrix instead of the default title
Daniel@0: %             'U-matrix'. This may be useful if several u-matrices
Daniel@0: %             are shown in the same figure. 
Daniel@0: % 
Daniel@0: % 'umati'     Same as 'umat' but uses shaded color plane (see 'compi').
Daniel@0: %
Daniel@0: % 'empty'     Show an empty plane (patch edges only)
Daniel@0: %    (string) value is used as title
Daniel@0: % 
Daniel@0: % 'color'     Define fixed RGB colors for the map units
Daniel@0: %    (matrix) a Mx3 matrix of RGB triples as rows             
Daniel@0: %    (vector) a Mx1 vector of any values: sets indexed coloring using
Daniel@0: %             the current colormap (as SURF does)  
Daniel@0: %    (matrix) a Mx3xN matrix of RGB triples as rows. This gives N
Daniel@0: %             color planes.
Daniel@0: %    (matrix) a Mx1xN matrix of any values: sets indexed coloring using
Daniel@0: %             the current colormap (as SURF does). This gives N
Daniel@0: %             color planes.
Daniel@0: %    (cell)   of form {rgb, str} where rgb is a Mx3 (xN) matrix of RGB
Daniel@0: %             triples as rows and str is a string that is used as
Daniel@0: %             title(s).  
Daniel@0: %    (cell)   of form {v, str} where v is a Mx1(xN) matrix of values
Daniel@0: %             and str is a string that is used as title(s). 
Daniel@0: %
Daniel@0: % 'colori'    Same as 'color' but uses shaded color plane (see 'compi').
Daniel@0: %
Daniel@0: % 'norm'      Defines whether to use normalized or denormalized
Daniel@0: %             values in the colorbar. If denormalized values are
Daniel@0: %             used, they are acquired from SOM_DENORMALIZE function 
Daniel@0: %             using sMap.comp_norm field.
Daniel@0: %    (string) 'd' (default) for denormalized values and 'n' for
Daniel@0: %             normalized values. The corresponding letter appears
Daniel@0: %             below the colorbar.
Daniel@0: %   
Daniel@0: % 'bar'       Define the direction of the colorbars for component planes 
Daniel@0: %             and U-matrices or turn them completely off.
Daniel@0: %    (string) 'vert' (default), 'horiz' or 'none'. 'vert' gives
Daniel@0: %             vertical and 'horiz' horizontal colorbars. 'none'
Daniel@0: %             shows no colorbars at all. 
Daniel@0: %
Daniel@0: % 'size'      Define sizes of the units. 
Daniel@0: %    (scalar) all units have the same size (1 by default)
Daniel@0: %    (vector) size Mx1, each unit gets individual size scaling 
Daniel@0: %             (as in SOM_CPLANE)
Daniel@0: %
Daniel@0: % 'edge'      Unit edges on component plane visualizations.
Daniel@0: %    (string) 'on' or 'off' determines whether the unit edges on component 
Daniel@0: %             planes ('comp') are shown or not. Default is 'off'. Note that
Daniel@0: %             U-matrix and color planes are _always_ drawn without edges.
Daniel@0: %
Daniel@0: % 'footnote'  Text on the figure
Daniel@0: %    (string) is printed as a movable text object on the figure
Daniel@0: %             where it may be moved using mouse. Default value is the
Daniel@0: %             string in the sMap.name field. Note: value [] gives the
Daniel@0: %             string, but input value '' gives no footnote a all. 
Daniel@0: %             See VIS_FOOTNOTE for more information on the text object 
Daniel@0: %             and ways to change its font size.
Daniel@0: % 
Daniel@0: % 'colormap'  som_show ghages the colormap by default to a gray-level map
Daniel@0: %    (matrix) This argument is used to set some other colormap. 
Daniel@0: %
Daniel@0: % 'subplots'  the number of subplots in y- and x-directions, as in 
Daniel@0: %    (vector) command SUBPLOT
Daniel@0: % 
Daniel@0: % OUTPUT ARGUMENTS
Daniel@0: %
Daniel@0: % h (struct)
Daniel@0: %    .plane         (vector) handles to the axes objects (subplots)
Daniel@0: %    .colorbar      (vector) handles to the colorbars. Colorbars of empty
Daniel@0: %                            & color planes do not exist: the corresponding
Daniel@0: %                            value in the vector is -1
Daniel@0: %    .label         (vector) handles to the axis labels
Daniel@0: %
Daniel@0: % OBJECT TAGS
Daniel@0: %
Daniel@0: % The property field 'Tag' of the axis objects created by this function 
Daniel@0: % are set to contain string 'Cplane' if the axis contains component plane
Daniel@0: % ('comp'), color plane ('color') or empty plane ('empty') and string
Daniel@0: % 'Uplane' if it contains a u-matrix ('umat'). The tag is set to 
Daniel@0: % 'CplaneI' for planes created using 'compi' and 'colori', and 
Daniel@0: % 'UplaneI' for 'umati'.
Daniel@0: %
Daniel@0: % FEATURES
Daniel@0: %
Daniel@0: % Note that when interpolated shading is used in coloring ('compi' and
Daniel@0: % 'colori') the standard built-in bilinear Gouraud interpolation for a 
Daniel@0: % SURF object is used. If the lattice is hexagonal - or anything else than 
Daniel@0: % rectangular in general - the result is not strictly what is looked 
Daniel@0: % for, especially if the map is small. 
Daniel@0: %
Daniel@0: % EXAMPLES
Daniel@0: %
Daniel@0: %% Make random data, normalize it, and give component names
Daniel@0: %% Make a map
Daniel@0: %
Daniel@0: %   data=som_data_struct(rand(1000,3),'comp_names',{'One','Two','Three'});
Daniel@0: %   data=som_normalize(data,'var');
Daniel@0: %   map=som_make(data);
Daniel@0: %
Daniel@0: %% Do the basic visualization with som_show: u-matrix and all
Daniel@0: %% component planes
Daniel@0: %
Daniel@0: %   som_show(map);   
Daniel@0: %
Daniel@0: %% The values shown in the colorbar are denormalized codebook values 
Daniel@0: %% (if denormalization is possible). To view the actual values, use
Daniel@0: %% the ..., 'norm', 'n' argument pair.
Daniel@0: %
Daniel@0: %   som_show(map,'norm','n')
Daniel@0: %
Daniel@0: %% Something more complex:
Daniel@0: %% Show 1-2. Component planes 1 and 2 (variables 'One' and 'Two')
Daniel@0: %%        3. U-matrix that is calculated only using variables
Daniel@0: %%           'One' and 'Two' 
Daniel@0: %%           with title '1,2 only'
Daniel@0: %%        4. U-matrix that is calculated using all variables with the 
Daniel@0: %%           deafult title 'U-matrix'
Daniel@0: %%        5. The color code (in c) with title 'Color code'
Daniel@0: %%        6. Component plane 3 (variable 'Three')
Daniel@0: %% and  use vertical colorbars and and the values      
Daniel@0: %% But first: make a continuous color code (see som_colorcode)
Daniel@0: %
Daniel@0: % c=som_colorcode(map,'rgb1');
Daniel@0: % 
Daniel@0: % som_show(map,'comp',[1 2],'umat',{1:2,'1,2 only'},'umat','all', ...
Daniel@0: %  'color',{c,'Color code'},'bar','vert','norm','n','comp',3)
Daniel@0: %
Daniel@0: %  SEE ALSO
Daniel@0: %
Daniel@0: % som_show_add   Show hits, labels and trajectories on SOM_SHOW visualization.
Daniel@0: % som_show_clear Clear hit marks, labels or trajectories from current figure. 
Daniel@0: % som_umat       Compute unified distance matrix of self-organizing map.
Daniel@0: % som_grid       Visualization of a SOM grid.
Daniel@0: % som_cplane     Visualization of component, u-matrix and color planes.
Daniel@0: 
Daniel@0: % Copyright (c) 1997-2000 by the SOM toolbox programming team.
Daniel@0: % http://www.cis.hut.fi/projects/somtoolbox/             
Daniel@0: 
Daniel@0: % Version 1.0beta johan 100298 
Daniel@0: % Version 2.0beta johan 201099 juuso 181199 johan 011299-100200
Daniel@0: %                 juuso 130300 190600
Daniel@0: 
Daniel@0: %% Check arguments %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Daniel@0: 
Daniel@0: error(nargchk(1,Inf,nargin))     % check no. of input args
Daniel@0: 
Daniel@0: if isstruct(sMap),               % check map
Daniel@0:   [tmp,ok,tmp]=som_set(sMap);
Daniel@0:   if all(ok) & strcmp(sMap.type,'som_map') 
Daniel@0:     ;
Daniel@0:   else
Daniel@0:     error('Map struct is invalid!');
Daniel@0:   end
Daniel@0: else
Daniel@0:   error('Requires a map struct!')
Daniel@0: end
Daniel@0: 
Daniel@0: munits=size(sMap.codebook,1); % numb. of map units
Daniel@0: d=size(sMap.codebook,2);      % numb. of components
Daniel@0: msize=sMap.topol.msize;       % size of the map
Daniel@0: lattice=sMap.topol.lattice;   % lattice
Daniel@0: 
Daniel@0: if length(msize)>2 
Daniel@0:   error('This visualizes only 2D maps!')
Daniel@0: end
Daniel@0: 
Daniel@0: if rem(length(varargin),2)
Daniel@0:   error('Mismatch in identifier-value  pairs.');
Daniel@0: end
Daniel@0: 
Daniel@0: %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Daniel@0: %  read in optional arguments
Daniel@0:  
Daniel@0: if isempty(varargin),
Daniel@0:   varargin = { 'umat','all','comp','all'};
Daniel@0: end
Daniel@0: 
Daniel@0: %% check the varargin and build visualization infostrcuts
Daniel@0: % Vis:       what kind of planes, in which order, what are the values in
Daniel@0: %            the units
Daniel@0: % Vis_param: general properties
Daniel@0: % see subfunction
Daniel@0: 
Daniel@0: % The try-catch construction is here just for avoiding the
Daniel@0: % possible termination to happen in subfunction because an error
Daniel@0: % message containing subfunction line numbers etc. might be confusing, as
Daniel@0: % there probably is nothing wrong with the subfunction but with the 
Daniel@0: % input. Ok, this isn't proper programming sytle... 
Daniel@0: 
Daniel@0: try       
Daniel@0:   [Plane, General]= check_varargin(varargin, munits, d, sMap.name);
Daniel@0: catch
Daniel@0:   error(lasterr);
Daniel@0: end
Daniel@0: 
Daniel@0: % Set default values for missing ones
Daniel@0: 
Daniel@0: % No planes at all (only general properties given in varargin):
Daniel@0: % set default visualization
Daniel@0: 
Daniel@0: if isempty(Plane)
Daniel@0:   varargin = [varargin, { 'umat','all','comp','all'}];
Daniel@0:   % and again we go...
Daniel@0:   try
Daniel@0:     [Plane, General]= check_varargin(varargin, munits, d, sMap.name);
Daniel@0:   catch
Daniel@0:     error(lasterr);
Daniel@0:   end
Daniel@0: end
Daniel@0: 
Daniel@0: % set defaults for general properties
Daniel@0: 
Daniel@0: if isempty(General.colorbardir)
Daniel@0:   General.colorbardir='vert';
Daniel@0: end
Daniel@0: 
Daniel@0: if isempty(General.scale)
Daniel@0:   General.scale='denormalized';
Daniel@0: end
Daniel@0: 
Daniel@0: if isempty(General.size)
Daniel@0:   General.size=1;
Daniel@0: end
Daniel@0: 
Daniel@0: if isempty(General.edgecolor)
Daniel@0:   General.edgecolor='none';
Daniel@0: end
Daniel@0: 
Daniel@0: %% Action %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Daniel@0: 
Daniel@0: % get rid of an annoying warning: "RGB color data not yet supported in
Daniel@0: % Painter's mode."
Daniel@0: %set(gcf, 'renderer','zbuffer'); 
Daniel@0: %% -> a much more annoying thing results: the output to PostScript is 
Daniel@0: %%    as bitmap, making the files over 6MB in size... 
Daniel@0: 
Daniel@0: n=length(Plane);                     % the number of subfigures
Daniel@0: 
Daniel@0: % get the unique component indices
Daniel@0: c=General.comp(General.comp>0);
Daniel@0: c=setdiff(unique(c),[0 -1]); 
Daniel@0: c=c(~isnan(c));                   
Daniel@0: 
Daniel@0: % estimate the suitable dimension for
Daniel@0: if isempty(General.subplots), 
Daniel@0:   y=ceil(sqrt(n));                   % subplots
Daniel@0:   x=ceil(n/y);
Daniel@0: else
Daniel@0:   y = General.subplots(2); 
Daniel@0:   x = General.subplots(1); 
Daniel@0:   if y*x<n, 
Daniel@0:     error(['Given subplots grid size is too small: should be >=' num2str(n)]); 
Daniel@0:   end    
Daniel@0: end
Daniel@0: 
Daniel@0: clf;                               % clear figure
Daniel@0: 
Daniel@0: for i=1:n,                         % main loop
Daniel@0:   h_axes(i,1)=subplot(x,y,i);      % open a new subplot
Daniel@0:   
Daniel@0:   % Main switch: select function according to the flags set in comps  
Daniel@0: 
Daniel@0:   switch Plane{i}.mode
Daniel@0:   
Daniel@0:   case 'comp'
Daniel@0:     %%% Component plane
Daniel@0: 
Daniel@0:     tmp_h=som_cplane(lattice,msize, sMap.codebook(:,General.comp(i)), ...
Daniel@0: 		     General.size);
Daniel@0:     set(tmp_h,'EdgeColor', General.edgecolor);
Daniel@0:     set(h_axes(i),'Tag','Cplane');
Daniel@0:     h_label(i,1)=xlabel(sMap.comp_names{General.comp(i)});
Daniel@0:     
Daniel@0: 
Daniel@0:   case 'compi'
Daniel@0:     %%% Component plane (interpolated shading)
Daniel@0:     
Daniel@0:     tmp_h=som_grid(lattice, msize, 'surf', sMap.codebook(:,Plane{i}.value), ...
Daniel@0: 	'Marker', 'none', 'Line', 'none');
Daniel@0:     set(h_axes(i),'Tag','CplaneI');
Daniel@0:     h_label(i,1)=xlabel(sMap.comp_names(Plane{i}.value));
Daniel@0:     vis_PlaneAxisProperties(gca,lattice,msize,NaN);
Daniel@0:   
Daniel@0:   case 'color'
Daniel@0:     %%% Color plane
Daniel@0: 
Daniel@0:     tmp_h=som_cplane(lattice,msize,Plane{i}.value,General.size);
Daniel@0:     set(tmp_h,'EdgeColor','none');
Daniel@0:     set(h_axes(i),'Tag','Cplane');
Daniel@0:     h_label(i,1)=xlabel(Plane{i}.name);
Daniel@0:     
Daniel@0:       
Daniel@0:   case 'colori'
Daniel@0:     %%% Color plane (interpolated shading)
Daniel@0:     
Daniel@0:     tmp_h=som_grid(lattice, msize, 'surf', Plane{i}.value, 'Marker', 'none', ...
Daniel@0: 	'Line', 'none');
Daniel@0:     set(h_axes(i),'Tag','CplaneI');
Daniel@0:     h_label(i,1)=xlabel(Plane{i}.name);
Daniel@0:     vis_PlaneAxisProperties(gca,lattice,msize,NaN);
Daniel@0:   
Daniel@0:   case 'empty'      
Daniel@0:     %%% Empty plane
Daniel@0:     
Daniel@0:     tmp_h=som_cplane(lattice,msize,'none');
Daniel@0:     h_label(i,1)=xlabel(Plane{i}.name);
Daniel@0:     set(h_axes(i),'Tag','Cplane');
Daniel@0:     
Daniel@0:   case 'umat'
Daniel@0:     %%% Umatrix  
Daniel@0:     
Daniel@0:     u=som_umat(sMap.codebook(:,Plane{i}.value),sMap.topol,'median',...
Daniel@0: 	'mask',sMap.mask(Plane{i}.value)); u=u(:);
Daniel@0:     tmp_h=som_cplane([lattice 'U'],msize,u);
Daniel@0:     set(tmp_h,'EdgeColor','none');
Daniel@0:     set(h_axes(i),'Tag','Uplane');
Daniel@0:     h_label(i,1)=xlabel(Plane{i}.name);
Daniel@0: 
Daniel@0:   case 'umati'
Daniel@0:     %%% Umatrix (interpolated shading) 
Daniel@0:     
Daniel@0:     u=som_umat(sMap.codebook(:,Plane{i}.value),sMap.topol,'mean',...
Daniel@0: 	'mask',sMap.mask(Plane{i}.value)); u=u(1:2:end,1:2:end);
Daniel@0:     u=u(:);
Daniel@0:     tmp_h=som_grid('rect', msize, 'surf', u, ...
Daniel@0: 	'Marker', 'none', 'Line', 'none', ...
Daniel@0: 	'coord', som_vis_coords(lattice,msize));
Daniel@0:     set(h_axes(i),'Tag','UplaneI');
Daniel@0:     h_label(i,1)=xlabel(Plane{i}.name);
Daniel@0:     vis_PlaneAxisProperties(gca,lattice,msize,NaN);
Daniel@0:     
Daniel@0:   otherwise
Daniel@0:     error('INTERNAL ERROR: unknown visualization mode.');
Daniel@0:   end
Daniel@0: 
Daniel@0:   %%% Adjust axis ratios to optimal (only 2D!) and put the
Daniel@0:   %%% title as close to axis as possible
Daniel@0: 
Daniel@0:   set(h_label,'Visible','on','verticalalignment','top');
Daniel@0:   set(gca,'plotboxaspectratio',[msize(2) msize(1) msize(1)]);
Daniel@0:   
Daniel@0:   %%% Draw colorbars if they are turned on and the plane is umat or c-plane
Daniel@0: 
Daniel@0:   if General.comp(i)> -1 & ~strcmp(General.colorbardir,'none'),
Daniel@0:     h_colorbar(i,1)=colorbar(General.colorbardir);           % colorbars
Daniel@0:   else
Daniel@0:     h_colorbar(i,1)=-1;
Daniel@0:     General.comp(i)=-1;
Daniel@0:   end
Daniel@0: end         %% main loop ends
Daniel@0:   
Daniel@0: % Set window name
Daniel@0: 
Daniel@0: set(gcf,'Name',[ 'Map name: ' sMap.name]);
Daniel@0: 
Daniel@0: %% Set axes handles to the UserData field (for som_addxxx functions
Daniel@0: %% and som_recolorbar) 
Daniel@0: %% set component indexes and normalization struct for som_recolorbar
Daniel@0: 
Daniel@0: SOM_SHOW.subplotorder=h_axes;
Daniel@0: SOM_SHOW.msize=msize;
Daniel@0: SOM_SHOW.lattice=lattice;
Daniel@0: SOM_SHOW.dim=d;
Daniel@0: SOM_SHOW.comps=General.comp;
Daniel@0: SOM_SHOW.comp_norm=sMap.comp_norm; %(General.comp(find(General.comp>0)));
Daniel@0: 
Daniel@0: set(gcf,'UserData', SOM_SHOW);
Daniel@0: 
Daniel@0: % Set text property 'interp' to 'none' in title texts
Daniel@0: 
Daniel@0: set(h_label,'interpreter','none');
Daniel@0: 
Daniel@0: h_colorbar=som_recolorbar('all', 3, General.scale);   %refresh colorbars
Daniel@0: 
Daniel@0: % Set a movable text to lower corner pointsize 12.
Daniel@0: 
Daniel@0: vis_footnote(General.footnote);  vis_footnote(12);  
Daniel@0: 
Daniel@0: % set colormap
Daniel@0: colormap(General.colormap);
Daniel@0: 
Daniel@0: %% Build output %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
Daniel@0: 
Daniel@0: if nargout > 0
Daniel@0:   h.plane=h_axes; h.colorbar=h_colorbar; h.label=h_label;
Daniel@0: end
Daniel@0: 
Daniel@0: 
Daniel@0: %%%%%% SUBFUNCTIONS %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Daniel@0: 
Daniel@0: function [Plane, General]=check_varargin(args, munits, dim, name)
Daniel@0: 
Daniel@0: % args: varargin of the main function
Daniel@0: % munits: number of map units
Daniel@0: % dim: map codebook dimension
Daniel@0: % name: map name
Daniel@0: % Define some variables (they must exist later)
Daniel@0: 
Daniel@0: Plane={};           % stores the visualization data for each subplot
Daniel@0: General.comp=[];    % information stored on SOM_SHOW figure (which component)
Daniel@0: General.size=[];            % unit size
Daniel@0: General.scale=[];           % normalization
Daniel@0: General.colorbardir=[];     % colorbar direction
Daniel@0: General.edgecolor=[];       % edge colors
Daniel@0: General.footnote=name;      % footnote text
Daniel@0: General.colormap=colormap;  % default colormap (used to be gray(64).^.5;)
Daniel@0: General.subplots=[];        % number of subplots in y- and x-directions
Daniel@0: 
Daniel@0: for i=1:2:length(args),
Daniel@0:   %% Check that all argument types are strings
Daniel@0:   
Daniel@0:   if ~ischar(args{i}),
Daniel@0:     error('Invalid input identifier names or input argument order.');
Daniel@0:   end
Daniel@0:   
Daniel@0:   %% Lower/uppercase in identifier types doesn't matter: 
Daniel@0:   
Daniel@0:   identifier=lower(args{i});     % identifier (lowercase)
Daniel@0:   value=args{i+1};
Daniel@0:   
Daniel@0:   %%% Check first the identifiers that define planes and get values
Daniel@0:   %%% to the visualization data struct array Plane.
Daniel@0:   %%% (comps,compi,umat,color,empty) Note that name, value and comp_
Daniel@0:   %%% must be specified in these cases 
Daniel@0:   %%% comp_ are collected to comp in order. This is stored to the
Daniel@0:   %%% SOM_SHOW user property field to give information for SOM_RECOLROBAR
Daniel@0:   %%% how to operate, i.e., which component is in which subplot:
Daniel@0:   %%% comp(i)=0: draw colorbar, but no normalization (umat) 
Daniel@0:   %%% comp(i)=1...N: a component plane of variable comp(i)
Daniel@0:   %%% comp(i)=-1: no colorbar (color or empty plane)    
Daniel@0:   
Daniel@0:   switch identifier  
Daniel@0:    case {'comp','compi'}
Daniel@0:     %%% Component planes: check values & set defaults
Daniel@0:     
Daniel@0:     if ~vis_valuetype(value,{'nx1','1xn','string'}) & ~isempty(value),
Daniel@0:       error([ 'A vector argument or string ''all'' expected for ''' ...
Daniel@0: 	      identifier '''.'])
Daniel@0:     end
Daniel@0:     if isempty(value) 
Daniel@0:       value=1:dim;
Daniel@0:     elseif ischar(value), 
Daniel@0:       if ~strcmp(value,'all')
Daniel@0: 	error([ 'Only string value ''all'' is valid for ''' ...
Daniel@0: 		identifier '''.']);
Daniel@0:       else
Daniel@0: 	value=1:dim;
Daniel@0:       end
Daniel@0:     else
Daniel@0:       value=round(value);
Daniel@0:       if min(value)<1 | max(value)>dim,
Daniel@0: 	error([ 'Component indices out of range in ''' identifier '''.']) 
Daniel@0:       end
Daniel@0:     end
Daniel@0:     if size(value,1)==1, value=value';end
Daniel@0:     comp_=value; 
Daniel@0:     name=[]; % name is taken form sMap by index in main loop 
Daniel@0:     
Daniel@0:   case {'umat','umati'}
Daniel@0:     %%% Check first the possible cell input
Daniel@0:     
Daniel@0:     if iscell(value),
Daniel@0:       if ndims(value) ~= 2 | any(size(value) ~= [1 2]) | ...
Daniel@0: 	    ~vis_valuetype(value{2},{'string'}),
Daniel@0: 	error('Cell input for ''umat'' has to be of form {vector, string}.');
Daniel@0:       else
Daniel@0: 	name=value{2}; value=value{1};
Daniel@0:       end
Daniel@0:     else 
Daniel@0:       name='U-matrix'; % no cell: default title is set
Daniel@0:     end
Daniel@0:     if ~vis_valuetype(value,{'nx1','1xn','string'}) & ~isempty(value),
Daniel@0:       error('Vector, string ''all'', or cell {vector, string} expected for ''umat''.')
Daniel@0:     end
Daniel@0:     if isempty(value)
Daniel@0:       value=1:dim;
Daniel@0:     elseif ischar(value), 
Daniel@0:       if ~strcmp(value,'all')
Daniel@0: 	error('Only string value ''all'' is valid for ''umat''.')
Daniel@0:       else
Daniel@0: 	value=1:dim;
Daniel@0:       end
Daniel@0:     else
Daniel@0:       value=unique(round(value));
Daniel@0:     end
Daniel@0:     if min(value)<1 | max(value)>dim,
Daniel@0:       error('Component indices out of range in ''umat''.') 
Daniel@0:     end
Daniel@0:     
Daniel@0:     if size(value,1)==1, value=value';end
Daniel@0:     comp_=0;
Daniel@0:     
Daniel@0:   case 'empty'
Daniel@0:     %%% Empty plane: check values & set defaults
Daniel@0:     
Daniel@0:     if ~vis_valuetype(value,{'string'}), 
Daniel@0:       error('A string value for title name expected for ''empty''.');
Daniel@0:     end
Daniel@0:     name=value;
Daniel@0:     comp_=-1;
Daniel@0:     
Daniel@0:   case { 'color','colori'}
Daniel@0:     %%% Color plane: check values & set defaults
Daniel@0:     
Daniel@0:     % Check first the possible cell input
Daniel@0:     if iscell(value),
Daniel@0:       if ndims(value)~=2 | any(size(value) ~= [1 2]) | ...
Daniel@0: 	    ~vis_valuetype(value{2},{'string'}),
Daniel@0: 	error([ 'Cell input for ''' identifier ...
Daniel@0: 	      ''' has to be of form {M, string}.']);
Daniel@0:       else
Daniel@0: 	name=value{2}; value=value{1};
Daniel@0:       end
Daniel@0:     else 
Daniel@0:       name='Color code'; % no cell: default title is set
Daniel@0:     end
Daniel@0:     if size(value,1)~=munits | ...
Daniel@0: 	  (~vis_valuetype(value,{'nx3rgb'}) & ... 
Daniel@0: 	   ~vis_valuetype(value,{'nx1'}) & ...
Daniel@0: 	   ~vis_valuetype(value,{'nx1xm'}) & ...
Daniel@0: 	   ~vis_valuetype(value,{'nx3xdimrgb'})),
Daniel@0:       error(['Mx3 or Mx3xN RGBmatrix, Mx1 or Mx1xN matrix, cell '...
Daniel@0: 	     '{RGBmatrix, string},' ...
Daniel@0: 	     ' or {matrix, string} expected for ''' identifier '''.']);
Daniel@0:     end
Daniel@0: 
Daniel@0:     % if colormap is fixed, we don't draw colorbar (comp_ flag is -1)
Daniel@0:     % if colormap is indexed, we draw colorbar as in umat (comp_=0)
Daniel@0: 
Daniel@0:     if size(value,2)==3
Daniel@0:       comp_=-1;
Daniel@0:     else
Daniel@0:       comp_=0;
Daniel@0:     end
Daniel@0:     
Daniel@0:     %%%% The next things are general properties of the visualization---
Daniel@0:     %%%%
Daniel@0:     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Daniel@0:     
Daniel@0:   case 'size'
Daniel@0:     %%% Unit size: check & set
Daniel@0:   
Daniel@0:     if ~vis_valuetype(value,{'1x1',[munits 1]})
Daniel@0:       error('A munits x 1 vector or a scalar expected for ''size''.')
Daniel@0:     end
Daniel@0:     if isempty(value),
Daniel@0:       General.size=1;
Daniel@0:     else
Daniel@0:       General.size=value;
Daniel@0:     end
Daniel@0:     
Daniel@0:    case 'bar'
Daniel@0:     %%% Colorbar existence & direction: check & set
Daniel@0:     
Daniel@0:     if ~vis_valuetype(value,{'string'})
Daniel@0:       error('String value expected for ''bar''.')
Daniel@0:     elseif isempty(value)
Daniel@0:       value='vert';
Daniel@0:     end
Daniel@0:     if any(strcmp(value,{'vert','horiz','none'})),
Daniel@0:       General.colorbardir=value;
Daniel@0:     else
Daniel@0:       error('String ''vert'', ''horiz'' or ''none'' expected for ''bar''.');
Daniel@0:     end
Daniel@0:     
Daniel@0:   case 'norm' 
Daniel@0:     %%% Value normalization: check & set
Daniel@0:     
Daniel@0:     if ~vis_valuetype(value,{'string'})
Daniel@0:       error('String ''n'' or ''d'' expected for ''norm''.');
Daniel@0:     elseif isempty(value)
Daniel@0:       value='n';
Daniel@0:     end
Daniel@0:     if strcmp(value(1),'n'), 
Daniel@0:       General.scale='normalized';
Daniel@0:     elseif strcmp(value(1),'d'),
Daniel@0:       General.scale='denormalized';
Daniel@0:     else
Daniel@0:       error('String ''n(ormalized)'' or ''d(enormalized)'' expected for ''norm''.');
Daniel@0:     end
Daniel@0:     
Daniel@0:   case 'edge'
Daniel@0:     %%% Edge on or off : check % set 
Daniel@0:     
Daniel@0:     if ~vis_valuetype(value,{'string'}) & ~isempty(value),
Daniel@0:       error('String value expected for ''edge''.')
Daniel@0:     elseif ~isempty(value),
Daniel@0:       switch value
Daniel@0:       case 'on'
Daniel@0: 	General.edgecolor='k';
Daniel@0:       case 'off' 
Daniel@0: 	General.edgecolor='none';
Daniel@0:       otherwise
Daniel@0: 	error('String value ''on'' or ''off'' expected for ''edge''.')  
Daniel@0:       end
Daniel@0:     end
Daniel@0:     
Daniel@0:   case 'footnote'
Daniel@0:     %%% Set the movable footnote text  
Daniel@0:     
Daniel@0:     if ~vis_valuetype(value,{'string'}) 
Daniel@0:       if ~isempty(value),
Daniel@0: 	error('String value expected for ''footnote''.');
Daniel@0:       else
Daniel@0: 	General.footnote=sMap.name;
Daniel@0:       end
Daniel@0:     else
Daniel@0:       General.footnote=value;
Daniel@0:     end
Daniel@0: 
Daniel@0:    case 'colormap'
Daniel@0:     %%% Set the colormap
Daniel@0:     if isempty(value)
Daniel@0:       General.colormap=gray(64).^2;
Daniel@0:     elseif ~vis_valuetype(value,{'nx3rgb'})
Daniel@0:       error('Colormap is invalid!');
Daniel@0:     else
Daniel@0:       General.colormap=value;
Daniel@0:     end
Daniel@0:     
Daniel@0:    case 'subplots'
Daniel@0:     %%% set the number of subplots
Daniel@0:     if ~vis_valuetype(value,{'1x2'}) & ~vis_valuetype(value,{'2x1'})
Daniel@0:       error('Subplots grid size is invalid!');
Daniel@0:     else
Daniel@0:       General.subplots=value; 
Daniel@0:     end
Daniel@0:     
Daniel@0:   otherwise
Daniel@0:     %%% Unknown identifier
Daniel@0:     
Daniel@0:     error(['Invalid argument identifier ''' identifier '''!']);
Daniel@0:   end
Daniel@0:   
Daniel@0:   %%% Set new entry to the Plane array if the indentifier means 
Daniel@0:   %%% making a new plane/planes
Daniel@0:   
Daniel@0:   tail=length(Plane);
Daniel@0:   switch identifier
Daniel@0:   case {'comp','compi'}
Daniel@0:     for i=1:length(value)
Daniel@0:       Plane{tail+i}.mode=identifier;
Daniel@0:       Plane{tail+i}.value=value(i);
Daniel@0:       Plane{tail+i}.name=name; % not used actually
Daniel@0:     end
Daniel@0:     General.comp = [General.comp; comp_];
Daniel@0:    case {'umat','umati','empty'}
Daniel@0:     Plane{tail+1}.mode=identifier;
Daniel@0:     Plane{tail+1}.value=value;
Daniel@0:     Plane{tail+1}.name=name;
Daniel@0:     General.comp = [General.comp; comp_];
Daniel@0:    case {'color','colori'},
Daniel@0:     for i=1:size(value,3),
Daniel@0:       Plane{tail+i}.mode=identifier;
Daniel@0:       Plane{tail+i}.name=[name '_' num2str(i)];
Daniel@0:       Plane{tail+i}.value=value(:,:,i);
Daniel@0:       General.comp = [General.comp; comp_];
Daniel@0:     end
Daniel@0:     if size(value,3)==1,
Daniel@0:       Plane{tail+1}.name=name;
Daniel@0:     end
Daniel@0:   otherwise
Daniel@0:     ; % do nothing
Daniel@0:   end
Daniel@0: end