Daniel@0: function som_trajectory(bmus,varargin)
Daniel@0: 
Daniel@0: %SOM_TRAJECTORY Launch a "comet" trajectory visualization GUI.
Daniel@0: %
Daniel@0: %  som_show(sM,'umat','all')
Daniel@0: %  bmus = som_bmus(sM,sD);
Daniel@0: %  som_trajectory(bmus)
Daniel@0: %  som_trajectory(bmus, 'data1', sD, 'trajsize', [12 6 3 1]')
Daniel@0: %  som_trajectory(bmus, 'data1', sD.data(:,[1 2 3]), 'name1', {'fii' 'faa' 'foo'})
Daniel@0: %
Daniel@0: % Input arguments ([]'s are optional):
Daniel@0: %   bmus      (matrix) size Nx1, vector of BMUS
Daniel@0: %   ['argID', (string) Other arguments can be given as 'argID', value   
Daniel@0: %    value]   (varies) pairs. See list below for valid values.
Daniel@0: %
Daniel@0: % NOTE: the GUI only works on a figure which has been made with SOM_SHOW.
Daniel@0: %
Daniel@0: % Here are the valid argument IDs (case insensitive) and associated values: 
Daniel@0: %  'color'      string 'xor' or ColorSpec, default: 'xor'. 
Daniel@0: %               (default: according to lattice as in som_cplane)
Daniel@0: %  'TrajSize'   vector of size Nx1 to define the length of comet
Daniel@0: %               (N) and size of the comet dots in points. 
Daniel@0: %               default: [16 12 10 8 6 4]' 
Daniel@0: %  'Data1'      SOM Toolbox data struct or matrix. The size of
Daniel@0: %               data matrix (in data struct the field .data) is
Daniel@0: %               Nxd, where N must be the same as the amount of
Daniel@0: %               BMUS given in the first input argument 'bmus'
Daniel@0: %               This data is shown in a new window in d subplots.
Daniel@0: %               Default: BMU indices (first input argument)
Daniel@0: %  'Name1'      cell array of d strings which contains names
Daniel@0: %               for the components in 'Data1'. If 'Data1' is a SOM
Daniel@0: %               Toolbox data struct, the existing component names 
Daniel@0: %               are overdone.                 
Daniel@0: %  'Figure'     scalar that must be a handle to an existing figure
Daniel@0: %               which has been made using SOM_SHOW function.
Daniel@0: %               Default: current active figure (gcf).
Daniel@0: %
Daniel@0: % The following tools can be found in the 'Tools' -menu.
Daniel@0: %
Daniel@0: %  Remove Trajectory: removes trajectory from the map.
Daniel@0: %  Dye Nodes        : opens GUI for selecting color for the nodes
Daniel@0: %                     and points selected.
Daniel@0: %  Clear Markers    : removes markers from map and data figure.
Daniel@0: %  Save             : saves the current situation as a struct.
Daniel@0: %  Load             : loads the struct from workspace and draws markers.
Daniel@0: %
Daniel@0: % Mouse operation
Daniel@0: %
Daniel@0: %  In data window: Left button is used to drag the operation point ruler  
Daniel@0: %                  if left button is on blank area, it starts 
Daniel@0: %  In map window : Left button starts a polygon; right button
Daniel@0: %                  finishes; middle button toggles a unit.
Daniel@0: %
Daniel@0: % SOM_TRAJECTORY is an application for observing trajectory behavior.
Daniel@0: %
Daniel@0: % Using mouse the line in data figure can be dragged and the
Daniel@0: % trajectory moves in the SOM SHOW figure. It is also possible to move
Daniel@0: % trajectory by pressing keys '>' and '<' when mouse pointer is above
Daniel@0: % data figure.
Daniel@0: % 
Daniel@0: % Regions can be chosen from the data and the points in that region
Daniel@0: % are mapped to the component planes. Regions can be chosen also in
Daniel@0: % the map.  In this situation data points and map nodes are also
Daniel@0: % marked (Left mouse button adds point to the polygon indicating the
Daniel@0: % region and right button finals the polygon). By clicking a node (the
Daniel@0: % middle button) that node is either added or removed from selection.
Daniel@0: % 
Daniel@0: % It should be noticed that choosing intervals from data may cause
Daniel@0: % situations that seem to be bugs. If there exisist marks of different
Daniel@0: % color, removing them by clicking the map may left some marks in the
Daniel@0: % data, because more than one point in the data is mapped to the same
Daniel@0: % node in the map and the removing operation depends on the color of
Daniel@0: % the marks. However, all the marks can be removed by using the 'Clear
Daniel@0: % Markers' -operation.
Daniel@0: %
Daniel@0: % FEATURES
Daniel@0: %
Daniel@0: % The first input argument 'bmus' may also be a munits x N matrix
Daniel@0: % In this case each column defines a "fuzzy response". That is,
Daniel@0: % each column defines a hit histogram function). The element
Daniel@0: % bmus(i,t) sets the size of marker on unit i at time t. 
Daniel@0: % NOTE: - in this case no regions can be selcted on the map!
Daniel@0: %       - only > and < keys can be used to move the operation point
Daniel@0: %         line: it can't be dragged
Daniel@0: %       - "fuzzy response is always black (hope this will be fixed) 
Daniel@0: %       
Daniel@0: % It is possible to open a second data window showing different data:
Daniel@0: % use indetifiers 'Data2' (and 'Name2'). The argument syntax is
Daniel@0: % identical to 'Data1' (and 'Name1').
Daniel@0: %
Daniel@0: % See also SOM_SHOW, SOM_SHOW_ADD, SOM_BMUS. 
Daniel@0: 
Daniel@0: % Contributed to SOM Toolbox 2.0, February 11th, 2000 by Johan
Daniel@0: % Himberg and Juha Parhankangas
Daniel@0: % Copyright (c) 2000 by the Johan Himberg and Juha Parhankangas
Daniel@0: % http://www.cis.hut.fi/projects/somtoolbox/        
Daniel@0: 
Daniel@0: % Check arguments
Daniel@0: 
Daniel@0: error(nargchk(1,Inf,nargin)); % Check no. of input arguments
Daniel@0: 
Daniel@0: %% Init input argument struct (see subfunction)
Daniel@0: Traj=iniTraj(bmus);
Daniel@0: 
Daniel@0: % Check tentative BMU input validity
Daniel@0: 
Daniel@0: if ~vis_valuetype(bmus,{'nxm'}),
Daniel@0:   error(['First input should be a vector of BMU indices or' ...
Daniel@0: 	 ' a "response matrix"']);
Daniel@0: end
Daniel@0: 
Daniel@0: %% Check optional arguments
Daniel@0: for i=1:2:length(varargin)
Daniel@0:   identifier=lower(varargin{i});
Daniel@0:   value=varargin{i+1};
Daniel@0: 
Daniel@0:   % Trajectory color
Daniel@0:   switch identifier  
Daniel@0:    case 'color'
Daniel@0:     if isempty(value)
Daniel@0:       value='xor';
Daniel@0:     end
Daniel@0:     if vis_valuetype(value,{'colorstyle','xor'})
Daniel@0:       Traj.color=value;
Daniel@0:     else
Daniel@0:       error('''Color'' has to be ColorSpec or string ''xor''.');
Daniel@0:     end
Daniel@0:    
Daniel@0:    % 1st data  
Daniel@0:    case 'data1'
Daniel@0:     if isempty(value),
Daniel@0:       value=[];
Daniel@0:     elseif vis_valuetype(value,{'nxm'})
Daniel@0:       Traj.primary_data=value;
Daniel@0:     elseif isstruct(value) & isfield(value,'type') & ...
Daniel@0: 	  ischar(value.type) & strcmp(value.type,'som_data'),
Daniel@0:       Traj.primary_data=value.data;
Daniel@0:       if isempty(Traj.primary_names),
Daniel@0: 	Traj.primary_names=value.comp_names;
Daniel@0:       end
Daniel@0:     end
Daniel@0:    
Daniel@0:     % 2nd data
Daniel@0:    case 'data2'
Daniel@0:     if isempty(value),
Daniel@0:       value=[];
Daniel@0:     elseif vis_valuetype(value,{'nxm'})
Daniel@0:       Traj.secondary_data=value;
Daniel@0:     elseif isstruct(value) & isfield(value,'type') & ...
Daniel@0: 	  ischar(value.type) & strcmp(value.type,'som_data'),
Daniel@0:       Traj.secondary_data=value.data;
Daniel@0:       if isempty(Traj.secondary_names),
Daniel@0: 	Traj.secondary_names=value.comp_names;
Daniel@0:       end
Daniel@0:      end
Daniel@0:    
Daniel@0:    % Trajectory length & size
Daniel@0:    case 'trajsize'
Daniel@0:     if isempty(value),
Daniel@0:       Traj.size=[16 12 10 8 6 4]';
Daniel@0:     end
Daniel@0:     if vis_valuetype(value,{'nx1'})
Daniel@0:       Traj.size=value
Daniel@0:     else
Daniel@0:       error('''TrajSize'' has to be a nx1 vector.');
Daniel@0:     end
Daniel@0:    
Daniel@0:    % Names for first data variables
Daniel@0:    case 'name1'
Daniel@0:     if isempty(value),
Daniel@0:       Traj.primary_names=[];
Daniel@0:     elseif ~vis_valuetype(value,{'cellcolumn_of_char'}),
Daniel@0:       error('''Name1'': variable names must be in a cell column array.') 
Daniel@0:     else
Daniel@0:       Traj.primary_names = value;
Daniel@0:     end
Daniel@0:    % Names for 2nd data variables
Daniel@0:    case 'name2'
Daniel@0:     if isempty(value),
Daniel@0:       Traj.secondary_names=[];
Daniel@0:     elseif ~vis_valuetype(value,{'cellcolumn_of_char'}),
Daniel@0:       error('''Name2'': variable names must be in a cell column array.') 
Daniel@0:     else
Daniel@0:       Traj.secondary_names = value;
Daniel@0:     end
Daniel@0:    
Daniel@0:    % Figure number
Daniel@0:    case 'figure'
Daniel@0:     if isempty(value)
Daniel@0:       Traj.figure='gcf';
Daniel@0:     end
Daniel@0:     if vis_valuetype(value,{'1x1'})
Daniel@0:       Traj.figure=value;
Daniel@0:     else
Daniel@0:       error('''Figure'' should be number of an existing figure.')
Daniel@0:     end
Daniel@0:   end
Daniel@0: end
Daniel@0: 
Daniel@0: %% Get SOM data from figure
Daniel@0: [h,msg,lattice,msize,dim]=vis_som_show_data('all',Traj.figure);
Daniel@0: 
Daniel@0: %% Not a SOM_SHOW figure?
Daniel@0: if ~isempty(msg);
Daniel@0:   error('Figure is invalid: use SOM_SHOW to draw the figure.');
Daniel@0: end
Daniel@0: 
Daniel@0: % Get map size from figure data
Daniel@0: Traj.lattice=lattice; 
Daniel@0: Traj.msize=msize;  
Daniel@0: if length(msize)>2,
Daniel@0:   error(['This function works only with 2D maps: figure contains' ...
Daniel@0: 	 ' something else.']);
Daniel@0: end
Daniel@0: munits=prod(msize);
Daniel@0: 
Daniel@0: % Check BMU (or response) and map match 
Daniel@0: 
Daniel@0: if vis_valuetype(bmus,{'nx1'});
Daniel@0:   if max(bmus)>prod(msize) | min(bmus) <1
Daniel@0:     error('BMU indexes out of range.')
Daniel@0:   elseif any(round(bmus)~=bmus)
Daniel@0:     error('BMU indexes must be integer.');
Daniel@0:   elseif isempty(Traj.primary_data),
Daniel@0:     Traj.primary_data=bmus;
Daniel@0:   end
Daniel@0: elseif size(bmus,1) ~= munits 
Daniel@0:   error(['Response matrix column number must match with the number of' ...
Daniel@0: 	 ' map units.']);
Daniel@0: else
Daniel@0:   bmus=bmus';
Daniel@0:   if isempty(Traj.primary_data),
Daniel@0:     Traj.primary_data=[1:size(bmus,1)]';
Daniel@0:     Traj.primary_names={'BMU Index'};
Daniel@0:   end
Daniel@0: end
Daniel@0: 
Daniel@0: size1=size(Traj.primary_data);
Daniel@0: size2=size(Traj.secondary_data);
Daniel@0: 
Daniel@0: % Data2 must not be defined alone
Daniel@0: 
Daniel@0: if isempty(Traj.primary_data)&~isempty(Traj.secondary_data),
Daniel@0:   error('If ''Data2'' is specified ''Data1'' must be specified, too.');
Daniel@0: elseif ~isempty(Traj.secondary_data) ...
Daniel@0:       & size1~= size2
Daniel@0:   % If data1 and data2 exist both, check data1 and data2 match
Daniel@0:   error('''Data1'' and ''Data2'' have different amount of data vectors.')
Daniel@0: end
Daniel@0: 
Daniel@0: % Check BMU and data1 match (data2 matches with 1 anyway)
Daniel@0: 
Daniel@0: if ~isempty(Traj.primary_data) & size(bmus,1) ~= size1,
Daniel@0:   error(['The number of data vectors in ''data1'' must match with' ...
Daniel@0: 	 ' the number of rows in the first input argument (bmus).']);
Daniel@0: end
Daniel@0: 
Daniel@0: % Check that number of names and data dimension is consistent
Daniel@0: 
Daniel@0: if ~isempty(Traj.primary_names) & (size1(2)~=length(Traj.primary_names)),
Daniel@0:   error('Number of component names and ''Data1'' dimension mismatch.');
Daniel@0: end
Daniel@0: if ~isempty(Traj.secondary_names) & ...
Daniel@0:       (size2(2)~=length(Traj.secondary_names)),
Daniel@0:   error('Number of component names and ''Data2'' dimension mismatch.');
Daniel@0: end
Daniel@0: 
Daniel@0: %% Call the function that does the job
Daniel@0: vis_trajgui(Traj);
Daniel@0: 
Daniel@0: %%% Subfunctions %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Daniel@0: 
Daniel@0: function Traj=iniTraj(bmus)
Daniel@0: 
Daniel@0: Traj.figure=gcf;
Daniel@0: Traj.primary_data=[];
Daniel@0: Traj.secondary_data=[];
Daniel@0: Traj.primary_names = [];  
Daniel@0: Traj.secondary_names = [];  
Daniel@0: Traj.size=[16 12 10 8 6 4]';
Daniel@0: Traj.bmus=bmus;
Daniel@0: Traj.color='xor';
Daniel@0: Traj.msize=[];
Daniel@0: Traj.lattice=[];
Daniel@0: