som_autolabel

Purpose

 Automatically label to map/data structs based on given data/map.

Syntax

  sTo = som_autolabel(sTo, sFrom)
  sTo = som_autolabel(sTo, sFrom, 'add')
  sTo = som_autolabel(sTo, sFrom, 'freq')
  sTo = som_autolabel(sTo, sFrom, 'vote')
  sTo = som_autolabel(..., inds)

Description

 This function automatically labels given map/data struct based on an
 already labelled data/map struct. Basically, the BMU of each vector in the
 sFrom struct is found from among the vectors in sTo, and the vectors in
 sFrom are added to the corresponding vector in the sTo struct. The actual
 labels to add are selected based on the mode ('add', 'freq' or 'vote').

  'add'  :  all labels from sFrom are added to sTo - even if there would 
            be multiple instances of the same label
  'add1' :  only one instance of each label is kept
  'freq' :  only one instance of each label is kept and '(#)', where 
            # is the frequency of the label, is added to the end of 
            the label. Labels are ordered according to frequency. 
  'vote' :  only the label with most instances is added

 Note that these operations do not effect the old labels of sTo: they 
 are left as they were.  

 NOTE: empty labels ('') are ignored.

Required input arguments

   sTo    (struct) data or map struct to which the labels are put 
   sFrom  (struct) data or map struct from which the labels are taken

Optional input arguments

   mode   (string) The mode of operation: 'add' (default), 
                   'add1', 'freq' or 'vote'
   inds   (vector) The columns of the '.labels' field in sFrom to be 
                   used in operation

Output arguments

   sTo    (struct) the given data/map struct with modified labels

Examples

 To label a trained map based on (labelled) training data, just do

  sM = som_autolabel(sM,sD);      

 This operation is sometimes called "calibration" in the literature.
 You can also do this the other way around: use a labelled map to 
 label a data set: 

  sD = som_autolabel(sD,sM);   

 If you only want a single instance of each label, use the 'freq' mode: 

  sM = som_autolabel(sM,sD,'freq');

 If you already have labels in the struct, and want to perform 'freq' on 
 them, do the following: 

  sMtemp = som_label(sM,'clear','all'); % make a map struct with no labels
  sM = som_autolabel(sMtemp,sM,'freq'); % add labels to it

 The third mode 'vote' votes between the labels and only adds the one
 which is most frequent. If two labels are equally frequent, one or the
 other is chosen based on which appears first in the list.

  sM = som_autolabel(sM,sD,'vote');

 The lat argument is useful if you have specific labels in each column
 of the '.labels' field. For example, the first column might be an
 identifier, the next a typecode and the last a year. In this case, you
 might want to label the map based only on the typecode: 

  sM  = som_autolabel(sM,sD,'vote',2);

See also