wolffd@0: function [sTo] = som_autolabel(sTo, sFrom, mode, inds)
wolffd@0: 
wolffd@0: %SOM_AUTOLABEL Automatical labeling, or clearing of labels.
wolffd@0: %
wolffd@0: % sTo = som_autolabel(sTo, sFrom, [mode], [inds])
wolffd@0: %
wolffd@0: %   sM = som_autolabel(sM,sD);      
wolffd@0: %   sD = som_autolabel(sD,sM);   
wolffd@0: %   sM = som_autolabel(sM,sD,'vote',[5]);
wolffd@0: %
wolffd@0: %  Input and output arguments ([]'s are optional): 
wolffd@0: %   sTo      (struct) data or map struct to which the labels are put,
wolffd@0: %                     the modified struct is returned
wolffd@0: %   sFrom    (struct) data or map struct from which the labels are taken
wolffd@0: %   [mode]   (string) labeling algorithm: 'add' (the default), 'freq' 
wolffd@0: %                     or 'vote'
wolffd@0: %   [inds]   (vector) the column-indexes of the labels that are to be
wolffd@0: %                     used in the operation (e.g. [2] would mean to use
wolffd@0: %                     only the second column of labels array in sFrom) 
wolffd@0: % 
wolffd@0: % The modes:
wolffd@0: %  'add':   all labels from sFrom are added to sTo (even multiple
wolffd@0: %           copies of same)  
wolffd@0: %  'add1':  only one instance of each label is kept
wolffd@0: %  'freq':  only one instance of each label is kept and '(#)', where 
wolffd@0: %           # is the frequency of the label, is added to the end of 
wolffd@0: %           the label. Labels are ordered according to frequency. 
wolffd@0: %  'vote':  only the label with most instances is kept
wolffd@0: %
wolffd@0: % NOTE: The operations are only performed for the new labels. 
wolffd@0: %       The old labels in sTo are left as they are.
wolffd@0: % NOTE: all empty labels ('') are ignored.
wolffd@0: %
wolffd@0: % For more help, try 'type som_autolabel' or check out online documentation.
wolffd@0: % See also SOM_LABEL, SOM_BMUS, SOM_SHOW_ADD, SOM_SHOW.
wolffd@0: 
wolffd@0: %%%%%%%%%%%%% DETAILED DESCRIPTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
wolffd@0: %
wolffd@0: % som_autolabel
wolffd@0: %
wolffd@0: % PURPOSE
wolffd@0: %
wolffd@0: % Automatically label to map/data structs based on given data/map.
wolffd@0: %
wolffd@0: % SYNTAX
wolffd@0: %
wolffd@0: %  sTo = som_autolabel(sTo, sFrom)
wolffd@0: %  sTo = som_autolabel(sTo, sFrom, 'add')
wolffd@0: %  sTo = som_autolabel(sTo, sFrom, 'freq')
wolffd@0: %  sTo = som_autolabel(sTo, sFrom, 'vote')
wolffd@0: %  sTo = som_autolabel(..., inds)
wolffd@0: %
wolffd@0: % DESCRIPTION
wolffd@0: %
wolffd@0: % This function automatically labels given map/data struct based on an
wolffd@0: % already labelled data/map struct. Basically, the BMU of each vector in the
wolffd@0: % sFrom struct is found from among the vectors in sTo, and the vectors in
wolffd@0: % sFrom are added to the corresponding vector in the sTo struct. The actual
wolffd@0: % labels to add are selected based on the mode ('add', 'freq' or 'vote').
wolffd@0: %
wolffd@0: %  'add'  :  all labels from sFrom are added to sTo - even if there would 
wolffd@0: %            be multiple instances of the same label
wolffd@0: %  'add1' :  only one instance of each label is kept
wolffd@0: %  'freq' :  only one instance of each label is kept and '(#)', where 
wolffd@0: %            # is the frequency of the label, is added to the end of 
wolffd@0: %            the label. Labels are ordered according to frequency. 
wolffd@0: %  'vote' :  only the label with most instances is added
wolffd@0: %
wolffd@0: % Note that these operations do not effect the old labels of sTo: they 
wolffd@0: % are left as they were.  
wolffd@0: % 
wolffd@0: % NOTE: empty labels ('') are ignored.
wolffd@0: %
wolffd@0: % REQUIRED INPUT ARGUMENTS
wolffd@0: %
wolffd@0: %   sTo    (struct) data or map struct to which the labels are put 
wolffd@0: %   sFrom  (struct) data or map struct from which the labels are taken
wolffd@0: %
wolffd@0: % OPTIONAL INPUT ARGUMENTS 
wolffd@0: %
wolffd@0: %   mode   (string) The mode of operation: 'add' (default), 
wolffd@0: %                   'add1', 'freq' or 'vote'
wolffd@0: %   inds   (vector) The columns of the '.labels' field in sFrom to be 
wolffd@0: %                   used in operation
wolffd@0: %
wolffd@0: % OUTPUT ARGUMENTS
wolffd@0: % 
wolffd@0: %   sTo    (struct) the given data/map struct with modified labels
wolffd@0: % 
wolffd@0: % EXAMPLES
wolffd@0: %
wolffd@0: % To label a trained map based on (labelled) training data, just do
wolffd@0: %
wolffd@0: %  sM = som_autolabel(sM,sD);      
wolffd@0: %
wolffd@0: % This operation is sometimes called "calibration" in the literature.
wolffd@0: % You can also do this the other way around: use a labelled map to 
wolffd@0: % label a data set: 
wolffd@0: %
wolffd@0: %  sD = som_autolabel(sD,sM);   
wolffd@0: %
wolffd@0: % If you only want a single instance of each label, use the 'freq' mode: 
wolffd@0: %
wolffd@0: %  sM = som_autolabel(sM,sD,'freq');
wolffd@0: %
wolffd@0: % If you already have labels in the struct, and want to perform 'freq' on 
wolffd@0: % them, do the following: 
wolffd@0: %
wolffd@0: %  sMtemp = som_label(sM,'clear','all'); % make a map struct with no labels
wolffd@0: %  sM = som_autolabel(sMtemp,sM,'freq'); % add labels to it
wolffd@0: %
wolffd@0: % The third mode 'vote' votes between the labels and only adds the one
wolffd@0: % which is most frequent. If two labels are equally frequent, one or the
wolffd@0: % other is chosen based on which appears first in the list.
wolffd@0: %
wolffd@0: %  sM = som_autolabel(sM,sD,'vote');
wolffd@0: %
wolffd@0: % The lat argument is useful if you have specific labels in each column
wolffd@0: % of the '.labels' field. For example, the first column might be an
wolffd@0: % identifier, the next a typecode and the last a year. In this case, you
wolffd@0: % might want to label the map based only on the typecode: 
wolffd@0: % 
wolffd@0: %  sM  = som_autolabel(sM,sD,'vote',2);
wolffd@0: %
wolffd@0: % SEE ALSO
wolffd@0: % 
wolffd@0: %  som_label     Give/remove labels from a map/data set.
wolffd@0: %  som_bmus      Find BMUs from the map for the given set of data vectors.
wolffd@0: %  som_show      Show map planes.
wolffd@0: %  som_show_add  Add for example labels to the SOM_SHOW visualization.
wolffd@0: 
wolffd@0: % Copyright (c) 1997-2000 by the SOM toolbox programming team.
wolffd@0: % http://www.cis.hut.fi/projects/somtoolbox/
wolffd@0: 
wolffd@0: % Version 1.0beta juuso 101297 
wolffd@0: % Version 2.0beta juuso 101199
wolffd@0: 
wolffd@0: %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
wolffd@0: %% check arguments
wolffd@0: 
wolffd@0: error(nargchk(2, 4, nargin));  % check no. of input args is correct
wolffd@0: 
wolffd@0: % sTo
wolffd@0: todata = strcmp(sTo.type,'som_data');
wolffd@0: 
wolffd@0: % sFrom 
wolffd@0: [dummy m] = size(sFrom.labels);
wolffd@0: 
wolffd@0: % mode
wolffd@0: if nargin<3 | isempty(mode), mode = 'add'; end
wolffd@0: 
wolffd@0: % inds
wolffd@0: if nargin<4, inds = 1:m; end
wolffd@0: inds = inds(find(inds>0 & inds<=m));
wolffd@0:   
wolffd@0: %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
wolffd@0: %% get a list of the labels to be added to each vector
wolffd@0: 
wolffd@0: % calculate BMUs
wolffd@0: if todata, bmus = som_bmus(sFrom,sTo,1);
wolffd@0: else bmus = som_bmus(sTo,sFrom,1); end
wolffd@0: 
wolffd@0: % for each vector in sTo, make a list of all new labels
wolffd@0: Labels = cell(size(sTo.labels,1),1);
wolffd@0: for d=1:length(bmus), 
wolffd@0:   m = bmus(d); 
wolffd@0:   if todata, t = d; f = m; else t = m; f = d; end
wolffd@0:   if ~isnan(m), 
wolffd@0:     % add the labels
wolffd@0:     for j=1:length(inds), 
wolffd@0:       if ~isempty(sFrom.labels{f,inds(j)}), 
wolffd@0:         Labels{t}{length(Labels{t})+1} = sFrom.labels{f,inds(j)}; 
wolffd@0:       end
wolffd@0:     end 
wolffd@0:   end
wolffd@0: end
wolffd@0: 
wolffd@0: %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
wolffd@0: %% insert the labels to sTo
wolffd@0: 
wolffd@0: 
wolffd@0: if strcmp(mode,'add1') | strcmp(mode,'freq') | strcmp(mode,'vote'),
wolffd@0: 
wolffd@0:   % modify the Labels array apprpriately
wolffd@0:   
wolffd@0:   for i=1:length(Labels),
wolffd@0:     
wolffd@0:     % calculate frequency of each label in each node
wolffd@0:     new_labels = {};
wolffd@0:     new_freq = [];
wolffd@0:     for j=1:length(Labels{i}),
wolffd@0:       if isempty(Labels{i}{j}), % ignore
wolffd@0:       elseif ~any(strcmp(Labels{i}{j},new_labels)), % a new one!
wolffd@0: 	k = length(new_labels) + 1;
wolffd@0: 	new_labels{k} = Labels{i}{j};
wolffd@0: 	new_freq(k) = sum(strcmp(new_labels{k},Labels{i}));
wolffd@0:       else, % an old one, ignore       
wolffd@0:       end
wolffd@0:     end
wolffd@0:     
wolffd@0:     % based on frequency, select label(s) to be added 
wolffd@0:     if length(new_labels) > 0,
wolffd@0:       if strcmp(mode,'add1'), 
wolffd@0: 	Labels{i} = new_labels;
wolffd@0:       else
wolffd@0:       
wolffd@0: 	% sort labels according to frequency
wolffd@0: 	[dummy order] = sort(1./(1+new_freq));
wolffd@0: 	new_labels = new_labels(order);
wolffd@0: 	new_freq = new_freq(order);
wolffd@0: 	
wolffd@0: 	switch mode,
wolffd@0: 	 case 'freq', 
wolffd@0: 	  % replace each label with 'label(#)' where # is the frequency
wolffd@0: 	  for j=1:length(new_labels), 
wolffd@0: 	    labf = sprintf('%s(%d)',new_labels{j},new_freq(j));
wolffd@0: 	    new_labels{j} = labf;
wolffd@0: 	  end
wolffd@0: 	  Labels{i} = new_labels;
wolffd@0: 	 case 'vote',
wolffd@0: 	  % place only the one with most votes 
wolffd@0: 	  Labels{i} = {new_labels{1}};
wolffd@0: 	end 
wolffd@0:       end 
wolffd@0:     end
wolffd@0:     
wolffd@0:   end
wolffd@0: 
wolffd@0: end
wolffd@0: 
wolffd@0: sTo = som_label(sTo,'add',[1:length(Labels)]',Labels);
wolffd@0: 
wolffd@0: %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
wolffd@0: 
wolffd@0: 
wolffd@0: 
wolffd@0: