SOM Toolbox Online documentation



 Trains a Self-Organizing Map using the batch algorithm. 



 Trains the given SOM (sM or M above) with the given training data
 (sD or D) using batch training algorithm.  If no optional arguments
 (argID, value) are given, a default training is done. Using optional
 arguments the training parameters can be specified. Returns the
 trained and updated SOM and a train struct which contains
 information on the training.


 Kohonen, T., "Self-Organizing Map", 2nd ed., Springer-Verlag, 
    Berlin, 1995, pp. 127-128.
 Kohonen, T., "Things you haven't heard about the Self-Organizing
    Map", In proceedings of International Conference
    on Neural Networks (ICNN), San Francisco, 1993, pp. 1147-1156.

Known bugs

 Batchtrain does not work correctly for a map with a single unit. 
 This is because of the way 'min'-function works. 

Required input arguments

  sM          The map to be trained. 
     (struct) map struct
     (matrix) codebook matrix (field .data of map struct)
              Size is either [munits dim], in which case the map grid 
              dimensions (msize) should be specified with optional arguments,
              or [msize(1) ... msize(k) dim] in which case the map 
              grid dimensions are taken from the size of the matrix. 
              Lattice, by default, is 'rect' and shape 'sheet'.
  D           Training data.
     (struct) data struct
     (matrix) data matrix, size [dlen dim]

Optional input arguments

  argID (string) Argument identifier string (see below).
  value (varies) Value for the argument (see below).

  The optional arguments can be given as 'argID',value -pairs. If an
  argument is given value multiple times, the last one is
  used. The valid IDs and corresponding values are listed below. The values 
  which are unambiguous (marked with '*') can be given without the 
  preceeding argID.

  Below is the list of valid arguments: 
   'mask'       (vector) BMU search mask, size dim x 1. Default is 
                         the one in sM (field '.mask') or a vector of
                         ones if only a codebook matrix was given.
   'msize'      (vector) map grid dimensions. Default is the one
                         in sM (field sM.topol.msize) or 
                         'si = size(sM); msize = si(1:end-1);' 
                         if only a codebook matrix was given. 
   'radius'     (vector) neighborhood radius 
                         length = 1: radius_ini = radius
                         length = 2: [radius_ini radius_fin] = radius
                         length > 2: the vector given neighborhood
                                     radius for each step separately
                                     trainlen = length(radius)
   'radius_ini' (scalar) initial training radius
   'radius_fin' (scalar) final training radius
   'tracking'   (scalar) tracking level: 0, 1 (default), 2 or 3
                         0 - estimate time 
                         1 - track time and quantization error 
                         2 - plot quantization error
                         3 - plot quantization error and two first 
   'trainlen'   (scalar) training length in epochs
   'train'     *(struct) train struct, parameters for training. 
                         Default parameters, unless specified, 
                         are acquired using SOM_TRAIN_STRUCT (this 
                         also applies for 'trainlen', 'radius_ini' 
                         and 'radius_fin').
   'sTrain', 'som_topol' (struct) = 'train'
   'neigh'     *(string) The used neighborhood function. Default is 
                         the one in sM (field '.neigh') or 'gaussian'
                         if only a codebook matrix was given. Other 
                         possible values is 'cutgauss', 'ep' and 'bubble'.
   'topol'     *(struct) topology of the map. Default is the one
                         in sM (field '.topol').
   'sTopol', 'som_topol' (struct) = 'topol'
   'lattice'   *(string) map lattice. Default is the one in sM
                         (field sM.topol.lattice) or 'rect' 
                         if only a codebook matrix was given. 
   'shape'     *(string) map shape. Default is the one in sM
                         (field sM.topol.shape) or 'sheet' 
                         if only a codebook matrix was given. 
   'weights'    (vector) weight for each data vector: during training, 
                         each data sample is weighted with the corresponding
                         value, for example giving weights = [1 1 2 1] 
                         would have the same result as having third sample
                         appear 2 times in the data

Output arguments

  sM          the trained map
     (struct) if a map struct was given as input argument, a 
              map struct is also returned. The current training 
              is added to the training history (sM.trainhist).
              The 'neigh' and 'mask' fields of the map struct
              are updated to match those of the training.
     (matrix) if a matrix was given as input argument, a matrix
              is also returned with the same size as the input 
  sT (struct) train struct; information of the accomplished training


 Simplest case:
  sM = som_batchtrain(sM,D);  
  sM = som_batchtrain(sM,sD);  

 To change the tracking level, 'tracking' argument is specified:
  sM = som_batchtrain(sM,D,'tracking',3);

 The change training parameters, the optional arguments 'train','neigh',
 'mask','trainlen','radius','radius_ini' and 'radius_fin' are used. 
  sM = som_batchtrain(sM,D,'neigh','cutgauss','trainlen',10,'radius_fin',0);

 Another way to specify training parameters is to create a train struct:
  sTrain = som_train_struct(sM,'dlen',size(D,1));
  sTrain = som_set(sTrain,'neigh','cutgauss');
  sM = som_batchtrain(sM,D,sTrain);

 By default the neighborhood radius goes linearly from radius_ini to
 radius_fin. If you want to change this, you can use the 'radius' argument
 to specify the neighborhood radius for each step separately:
  sM = som_batchtrain(sM,D,'radius',[5 3 1 1 1 1 0.5 0.5 0.5]);

 You don't necessarily have to use the map struct, but you can operate
 directly with codebook matrices. However, in this case you have to
 specify the topology of the map in the optional arguments. The
 following commads are identical (M is originally a 200 x dim sized matrix):
  M = som_batchtrain(M,D,'msize',[20 10],'lattice','hexa','shape','cyl');
  M = som_batchtrain(M,D,'msize',[20 10],'hexa','cyl');
  sT= som_set('som_topol','msize',[20 10],'lattice','hexa','shape','cyl');
  M = som_batchtrain(M,D,sT);
  M = reshape(M,[20 10 dim]);
  M = som_batchtrain(M,D,'hexa','cyl');

 The som_batchtrain also returns a train struct with information on the 
 accomplished training. This struct is also added to the end of the 
 trainhist field of map struct, in case a map struct was given.
  [M,sTrain] = som_batchtrain(M,D,'msize',[20 10]);
  [sM,sTrain] = som_batchtrain(sM,D); % sM.trainhist{end}==sTrain

See also

som_make Initialize and train a SOM using default parameters.
som_seqtrain Train SOM with sequential algorithm.
som_train_struct Determine default training parameters.