som_map_struct

Purpose

 Creates a self-organizing map structure. 

Syntax

  sM = som_map_struct(dim)
  sM = som_map_struct(...,'argID',value,...);
  sM = som_map_struct(...,value,...);

Description

 Creates a self-organizing map struct. The struct contains the map
 codebook, labels, topology, information on normalization and training, 
 as well as component names and a name for the map. The obligatory
 parameter is the map dimension. Most of the other fields can be
 given values using optional arguments. If they are left unspecified,
 default values are used.

  Field         Type         Size / default value (munits = prod(msize))
  ------------------------------------------------------------------------
   .type        (string)     'som_map'               
   .name        (string)     'SOM date'
   .codebook    (matrix)     rand(munits, dim)
   .topol       (struct)     topology struct, with the following fields
     .type         (string)  'som_topol'
     .msize        (vector)  size k x 1, [0] 
     .lattice      (string)  'hexa' 
     .shape        (string)  'sheet'
   .labels      (cellstr)    size munits x m, {''; ''; ... ''}
   .neigh       (string)     'gaussian'
   .mask        (vector)     size dim x 1, [1; 1; ...; 1]
   .trainhist   (cell array) size tl x 1, []
   .comp_names  (cellstr)    size dim x 1, {'Variable1', 'Variable2', ...}
   .comp_norm   (cell array) size dim x 1, {[], [], ... []}

 '.type' field is the struct identifier. Do not change it.
 '.name' field is the identifier for the whole map struct
 '.codebook' field is the codebook matrix, each row corresponds to one unit
 '.topol' field is the topology of the map. This struct has three fields:
   '.msize' field is the dimensions of the map grid. Note that the
         matrix notation of indeces is used.
   '.lattice' field is the map grid lattice
   '.shape' field is the map grid shape
 '.labels' field contains the labels for each of the vectors. The ith row
         of '.labels' contains the labels for ith map unit. Note that 
         if some vectors have more labels than others, the others are
         are given empty labels ('') to pad the '.labels' array up.
 '.neigh' field is the neighborhood function. 
 '.mask' field is the BMU search mask.
 '.trainhist' field contains information on the training. It is a cell
         array of training structs. The first training struct contains
         information on initialization, the others on actual trainings. 
         If the map has not been initialized, '.trainhist' is empty ([]).
 '.comp_names' field contains the names of the vector components
 '.comp_norm' field contains normalization information for each
         component. Each cell of '.comp_norm' is itself a cell array of
         normalization structs. If no normalizations are performed for 
         the particular component, the cell is empty ([]).

Required input arguments

  dim    (scalar) Input space dimension. 

Optional input arguments

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

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

   'mask'       (vector) BMU search mask, size dim x 1
   'msize'      (vector) map grid size, default is [0]
   'labels'     (string array / cellstr) labels for each map unit, 
                 length=prod(msize)
   'name'       (string) map name
   'comp_names' (string array / cellstr) component names, size dim x 1
   'comp_norm'  (cell array) normalization operations for each
                 component, size dim x 1. Each cell is either empty, 
                 or a cell array of normalization structs.
   'lattice'   *(string) map lattice, 'hexa' or 'rect'
   'shape'     *(string) map shape, 'sheet', 'cyl' or 'toroid'
   'topol'     *(struct) topology struct, sets msize, lattice and shape
   'som_topol','sTopol' = 'topol'
   'neigh'     *(string) neighborhood function, 'gaussian', 'cutgauss',
                 'ep' or 'bubble'

Output arguments

  sMap (struct) the map struct

Examples

 Simplest case:
  sMap = som_map_struct(3);

 With optional arguments, the other fields can be given values:
  sTo    = som_set('som_topol','msize',[10 5]);
  labs   = cell(50, 1); labs{1, 1} = 'first_unit';
  cnames = {'first'; 'second'; 'third'};
  sN     = som_set('som_norm');
  csN    = {sN; sN; sN};

  sMap = som_map_struct(3,'msize',[10 5],'rect');
  sMap = som_map_struct(3,'msize',[10 5],'lattice','rect');
  sMap = som_map_struct(3,sTo,'bubble','labels',labs);
  sMap = som_map_struct(3,sTo,'comp_names',cnames);
  sMap = som_map_struct(3,sTo,'name','a data struct');
  sMap = som_map_struct(3,sTo,'comp_norm',csN,'mask',[1 0 0.5]);

See also