som_make

Purpose

 Creates, initializes and trains a SOM using default parameters.

Syntax

  sMap = som_make(D);
  sMap = som_make(...,'argID',value,...);
  sMap = som_make(...,value,...);

Description

 Creates, initializes and trains a SOM with default parameters. Uses functions
 SOM_TOPOL_STRUCT, SOM_TRAIN_STRUCT, SOM_DATA_STRUCT and SOM_MAP_STRUCT to come
 up with the default values.

 First, the number of map units is determined. Unless they are
 explicitly defined, function SOM_TOPOL_STRUCT is used to determine this.
 It uses a heuristic formula of 'munits = 5*dlen^0.54321'. The 'mapsize'
 argument influences the final number of map units: a 'big' map has 
 x4 the default number of map units and a 'small' map has x0.25 the
 default number of map units. 

 After the number of map units has been determined, the map size is 
 determined. Basically, the two biggest eigenvalues of the training
 data are calculated and the ratio between sidelengths of the map grid
 is set to this ratio. The actual sidelengths are then set so that 
 their product is as close to the desired number of map units as
 possible.

 Then the SOM is initialized. First, linear initialization along two
 greatest eigenvectors is tried, but if this can't be done (the
 eigenvectors cannot be calculated), random initialization is used
 instead.  After initialization, the SOM is trained in two phases:
 first rough training and then fine-tuning. If the 'tracking'
 argument is greater than zero, the average quantization error and
 topographic error of the final map are calculated.

Required input arguments

  D           The data to use in the training.
     (struct) A data struct. If a struct is given, '.comp_names' field as 
              well as '.comp_norm' field is copied to the map struct.
     (matrix) A data matrix, size dlen x dim. The data matrix may
              contain unknown values, indicated by NaNs. 

Optional input arguments

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

 Here are the valid argument IDs and corresponding values. The values 
 which are unambiguous (marked with '*') can be given without the
 preceeding argID.
   'init'       *(string) initialization: 'randinit' or 'lininit' (default)
   'algorithm'  *(string) training: 'seq' or 'batch' (default) or 'sompak'
   'munits'      (scalar) the preferred number of map units
   'msize'       (vector) map grid size
   'mapsize'    *(string) do you want a 'small', 'normal' or 'big' map
                          Any explicit settings of munits or msize override this.
   'lattice'    *(string) map lattice, 'hexa' or 'rect'
   'shape'      *(string) map shape, 'sheet', 'cyl' or 'toroid'
   'neigh'      *(string) neighborhood function, 'gaussian', 'cutgauss',
                          'ep' or 'bubble'
   'topol'      *(struct) topology struct
   'som_topol','sTopol' = 'topol'
   'mask'        (vector) BMU search mask, size dim x 1
   'name'        (string) map name
   'comp_names'  (string array / cellstr) component names, size dim x 1
   'tracking'    (scalar) how much to report, default = 1
   'training'    (string) 'short', 'default' or 'long'
                 (vector) size 1 x 2, first length of rough training in epochs, 
                          and then length of finetuning in epochs

Output arguments

  sMap (struct) the trained map struct

Examples

  To simply train a map with default parameters: 

   sMap = som_make(D); 

  With the optional arguments, the initialization and training can be
  influenced. To change map size, use 'msize', 'munits' or 'mapsize'
  arguments:  

   sMap = som_make(D,'mapsize','big'); or sMap=som_make(D,'big');
   sMap = som_make(D,'munits', 100);
   sMap = som_make(D,'msize', [20 10]); 

  Argument 'algorithm' can be used to switch between 'seq' and 'batch'
  algorithms. 'batch' is the default, so to use 'seq' algorithm: 

   sMap = som_make(D,'algorithm','seq'); or sMap = som_make(D,'seq'); 

  The 'tracking' argument can be used to control the amout of reporting
  during training. The argument is used in this function, and it is
  passed to the training functions. To make the function work silently
  set it to 0.

   sMap = som_make(D,'tracking',0); 

See also