comparison toolboxes/MIRtoolbox1.3.2/somtoolbox/som_trajectory.m @ 0:e9a9cd732c1e tip

first hg version after svn

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