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