Mercurial > hg > camir-aes2014

annotate toolboxes/MIRtoolbox1.3.2/somtoolbox/som_map_struct.m @ 0:e9a9cd732c1e tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
first hg version after svn
author wolffd
date Tue, 10 Feb 2015 15:05:51 +0000
parents
children
rev   line source
wolffd@0 1 function sMap = som_map_struct(dim, varargin)
wolffd@0 2
wolffd@0 3 %SOM_MAP_STRUCT Create map struct.
wolffd@0 4 %
wolffd@0 5 % sMap = som_map_struct(dim, [[argID,] value, ...])
wolffd@0 6 %
wolffd@0 7 % sMap = som_map_struct(4);
wolffd@0 8 % sMap = som_map_struct(4,'msize',[3 4],'hexa','sheet');
wolffd@0 9 % sMap = som_map_struct(4,'msize',[3 4 5],'rect','name','a 3D-SOM');
wolffd@0 10 % sMap = som_map_struct(4,'msize',[3 4],'bubble','mask',[1 1 1 0]);
wolffd@0 11 %
wolffd@0 12 % Input and output arguments ([]'s are optional):
wolffd@0 13 % dim (scalar) input space dimension
wolffd@0 14 % [argID, (string) See below. The values which are unambiguous can
wolffd@0 15 % value] (varies) be given without the preceeding argID.
wolffd@0 16 %
wolffd@0 17 % sMap (struct) self-organizing map struct
wolffd@0 18 %
wolffd@0 19 % Here are the valid argument IDs and corresponding values. The values
wolffd@0 20 % which are unambiguous (marked with '*') can be given without the
wolffd@0 21 % preceeding argID.
wolffd@0 22 % 'mask' (vector) BMU search mask, size dim x 1
wolffd@0 23 % 'msize' (vector) map grid size, default is [0]
wolffd@0 24 % 'labels' (string array / cellstr) labels for each map unit,
wolffd@0 25 % length=prod(msize)
wolffd@0 26 % 'name' (string) map name
wolffd@0 27 % 'comp_names' (string array / cellstr) component names, size dim x 1
wolffd@0 28 % 'comp_norm' (cell array) normalization operations for each
wolffd@0 29 % component, size dim x 1. Each cell is either empty,
wolffd@0 30 % or a cell array of normalization structs.
wolffd@0 31 % 'topol' *(struct) topology struct
wolffd@0 32 % 'som_topol','sTopol' = 'topol'
wolffd@0 33 % 'lattice' *(string) map lattice, 'hexa' or 'rect'
wolffd@0 34 % 'shape' *(string) map shape, 'sheet', 'cyl' or 'toroid'
wolffd@0 35 % 'neigh' *(string) neighborhood function, 'gaussian', 'cutgauss',
wolffd@0 36 % 'ep' or 'bubble'
wolffd@0 37 %
wolffd@0 38 % For more help, try 'type som_map_struct' or check out online documentation.
wolffd@0 39 % See also SOM_SET, SOM_INFO, SOM_DATA_STRUCT, SOM_TOPOL_STRUCT, SOM_MAKE.
wolffd@0 40
wolffd@0 41 %%%%%%%%%%%%% DETAILED DESCRIPTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
wolffd@0 42 %
wolffd@0 43 % som_map_struct
wolffd@0 44 %
wolffd@0 45 % PURPOSE
wolffd@0 46 %
wolffd@0 47 % Creates a self-organizing map structure.
wolffd@0 48 %
wolffd@0 49 % SYNTAX
wolffd@0 50 %
wolffd@0 51 % sM = som_map_struct(dim)
wolffd@0 52 % sM = som_map_struct(...,'argID',value,...);
wolffd@0 53 % sM = som_map_struct(...,value,...);
wolffd@0 54 %
wolffd@0 55 % DESCRIPTION
wolffd@0 56 %
wolffd@0 57 % Creates a self-organizing map struct. The struct contains the map
wolffd@0 58 % codebook, labels, topology, information on normalization and training,
wolffd@0 59 % as well as component names and a name for the map. The obligatory
wolffd@0 60 % parameter is the map dimension. Most of the other fields can be
wolffd@0 61 % given values using optional arguments. If they are left unspecified,
wolffd@0 62 % default values are used.
wolffd@0 63 %
wolffd@0 64 % Field Type Size / default value (munits = prod(msize))
wolffd@0 65 % ------------------------------------------------------------------------
wolffd@0 66 % .type (string) 'som_map'
wolffd@0 67 % .name (string) 'SOM date'
wolffd@0 68 % .codebook (matrix) rand(munits, dim)
wolffd@0 69 % .topol (struct) topology struct, with the following fields
wolffd@0 70 % .type (string) 'som_topol'
wolffd@0 71 % .msize (vector) size k x 1, [0]
wolffd@0 72 % .lattice (string) 'hexa'
wolffd@0 73 % .shape (string) 'sheet'
wolffd@0 74 % .labels (cellstr) size munits x m, {''; ''; ... ''}
wolffd@0 75 % .neigh (string) 'gaussian'
wolffd@0 76 % .mask (vector) size dim x 1, [1; 1; ...; 1]
wolffd@0 77 % .trainhist (cell array) size tl x 1, []
wolffd@0 78 % .comp_names (cellstr) size dim x 1, {'Variable1', 'Variable2', ...}
wolffd@0 79 % .comp_norm (cell array) size dim x 1, {[], [], ... []}
wolffd@0 80 %
wolffd@0 81 % '.type' field is the struct identifier. Do not change it.
wolffd@0 82 % '.name' field is the identifier for the whole map struct
wolffd@0 83 % '.codebook' field is the codebook matrix, each row corresponds to one unit
wolffd@0 84 % '.topol' field is the topology of the map. This struct has three fields:
wolffd@0 85 % '.msize' field is the dimensions of the map grid. Note that the
wolffd@0 86 % matrix notation of indeces is used.
wolffd@0 87 % '.lattice' field is the map grid lattice
wolffd@0 88 % '.shape' field is the map grid shape
wolffd@0 89 % '.labels' field contains the labels for each of the vectors. The ith row
wolffd@0 90 % of '.labels' contains the labels for ith map unit. Note that
wolffd@0 91 % if some vectors have more labels than others, the others are
wolffd@0 92 % are given empty labels ('') to pad the '.labels' array up.
wolffd@0 93 % '.neigh' field is the neighborhood function.
wolffd@0 94 % '.mask' field is the BMU search mask.
wolffd@0 95 % '.trainhist' field contains information on the training. It is a cell
wolffd@0 96 % array of training structs. The first training struct contains
wolffd@0 97 % information on initialization, the others on actual trainings.
wolffd@0 98 % If the map has not been initialized, '.trainhist' is empty ([]).
wolffd@0 99 % '.comp_names' field contains the names of the vector components
wolffd@0 100 % '.comp_norm' field contains normalization information for each
wolffd@0 101 % component. Each cell of '.comp_norm' is itself a cell array of
wolffd@0 102 % normalization structs. If no normalizations are performed for
wolffd@0 103 % the particular component, the cell is empty ([]).
wolffd@0 104 %
wolffd@0 105 % REQUIRED INPUT ARGUMENTS
wolffd@0 106 %
wolffd@0 107 % dim (scalar) Input space dimension.
wolffd@0 108 %
wolffd@0 109 % OPTIONAL INPUT ARGUMENTS
wolffd@0 110 %
wolffd@0 111 % argID (string) Argument identifier string (see below).
wolffd@0 112 % value (varies) Value for the argument (see below).
wolffd@0 113 %
wolffd@0 114 % The optional arguments are given as 'argID',value -pairs. If the
wolffd@0 115 % value is unambiguous (marked below with '*'), it can be given
wolffd@0 116 % without the preceeding argID. If an argument is given value
wolffd@0 117 % multiple times, the last one is used.
wolffd@0 118 %
wolffd@0 119 % 'mask' (vector) BMU search mask, size dim x 1
wolffd@0 120 % 'msize' (vector) map grid size, default is [0]
wolffd@0 121 % 'labels' (string array / cellstr) labels for each map unit,
wolffd@0 122 % length=prod(msize)
wolffd@0 123 % 'name' (string) map name
wolffd@0 124 % 'comp_names' (string array / cellstr) component names, size dim x 1
wolffd@0 125 % 'comp_norm' (cell array) normalization operations for each
wolffd@0 126 % component, size dim x 1. Each cell is either empty,
wolffd@0 127 % or a cell array of normalization structs.
wolffd@0 128 % 'lattice' *(string) map lattice, 'hexa' or 'rect'
wolffd@0 129 % 'shape' *(string) map shape, 'sheet', 'cyl' or 'toroid'
wolffd@0 130 % 'topol' *(struct) topology struct, sets msize, lattice and shape
wolffd@0 131 % 'som_topol','sTopol' = 'topol'
wolffd@0 132 % 'neigh' *(string) neighborhood function, 'gaussian', 'cutgauss',
wolffd@0 133 % 'ep' or 'bubble'
wolffd@0 134 %
wolffd@0 135 % OUTPUT ARGUMENTS
wolffd@0 136 %
wolffd@0 137 % sMap (struct) the map struct
wolffd@0 138 %
wolffd@0 139 % EXAMPLES
wolffd@0 140 %
wolffd@0 141 % Simplest case:
wolffd@0 142 % sMap = som_map_struct(3);
wolffd@0 143 %
wolffd@0 144 % With optional arguments, the other fields can be given values:
wolffd@0 145 % sTo = som_set('som_topol','msize',[10 5]);
wolffd@0 146 % labs = cell(50, 1); labs{1, 1} = 'first_unit';
wolffd@0 147 % cnames = {'first'; 'second'; 'third'};
wolffd@0 148 % sN = som_set('som_norm');
wolffd@0 149 % csN = {sN; sN; sN};
wolffd@0 150 %
wolffd@0 151 % sMap = som_map_struct(3,'msize',[10 5],'rect');
wolffd@0 152 % sMap = som_map_struct(3,'msize',[10 5],'lattice','rect');
wolffd@0 153 % sMap = som_map_struct(3,sTo,'bubble','labels',labs);
wolffd@0 154 % sMap = som_map_struct(3,sTo,'comp_names',cnames);
wolffd@0 155 % sMap = som_map_struct(3,sTo,'name','a data struct');
wolffd@0 156 % sMap = som_map_struct(3,sTo,'comp_norm',csN,'mask',[1 0 0.5]);
wolffd@0 157 %
wolffd@0 158 % SEE ALSO
wolffd@0 159 %
wolffd@0 160 % som_set Set values and create SOM Toolbox structs.
wolffd@0 161 % som_data_struct Create a data struct.
wolffd@0 162 % som_make Initialize and train self-organizing map.
wolffd@0 163 % som_topol_struct Default values for map topology.
wolffd@0 164
wolffd@0 165 % Copyright (c) 1997-2000 by the SOM toolbox programming team.
wolffd@0 166 % http://www.cis.hut.fi/projects/somtoolbox/
wolffd@0 167
wolffd@0 168 % Version 1.0beta ecco 100997
wolffd@0 169 % Version 2.0beta juuso 101199 130300
wolffd@0 170
wolffd@0 171 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
wolffd@0 172
wolffd@0 173 % default values
wolffd@0 174 sTopol = som_set('som_topol','lattice','hexa','shape','sheet');
wolffd@0 175 neigh = 'gaussian';
wolffd@0 176 mask = ones(dim,1);
wolffd@0 177 name = sprintf('SOM %s', datestr(now, 1));
wolffd@0 178 labels = cell(prod(sTopol.msize),1);
wolffd@0 179 for i=1:length(labels), labels{i} = ''; end
wolffd@0 180 comp_names = cell(dim,1);
wolffd@0 181 for i = 1:dim, comp_names{i} = sprintf('Variable%d', i); end
wolffd@0 182 comp_norm = cell(dim,1);
wolffd@0 183
wolffd@0 184 % varargin
wolffd@0 185 i=1;
wolffd@0 186 while i<=length(varargin),
wolffd@0 187 argok = 1;
wolffd@0 188 if ischar(varargin{i}),
wolffd@0 189 switch varargin{i},
wolffd@0 190 % argument IDs
wolffd@0 191 case 'mask', i=i+1; mask = varargin{i};
wolffd@0 192 case 'msize', i=i+1; sTopol.msize = varargin{i};
wolffd@0 193 case 'labels', i=i+1; labels = varargin{i};
wolffd@0 194 case 'name', i=i+1; name = varargin{i};
wolffd@0 195 case 'comp_names', i=i+1; comp_names = varargin{i};
wolffd@0 196 case 'comp_norm', i=i+1; comp_norm = varargin{i};
wolffd@0 197 case 'lattice', i=i+1; sTopol.lattice = varargin{i};
wolffd@0 198 case 'shape', i=i+1; sTopol.shape = varargin{i};
wolffd@0 199 case {'topol','som_topol','sTopol'}, i=i+1; sTopol = varargin{i};
wolffd@0 200 case 'neigh', i=i+1; neigh = varargin{i};
wolffd@0 201 % unambiguous values
wolffd@0 202 case {'hexa','rect'}, sTopol.lattice = varargin{i};
wolffd@0 203 case {'sheet','cyl','toroid'}, sTopol.shape = varargin{i};
wolffd@0 204 case {'gaussian','cutgauss','ep','bubble'}, neigh = varargin{i};
wolffd@0 205 otherwise argok=0;
wolffd@0 206 end
wolffd@0 207 elseif isstruct(varargin{i}) & isfield(varargin{i},'type'),
wolffd@0 208 switch varargin{i}(1).type,
wolffd@0 209 case 'som_topol', sTopol = varargin{i};
wolffd@0 210 otherwise argok=0;
wolffd@0 211 end
wolffd@0 212 else
wolffd@0 213 argok = 0;
wolffd@0 214 end
wolffd@0 215 if ~argok,
wolffd@0 216 disp(['(som_map_struct) Ignoring invalid argument #' num2str(i+1)]);
wolffd@0 217 end
wolffd@0 218 i = i+1;
wolffd@0 219 end
wolffd@0 220
wolffd@0 221 % create the SOM
wolffd@0 222 codebook = rand(prod(sTopol.msize),dim);
wolffd@0 223 sTrain = som_set('som_train','time',datestr(now,0),'mask',mask);
wolffd@0 224 sMap = som_set('som_map','codebook',codebook,'topol',sTopol,...
wolffd@0 225 'neigh',neigh,'labels',labels,'mask',mask,...
wolffd@0 226 'comp_names',comp_names,'name',name,...
wolffd@0 227 'comp_norm',comp_norm,'trainhist',sTrain);
wolffd@0 228
wolffd@0 229
wolffd@0 230
wolffd@0 231 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%