som_train_struct

Purpose

 Default values for SOM training parameters.

Syntax

  sT = som_train_struct('argID',value,...);
  sT = som_train_struct(value,...);

Description

 This function is used to give sensible values for SOM training
 parameters and returns a training struct. Often, the parameters
 depend on the properties of the map and the training data. These are
 given as optional arguments to the function. If a partially filled
 train struct is given, its empty fields (field value is [] or '' or
 NaN) are supplimented with default values.

 The training struct has a number of fields which depend on each other
 and the optional arguments in complex ways. The most important argument 
 is 'phase' which can be either 'init', 'train', 'rough' or 'finetune'.

  'init'     Map initialization. 
  'train'    Map training in a onepass operation, as opposed to the
             rough-finetune combination.
  'rough'    Rough organization of the map: large neighborhood, big
             initial value for learning coefficient. Short training.
  'finetune' Finetuning the map after rough organization phase. Small
             neighborhood, learning coefficient is small already at 
             the beginning. Long training.

 The fields of training struct set by this function are listed below.

  '.mask'  Basically, a column vector of ones. But if a previous
           train or map struct is given, it is copied from there.
  '.neigh' Default value is 'gaussian' but if a previous train or map 
           struct is given, it is copied from there.
  '.alpha_type' Default value is 'inv' but if a previous training struct 
           is given, it is copied from there.
  '.alpha_ini' For 'train' and 'rough' phases, this is 0.5, for
           'finetune' it is 0.05.
  '.radius_ini' Depends on the previous training operation and the 
           maximum sidelength of the map ms = max(msize).
           if there isn't one, or it is 'randinit', rad_ini = max(1,ms/2)
           if it is 'lininit', rad_ini = max(1,ms/8)
           otherwise, rad_ini = rad_fin of the previous training
  '.radius_fin' Default value is 1, but if the training phase is
           'rough', rad_fin = max(1,rad_ini/4).
  '.trainlen' For 'train' phase this is 20 x mpd epochs, for 'rough'
           phase 4 x mpd epochs and for 'finetune' 16 x mpd
           epochs, where mpd = munits/dlen. If mpd cannot be
           calculated, it is set to be = 0.5. In any case,
           trainlen is at least one epoch.
  '.algorithm' Default training algorithm is 'batch' and default
           initialization algorithm is 'lininit'.

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.

  'dim'          (scalar) input space dimension
  'dlen'         (scalar) length of the training data
  'data'         (matrix / struct) the training data
  'munits'       (scalar) number of map units
  'msize'        (vector) map size
  'previous'     (struct) previous training struct can be given in 
                  conjunction with 'finetune' phase. 
  'phase'       *(string) training phase: 'init', 'train', 'rough' or 'finetune'
  'algorithm'   *(string) algorithm to use: 'lininit', 'randinit', 
                  'batch' or 'seq'
  'map'         *(struct) If a map struc is given, the last training struct
                  in '.trainhist' field is used as the previous training
                  struct. The map size and input space dimension are 
                  extracted from the map struct.
  'sTrain'      *(struct) a train struct, the empty fields of which are
                  filled with sensible values

Output arguments

  sT     (struct) The training struct.

Examples

  The most important optional argument for the training parameters is
  'phase'. The second most important are 'previous' and/or 'map'. 

  To get default initialization parameters, use: 

    sTrain = som_train_struct('phase','init');
     or
    sTrain = som_train_struct('init');

  To get default training parameters, use: 

    sTrain = som_train_struct('phase','train','data',D,'map',sMap);
     or  
    sTrain = som_train_struct('train','data',D,sMap);
     or
    sTrain = som_train_struct('train','dlen',dlen, ...
                              'msize',sMap.topol.msize,'dim',dim);

  If you want to first rough train and then finetune, do like this: 

   sT1 = som_train_struct('rough','dlen',length(D),sMap); % rough training
   sT2 = som_train_struct('finetune','previous',sT1);     % finetuning

See also