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