wolffd@0: function sMap = som_map_struct(dim, varargin)
wolffd@0: 
wolffd@0: %SOM_MAP_STRUCT Create map struct. 
wolffd@0: % 
wolffd@0: % sMap = som_map_struct(dim, [[argID,] value, ...])
wolffd@0: %
wolffd@0: %  sMap = som_map_struct(4);
wolffd@0: %  sMap = som_map_struct(4,'msize',[3 4],'hexa','sheet');
wolffd@0: %  sMap = som_map_struct(4,'msize',[3 4 5],'rect','name','a 3D-SOM');
wolffd@0: %  sMap = som_map_struct(4,'msize',[3 4],'bubble','mask',[1 1 1 0]);
wolffd@0: %
wolffd@0: %  Input and output arguments ([]'s are optional): 
wolffd@0: %   dim      (scalar) input space dimension
wolffd@0: %   [argID,  (string) See below. The values which are unambiguous can 
wolffd@0: %    value]  (varies) be given without the preceeding argID.
wolffd@0: %
wolffd@0: %   sMap     (struct) self-organizing map struct
wolffd@0: %
wolffd@0: % Here are the valid argument IDs and corresponding values. The values
wolffd@0: % which are unambiguous (marked with '*') can be given without the
wolffd@0: % preceeding argID.
wolffd@0: %   'mask'       (vector) BMU search mask, size dim x 1
wolffd@0: %   'msize'      (vector) map grid size, default is [0]
wolffd@0: %   'labels'     (string array / cellstr) labels for each map unit, 
wolffd@0: %                 length=prod(msize)
wolffd@0: %   'name'       (string) map name
wolffd@0: %   'comp_names' (string array / cellstr) component names, size dim x 1
wolffd@0: %   'comp_norm'  (cell array) normalization operations for each
wolffd@0: %                 component, size dim x 1. Each cell is either empty, 
wolffd@0: %                 or a cell array of normalization structs.
wolffd@0: %   'topol'     *(struct) topology struct
wolffd@0: %   'som_topol','sTopol' = 'topol'
wolffd@0: %   'lattice'   *(string) map lattice, 'hexa' or 'rect'
wolffd@0: %   'shape'     *(string) map shape, 'sheet', 'cyl' or 'toroid'
wolffd@0: %   'neigh'     *(string) neighborhood function, 'gaussian', 'cutgauss',
wolffd@0: %                 'ep' or 'bubble'
wolffd@0: %
wolffd@0: % For more help, try 'type som_map_struct' or check out online documentation.
wolffd@0: % See also SOM_SET, SOM_INFO, SOM_DATA_STRUCT, SOM_TOPOL_STRUCT, SOM_MAKE.
wolffd@0: 
wolffd@0: %%%%%%%%%%%%% DETAILED DESCRIPTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
wolffd@0: %
wolffd@0: % som_map_struct
wolffd@0: %
wolffd@0: % PURPOSE
wolffd@0: %
wolffd@0: % Creates a self-organizing map structure. 
wolffd@0: %
wolffd@0: % SYNTAX
wolffd@0: %
wolffd@0: %  sM = som_map_struct(dim)
wolffd@0: %  sM = som_map_struct(...,'argID',value,...);
wolffd@0: %  sM = som_map_struct(...,value,...);
wolffd@0: %
wolffd@0: % DESCRIPTION
wolffd@0: %
wolffd@0: % Creates a self-organizing map struct. The struct contains the map
wolffd@0: % codebook, labels, topology, information on normalization and training, 
wolffd@0: % as well as component names and a name for the map. The obligatory
wolffd@0: % parameter is the map dimension. Most of the other fields can be
wolffd@0: % given values using optional arguments. If they are left unspecified,
wolffd@0: % default values are used.
wolffd@0: %
wolffd@0: %  Field         Type         Size / default value (munits = prod(msize))
wolffd@0: %  ------------------------------------------------------------------------
wolffd@0: %   .type        (string)     'som_map'               
wolffd@0: %   .name        (string)     'SOM date'
wolffd@0: %   .codebook    (matrix)     rand(munits, dim)
wolffd@0: %   .topol       (struct)     topology struct, with the following fields
wolffd@0: %     .type         (string)  'som_topol'
wolffd@0: %     .msize        (vector)  size k x 1, [0] 
wolffd@0: %     .lattice      (string)  'hexa' 
wolffd@0: %     .shape        (string)  'sheet'
wolffd@0: %   .labels      (cellstr)    size munits x m, {''; ''; ... ''}
wolffd@0: %   .neigh       (string)     'gaussian'
wolffd@0: %   .mask        (vector)     size dim x 1, [1; 1; ...; 1]
wolffd@0: %   .trainhist   (cell array) size tl x 1, []
wolffd@0: %   .comp_names  (cellstr)    size dim x 1, {'Variable1', 'Variable2', ...}
wolffd@0: %   .comp_norm   (cell array) size dim x 1, {[], [], ... []}
wolffd@0: %
wolffd@0: % '.type' field is the struct identifier. Do not change it.
wolffd@0: % '.name' field is the identifier for the whole map struct
wolffd@0: % '.codebook' field is the codebook matrix, each row corresponds to one unit
wolffd@0: % '.topol' field is the topology of the map. This struct has three fields:
wolffd@0: %   '.msize' field is the dimensions of the map grid. Note that the
wolffd@0: %         matrix notation of indeces is used.
wolffd@0: %   '.lattice' field is the map grid lattice
wolffd@0: %   '.shape' field is the map grid shape
wolffd@0: % '.labels' field contains the labels for each of the vectors. The ith row
wolffd@0: %         of '.labels' contains the labels for ith map unit. Note that 
wolffd@0: %         if some vectors have more labels than others, the others are
wolffd@0: %         are given empty labels ('') to pad the '.labels' array up.
wolffd@0: % '.neigh' field is the neighborhood function. 
wolffd@0: % '.mask' field is the BMU search mask.
wolffd@0: % '.trainhist' field contains information on the training. It is a cell
wolffd@0: %         array of training structs. The first training struct contains
wolffd@0: %         information on initialization, the others on actual trainings. 
wolffd@0: %         If the map has not been initialized, '.trainhist' is empty ([]).
wolffd@0: % '.comp_names' field contains the names of the vector components
wolffd@0: % '.comp_norm' field contains normalization information for each
wolffd@0: %         component. Each cell of '.comp_norm' is itself a cell array of
wolffd@0: %         normalization structs. If no normalizations are performed for 
wolffd@0: %         the particular component, the cell is empty ([]).
wolffd@0: %
wolffd@0: % REQUIRED INPUT ARGUMENTS
wolffd@0: %
wolffd@0: %  dim    (scalar) Input space dimension. 
wolffd@0: %  
wolffd@0: % OPTIONAL INPUT ARGUMENTS 
wolffd@0: %
wolffd@0: %  argID (string) Argument identifier string (see below).
wolffd@0: %  value (varies) Value for the argument (see below).
wolffd@0: %
wolffd@0: %  The optional arguments are given as 'argID',value -pairs. If the
wolffd@0: %  value is unambiguous (marked below with '*'), it can be given
wolffd@0: %  without the preceeding argID. If an argument is given value
wolffd@0: %  multiple times, the last one is used.
wolffd@0: %
wolffd@0: %   'mask'       (vector) BMU search mask, size dim x 1
wolffd@0: %   'msize'      (vector) map grid size, default is [0]
wolffd@0: %   'labels'     (string array / cellstr) labels for each map unit, 
wolffd@0: %                 length=prod(msize)
wolffd@0: %   'name'       (string) map name
wolffd@0: %   'comp_names' (string array / cellstr) component names, size dim x 1
wolffd@0: %   'comp_norm'  (cell array) normalization operations for each
wolffd@0: %                 component, size dim x 1. Each cell is either empty, 
wolffd@0: %                 or a cell array of normalization structs.
wolffd@0: %   'lattice'   *(string) map lattice, 'hexa' or 'rect'
wolffd@0: %   'shape'     *(string) map shape, 'sheet', 'cyl' or 'toroid'
wolffd@0: %   'topol'     *(struct) topology struct, sets msize, lattice and shape
wolffd@0: %   'som_topol','sTopol' = 'topol'
wolffd@0: %   'neigh'     *(string) neighborhood function, 'gaussian', 'cutgauss',
wolffd@0: %                 'ep' or 'bubble'
wolffd@0: %
wolffd@0: % OUTPUT ARGUMENTS
wolffd@0: % 
wolffd@0: %  sMap (struct) the map struct
wolffd@0: %
wolffd@0: % EXAMPLES
wolffd@0: %
wolffd@0: % Simplest case:
wolffd@0: %  sMap = som_map_struct(3);
wolffd@0: %  
wolffd@0: % With optional arguments, the other fields can be given values:
wolffd@0: %  sTo    = som_set('som_topol','msize',[10 5]);
wolffd@0: %  labs   = cell(50, 1); labs{1, 1} = 'first_unit';
wolffd@0: %  cnames = {'first'; 'second'; 'third'};
wolffd@0: %  sN     = som_set('som_norm');
wolffd@0: %  csN    = {sN; sN; sN};
wolffd@0: %  
wolffd@0: %  sMap = som_map_struct(3,'msize',[10 5],'rect');
wolffd@0: %  sMap = som_map_struct(3,'msize',[10 5],'lattice','rect');
wolffd@0: %  sMap = som_map_struct(3,sTo,'bubble','labels',labs);
wolffd@0: %  sMap = som_map_struct(3,sTo,'comp_names',cnames);
wolffd@0: %  sMap = som_map_struct(3,sTo,'name','a data struct');
wolffd@0: %  sMap = som_map_struct(3,sTo,'comp_norm',csN,'mask',[1 0 0.5]);
wolffd@0: %
wolffd@0: % SEE ALSO
wolffd@0: % 
wolffd@0: %  som_set          Set values and create SOM Toolbox structs.
wolffd@0: %  som_data_struct  Create a data struct.
wolffd@0: %  som_make         Initialize and train self-organizing map.
wolffd@0: %  som_topol_struct Default values for map topology.
wolffd@0: 
wolffd@0: % Copyright (c) 1997-2000 by the SOM toolbox programming team.
wolffd@0: % http://www.cis.hut.fi/projects/somtoolbox/
wolffd@0: 
wolffd@0: % Version 1.0beta ecco 100997
wolffd@0: % Version 2.0beta juuso 101199 130300
wolffd@0: 
wolffd@0: %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
wolffd@0: 
wolffd@0: % default values
wolffd@0: sTopol     = som_set('som_topol','lattice','hexa','shape','sheet');
wolffd@0: neigh      = 'gaussian';
wolffd@0: mask       = ones(dim,1);
wolffd@0: name       = sprintf('SOM %s', datestr(now, 1));
wolffd@0: labels     = cell(prod(sTopol.msize),1);
wolffd@0: for i=1:length(labels), labels{i} = ''; end
wolffd@0: comp_names = cell(dim,1); 
wolffd@0: for i = 1:dim, comp_names{i} = sprintf('Variable%d', i); end
wolffd@0: comp_norm  = cell(dim,1); 
wolffd@0: 
wolffd@0: % varargin
wolffd@0: i=1; 
wolffd@0: while i<=length(varargin), 
wolffd@0:   argok = 1; 
wolffd@0:   if ischar(varargin{i}), 
wolffd@0:     switch varargin{i}, 
wolffd@0:       % argument IDs
wolffd@0:      case 'mask',       i=i+1; mask = varargin{i}; 
wolffd@0:      case 'msize',      i=i+1; sTopol.msize = varargin{i}; 
wolffd@0:      case 'labels',     i=i+1; labels = varargin{i};
wolffd@0:      case 'name',       i=i+1; name = varargin{i};
wolffd@0:      case 'comp_names', i=i+1; comp_names = varargin{i}; 
wolffd@0:      case 'comp_norm',  i=i+1; comp_norm = varargin{i};
wolffd@0:      case 'lattice',    i=i+1; sTopol.lattice = varargin{i};
wolffd@0:      case 'shape',      i=i+1; sTopol.shape = varargin{i}; 
wolffd@0:      case {'topol','som_topol','sTopol'}, i=i+1; sTopol = varargin{i};
wolffd@0:      case 'neigh',      i=i+1; neigh = varargin{i};
wolffd@0:       % unambiguous values
wolffd@0:      case {'hexa','rect'}, sTopol.lattice = varargin{i};
wolffd@0:      case {'sheet','cyl','toroid'}, sTopol.shape = varargin{i}; 
wolffd@0:      case {'gaussian','cutgauss','ep','bubble'}, neigh = varargin{i};
wolffd@0:      otherwise argok=0; 
wolffd@0:     end
wolffd@0:   elseif isstruct(varargin{i}) & isfield(varargin{i},'type'), 
wolffd@0:     switch varargin{i}(1).type, 
wolffd@0:      case 'som_topol', sTopol = varargin{i};
wolffd@0:      otherwise argok=0; 
wolffd@0:     end
wolffd@0:   else
wolffd@0:     argok = 0; 
wolffd@0:   end
wolffd@0:   if ~argok, 
wolffd@0:     disp(['(som_map_struct) Ignoring invalid argument #' num2str(i+1)]); 
wolffd@0:   end
wolffd@0:   i = i+1; 
wolffd@0: end
wolffd@0: 
wolffd@0: % create the SOM
wolffd@0: codebook = rand(prod(sTopol.msize),dim); 
wolffd@0: sTrain = som_set('som_train','time',datestr(now,0),'mask',mask);
wolffd@0: sMap = som_set('som_map','codebook',codebook,'topol',sTopol,...
wolffd@0:                          'neigh',neigh,'labels',labels,'mask',mask,...
wolffd@0:                          'comp_names',comp_names,'name',name,...
wolffd@0:                          'comp_norm',comp_norm,'trainhist',sTrain);
wolffd@0: 
wolffd@0: 
wolffd@0: 
wolffd@0: %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%