som_bmus

Purpose

 Finds Best-Matching Units (BMUs) for given data vector from a given map.

Syntax

  Bmus = som_bmus(sMap, sData)
  Bmus = som_bmus(..., which)
  Bmus = som_bmus(..., which, mask)
  [Bmus, Qerrs] = som_bmus(...)

Description

 Returns the indexes and corresponding quantization errors of the
 vectors in sMap that best matched the vectors in sData.

 By default only the index of the best matching unit (/vector) is
 returned, but the 'which' argument can be used to get others as
 well. For example it might be desirable to get also second- and
 third-best matching units as well (which = [1:3]). 

 A mask can be used to weight the search process. The mask is used to
 weight the influence of components in the distance calculation, as
 follows: 

   distance(x,y) = (x-y)' diag(mask) (x-y)

 where x and y are two vectors, and diag(mask) is a diagonal matrix with 
 the elements of mask vector on the diagonal. 

 The vectors in the data set (sData) can contain unknown components
 (NaNs), but the map (sMap) cannot. If there are completely empty
 vectors (all NaNs), the returned BMUs and quantization errors for those 
 vectors are NaNs.

Required input arguments

   sMap              The vectors from among which the BMUs are searched
                     for. These must not have any unknown components (NaNs).
            (struct) map struct
            (matrix) codebook matrix, size munits x dim

   sData             The data vector(s) for which the BMUs are searched.
            (struct) data struct
            (matrix) data matrix, size dlen x dim

Optional input arguments

   which    (vector) which BMUs are returned, 
                     by default only the best (ie. which = [1])
            (string) 'all', 'best' or 'worst' meaning [1:munits],
                     [1] and [munits] respectively  
   mask     (vector) mask vector to be used in BMU search, 
                     by default sMap.mask, or ones(dim,1) in case
                     a matrix was given

Output arguments

   Bmus     (matrix) the requested BMUs for each data vector, 
                     size dlen x length(which)
   Qerrors  (matrix) the corresponding quantization errors, 
                     size equal to that of Bmus

Examples

 Simplest case:
  bmu = som_bmus(sM, [0.3 -0.4 1.0]);
           % 3-dimensional data, returns BMU for vector [0.3 -0.4 1]
  bmu = som_bmus(sM, [0.3 -0.4 1.0], [3 5]);
           % as above, except returns the 3rd and 5th BMUs
  bmu = som_bmus(sM, [0.3 -0.4 1.0], [], [1 0 1]);
           % as above, except ignores second component in searching
  [bmus qerrs] = som_bmus(sM, D);
           % returns BMUs and corresponding quantization errors 
           % for each vector in D
  bmus = som_bmus(sM, sD);
           % returns BMUs for each vector in sD using the mask in sM

See also