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

first hg version after svn

+function [sTo] = som_label(sTo, mode, inds, labels)
+
+%SOM_LABEL Give/clear labels to/from map or data struct.
+%
+% sTo = som_label(sTo, mode, inds [, labels])
+% 
+%   sD = som_label(sD,'add',20,'a_label');
+%   sM = som_label(sM,'replace',[2 4],'a_label');
+%   sM = som_label(sM,'add',som_bmus(sM,x),'BMU');
+%   sD = som_label(sD,'prune',[1:10]');
+%   sM = som_label(sM,'clear','all');         
+%
+%  Input and output arguments ([]'s are optional): 
+%   sTo      (struct) data or map struct to which the labels are put 
+%   mode     (string) 'add' or 'replace' or 'prune' or 'clear'
+%   inds     (vector) indeces of the vectors to which the labels
+%                     are put. Note: this must be a column vector!
+%            (matrix) subscript indeces to the '.labels' field. The vector 
+%                     is given by the first index (e.g. inds(i,1)). 
+%            (string) for 'prune' and 'clear' modes, the string 'all'
+%                     means that all vectors should be pruned/cleared
+%   [labels]          The labels themselves. The number of rows much match 
+%                     the number of given indeces, except if there is either
+%                     only one index or only one label. If mode is
+%                     'prune' or 'clear', labels argument is ignored.
+%            (string) Label.
+%            (string array) Each row is a label.
+%            (cell array of strings) All labels in a cell are handled 
+%                     as a group and are applied to the same vector given 
+%                     on the corresponding row of inds.
+%
+% Note: If there is only one label/index, it is used for each specified
+% index/label.
+%
+% For more help, try 'type som_label' or check out online documentation.
+% See also  SOM_AUTOLABEL, SOM_SHOW_ADD, SOM_SHOW.
+
+%%%%%%%%%%%%% DETAILED DESCRIPTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% som_label
+%
+% PURPOSE
+%
+% Add (or remove) labels to (from) map and data structs.
+%
+% SYNTAX
+%
+%  sTo = som_label(sTo, 'clear', inds)
+%  sTo = som_label(sTo, 'prune', inds)
+%  sTo = som_label(sTo, 'add', inds, labels)
+%  sTo = som_label(sTo, 'replace', inds, labels)
+%
+% DESCRIPTION
+%
+% This function can be used to give and remove labels in map and data
+% structs. Of course the same operation could be done by hand, but this
+% function offers an alternative and hopefully slightly user-friendlier
+% way to do it.
+%
+% REQUIRED INPUT ARGUMENTS
+%
+%   sTo    (struct) data or map struct to which the labels are put 
+%   mode   (string) The mode of operation. 
+%                    'add'     : adds the given labels
+%                    'clear'   : removes labels
+%                    'replace' : replaces current labels with given
+%                                labels; basically same as 'clear'
+%                                followed by 'add'
+%                    'prune'   : removes empty labels ('') from between
+%                                non-empty labels, e.g. if the labels of
+%                                a vector were {'A','','','B','','C'}
+%                                they'd become {'A','B','C'}. Some empty
+%                                labels may be left at the end of the list.
+%
+%   inds            Identifies the vectors to which the operation
+%                   (given by mode) is applied to.
+%          (vector) Linear indexes of the vectors, size n x 1.
+%                   Notice! This should be a column vector!
+%          (matrix) The labels are in a cell matrix. By giving matrix 
+%                   argument for inds, you can address this matrix
+%                   directly. The first index gives the vector and the
+%                   second index the vertical position of the label in
+%                   the labels array. Size n x 2, where n is the 
+%                   number of labels. 
+%          (string) for 'prune' and 'clear' modes, the string 'all'
+%                   means that all vectors should be pruned/cleared
+%
+% OPTIONAL INPUT ARGUMENTS 
+%
+%   [labels]        The labels themselves. The number of rows much match 
+%                   the number of given indeces, except if there is either
+%                   only one index or only one label. 
+%          (string) Label, e.g. 'label'
+%          (string array) Each row is a label, 
+%                   e.g. ['label1'; 'label2'; 'label3']
+%          (cell array of strings) All labels in a cell are handled 
+%                   as a group and are applied to the same vector given 
+%                   on the corresponding row of inds.
+%                   e.g. three labels: {'label1'; 'label2'; 'label3'}
+%                   e.g. a group of labels: {'label1', 'label2', 'label3'}
+%                   e.g. three groups: {{'la1'},{'la21','la22'},{'la3'}
+%
+% OUTPUT ARGUMENTS
+% 
+%   sTo    (struct) the given data/map struct with modified labels
+% 
+% EXAMPLES
+%
+%  This is the basic way to add a label to map structure:
+%   sMap = som_label(sMap,'add',3,'label');
+%
+%  The following examples have identical results: 
+%   sMap = som_label(sMap,'add',[4; 13], ['label1'; 'label2']);
+%   sMap = som_label(sMap,'add',[4; 13], {{'label1'};{'label2'}});
+%
+%  Labeling the BMU of a vector x (and removing any old labels)
+%   sMap = som_label(sMap,'replace',som_bmus(sMap,x),'BMU');
+%
+%  Pruning labels 
+%   sMap = som_label(sMap,'prune','all');
+%
+%  Clearing labels from a struct
+%   sMap = som_label(sMap,'clear','all');
+%   sMap = som_label(sMap,'clear',[1:4, 9:30]');
+%
+% SEE ALSO
+% 
+%  som_autolabel   Automatically label a map/data set.
+%  som_show        Show map planes.
+%  som_show_add    Add for example labels to the SOM_SHOW visualization.
+
+% Copyright (c) 1997-2000 by the SOM toolbox programming team.
+% http://www.cis.hut.fi/projects/somtoolbox/
+
+% Version 2.0beta juuso 101199
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% check arguments
+
+error(nargchk(3, 4, nargin));  % check no. of input args is correct
+
+% sTo
+switch sTo.type, 
+case 'som_map',  [dlen dim] = size(sTo.codebook);
+case 'som_data', [dlen dim] = size(sTo.data);
+end
+maxl = size(sTo.labels,2); % maximum number of labels for a single vector
+
+% inds
+if ischar(inds) & strcmp(inds,'all'), 
+  inds = [1:dlen]'; 
+end
+if length(inds)>2 & size(inds,2)>2, inds = inds'; end
+ni = size(inds,1);
+n = ni; 
+
+% labels
+if nargin==4, 
+  % convert labels to a cell array of cells
+  if ischar(labels), labels = cellstr(labels); end
+  if iscellstr(labels), 
+    tmplab = labels; 
+    nl = size(labels,1);
+    labels = cell(nl,1);  
+    for i=1:nl, 
+      if ~iscell(tmplab{i}) 
+	if ~isempty(tmplab{i}), labels{i} = tmplab(i,:);
+	else labels{i} = {}; end
+      else
+	labels(i) = tmplab(i);
+      end
+    end
+    clear tmplab;
+  end
+  nl = size(labels,1);    
+end
+
+% the case of a single label/index
+if any(strcmp(mode,{'add','replace'})),
+  n = max(nl,ni);   
+  if n>1, 
+    if ni==1, 
+      inds = zeros(n,1)+inds(1); 
+    elseif nl==1,
+      label = labels{1}; 
+      labels = cell(n,1); 
+      for i=1:n, labels{i} = label; end
+    elseif ni ~= nl,
+      error('The number of labels and indexes does not match.'); 
+    end
+  end
+end
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% action
+
+switch mode,   
+ case 'clear',
+  if size(inds,2)>2, 
+    inds = inds(find(inds(:,2)<=maxl),:); % ignore if subindex is out-of-range
+    inds = sub2ind([dlen maxl],inds(:,1),inds(:,2)); 
+    sTo.labels{inds} = []; 
+  else
+    sTo.labels(inds,:) = cell(n,maxl); 
+  end
+ case 'prune', 
+  if size(inds,2)==1, 
+    % subindex gives the index from which the pruning is started
+    inds = [inds, ones(n,1)]; % from 1 by default
+  end 
+  select = ones(1,maxl);     
+  for i=1:n, 
+    v = inds(i,1); s = inds(i,2); select(:) = 1; 
+    for j=s:maxl, select(j) = ~isempty(sTo.labels{v,j}); end
+    if ~all(select), 
+      labs = cell(1,maxl); 
+      labs(1:sum(select)) = sTo.labels(v,find(select));
+      sTo.labels(v,:) = labs; 
+    end
+  end
+ case 'add', 
+  if size(inds,2)==1, 
+    % subindex gives the index from which the adding is started
+    inds = [inds, ones(n,1)]; % from 1 by default
+  end 
+  for i=1:n, 
+    v = inds(i,1); s = inds(i,2); l = length(labels{i});
+    for j=1:l, 
+      while s<=size(sTo.labels,2) & ~isempty(sTo.labels{v,s}), s=s+1; end
+      sTo.labels{v,s} = labels{i}{j}; 
+      s=s+1; 
+    end
+  end
+ case 'replace', 
+  if size(inds,2)==1, 
+    % subindex gives the index from which the replacing is started
+    inds = [inds, ones(n,1)]; % from 1 by default
+  end 
+  for i=1:n, 
+    v = inds(i,1); s = inds(i,2); l = length(labels(i)); 
+    for j=1:l, sTo.labels{v,s-1+j} = labels{i}{j}; end 
+  end
+ otherwise
+  error(['Unrecognized mode: ' mode]);
+end
+
+sTo.labels = remove_empty_columns(sTo.labels);
+
+[dlen maxl] = size(sTo.labels);
+for i=1:dlen, 
+  for j=1:maxl, 
+    if isempty(sTo.labels{i,j}) & ~ischar(sTo.labels{i,j}), 
+      sTo.labels{i,j} = ''; 
+    end
+  end
+end
+
+return;
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% subfunctions
+
+function labels = remove_empty_columns(labels)
+
+  [dlen maxl] = size(labels);
+  
+  % find which columns are empty
+  cols = zeros(1,maxl); 
+  for i=1:dlen, 
+    for j=1:maxl,
+      cols(j) = cols(j) + ~isempty(labels{i,j}); 
+    end
+  end
+  while maxl>0 & cols(maxl)==0, maxl = maxl-1; end % check starting from end
+
+  if maxl==0, labels = cell(dlen,1); 
+  elseif maxl<size(labels,2), labels = labels(:,1:maxl); 
+  else % ok
+  end
+  % end of remove_empty_columns
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%