Mercurial > hg > camir-aes2014

annotate toolboxes/MIRtoolbox1.3.2/somtoolbox/som_train_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 sTrain = som_train_struct(varargin)
wolffd@0 2
wolffd@0 3 %SOM_TRAIN_STRUCT Default values for SOM training parameters.
wolffd@0 4 %
wolffd@0 5 % sT = som_train_struct([[argID,] value, ...])
wolffd@0 6 %
wolffd@0 7 % sTrain = som_train_struct('train',sM,sD);
wolffd@0 8 % sTrain = som_train_struct('finetune','data',D);
wolffd@0 9 % sTrain = som_train_struct('previous',sT0);
wolffd@0 10 %
wolffd@0 11 % Input and output arguments ([]'s are optional):
wolffd@0 12 % [argID, (string) Several default values depend on other SOM parameters
wolffd@0 13 % value] (varies) or on the proporties of a data set. See below for a
wolffd@0 14 % a list of required and optional arguments for
wolffd@0 15 % different parameters, and well as the list of valid
wolffd@0 16 % argIDs and associated values. The values which are
wolffd@0 17 % unambiguous can be given without the preceeding argID.
wolffd@0 18 %
wolffd@0 19 % sT (struct) The training struct.
wolffd@0 20 %
wolffd@0 21 % Training struct contains values for training and initialization
wolffd@0 22 % parameters. These parameters depend on the number of training samples,
wolffd@0 23 % phase of training, the training algorithm.
wolffd@0 24 %
wolffd@0 25 % Here are the valid argument IDs and corresponding values. The values which
wolffd@0 26 % are unambiguous (marked with '*') can be given without the preceeding rgID.
wolffd@0 27 % 'dim' (scalar) input space dimension
wolffd@0 28 % 'dlen' (scalar) length of the training data
wolffd@0 29 % 'data' (matrix / struct) the training data
wolffd@0 30 % 'munits' (scalar) number of map units
wolffd@0 31 % 'msize' (vector) map size
wolffd@0 32 % 'previous' (struct) previous training struct can be given in
wolffd@0 33 % conjunction with 'finetune' phase (see below)
wolffd@0 34 % 'phase' *(string) training phase: 'init', 'train', 'rough' or 'finetune'
wolffd@0 35 % 'algorithm' *(string) algorithm to use: 'lininit', 'randinit', 'batch' or 'seq'
wolffd@0 36 % 'map' *(struct) If a map struct is given, the last training struct
wolffd@0 37 % in '.trainhist' field is used as the previous training
wolffd@0 38 % struct. The map size and input space dimension are
wolffd@0 39 % extracted from the map struct.
wolffd@0 40 % 'sTrain' *(struct) a train struct, the empty fields of which are
wolffd@0 41 % filled with sensible values
wolffd@0 42 %
wolffd@0 43 % For more help, try 'type som_train_struct' or check out online documentation.
wolffd@0 44 % See also SOM_SET, SOM_TOPOL_STRUCT, SOM_MAKE.
wolffd@0 45
wolffd@0 46 %%%%%%%%%%%%% DETAILED DESCRIPTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
wolffd@0 47 %
wolffd@0 48 % som_train_struct
wolffd@0 49 %
wolffd@0 50 % PURPOSE
wolffd@0 51 %
wolffd@0 52 % Default values for SOM training parameters.
wolffd@0 53 %
wolffd@0 54 % SYNTAX
wolffd@0 55 %
wolffd@0 56 % sT = som_train_struct('argID',value,...);
wolffd@0 57 % sT = som_train_struct(value,...);
wolffd@0 58 %
wolffd@0 59 % DESCRIPTION
wolffd@0 60 %
wolffd@0 61 % This function is used to give sensible values for SOM training
wolffd@0 62 % parameters and returns a training struct. Often, the parameters
wolffd@0 63 % depend on the properties of the map and the training data. These are
wolffd@0 64 % given as optional arguments to the function. If a partially filled
wolffd@0 65 % train struct is given, its empty fields (field value is [] or '' or
wolffd@0 66 % NaN) are supplimented with default values.
wolffd@0 67 %
wolffd@0 68 % The training struct has a number of fields which depend on each other
wolffd@0 69 % and the optional arguments in complex ways. The most important argument
wolffd@0 70 % is 'phase' which can be either 'init', 'train', 'rough' or 'finetune'.
wolffd@0 71 %
wolffd@0 72 % 'init' Map initialization.
wolffd@0 73 % 'train' Map training in a onepass operation, as opposed to the
wolffd@0 74 % rough-finetune combination.
wolffd@0 75 % 'rough' Rough organization of the map: large neighborhood, big
wolffd@0 76 % initial value for learning coefficient. Short training.
wolffd@0 77 % 'finetune' Finetuning the map after rough organization phase. Small
wolffd@0 78 % neighborhood, learning coefficient is small already at
wolffd@0 79 % the beginning. Long training.
wolffd@0 80 %
wolffd@0 81 % The fields of training struct set by this function are listed below.
wolffd@0 82 %
wolffd@0 83 % '.mask' Basically, a column vector of ones. But if a previous
wolffd@0 84 % train or map struct is given, it is copied from there.
wolffd@0 85 % '.neigh' Default value is 'gaussian' but if a previous train or map
wolffd@0 86 % struct is given, it is copied from there.
wolffd@0 87 % '.alpha_type' Default value is 'inv' but if a previous training struct
wolffd@0 88 % is given, it is copied from there.
wolffd@0 89 % '.alpha_ini' For 'train' and 'rough' phases, this is 0.5, for
wolffd@0 90 % 'finetune' it is 0.05.
wolffd@0 91 % '.radius_ini' Depends on the previous training operation and the
wolffd@0 92 % maximum sidelength of the map ms = max(msize).
wolffd@0 93 % if there isn't one, or it is 'randinit', rad_ini = max(1,ms/2)
wolffd@0 94 % if it is 'lininit', rad_ini = max(1,ms/8)
wolffd@0 95 % otherwise, rad_ini = rad_fin of the previous training
wolffd@0 96 % '.radius_fin' Default value is 1, but if the training phase is
wolffd@0 97 % 'rough', rad_fin = max(1,rad_ini/4).
wolffd@0 98 % '.trainlen' For 'train' phase this is 20 x mpd epochs, for 'rough'
wolffd@0 99 % phase 4 x mpd epochs and for 'finetune' 16 x mpd
wolffd@0 100 % epochs, where mpd = munits/dlen. If mpd cannot be
wolffd@0 101 % calculated, it is set to be = 0.5. In any case,
wolffd@0 102 % trainlen is at least one epoch.
wolffd@0 103 % '.algorithm' Default training algorithm is 'batch' and default
wolffd@0 104 % initialization algorithm is 'lininit'.
wolffd@0 105 %
wolffd@0 106 % OPTIONAL INPUT ARGUMENTS
wolffd@0 107 %
wolffd@0 108 % argID (string) Argument identifier string (see below).
wolffd@0 109 % value (varies) Value for the argument (see below).
wolffd@0 110 %
wolffd@0 111 % The optional arguments can be given as 'argID',value -pairs. If an
wolffd@0 112 % argument is given value multiple times, the last one is used. The
wolffd@0 113 % valid IDs and corresponding values are listed below. The values
wolffd@0 114 % which are unambiguous (marked with '*') can be given without the
wolffd@0 115 % preceeding argID.
wolffd@0 116 %
wolffd@0 117 % 'dim' (scalar) input space dimension
wolffd@0 118 % 'dlen' (scalar) length of the training data
wolffd@0 119 % 'data' (matrix / struct) the training data
wolffd@0 120 % 'munits' (scalar) number of map units
wolffd@0 121 % 'msize' (vector) map size
wolffd@0 122 % 'previous' (struct) previous training struct can be given in
wolffd@0 123 % conjunction with 'finetune' phase.
wolffd@0 124 % 'phase' *(string) training phase: 'init', 'train', 'rough' or 'finetune'
wolffd@0 125 % 'algorithm' *(string) algorithm to use: 'lininit', 'randinit',
wolffd@0 126 % 'batch' or 'seq'
wolffd@0 127 % 'map' *(struct) If a map struc is given, the last training struct
wolffd@0 128 % in '.trainhist' field is used as the previous training
wolffd@0 129 % struct. The map size and input space dimension are
wolffd@0 130 % extracted from the map struct.
wolffd@0 131 % 'sTrain' *(struct) a train struct, the empty fields of which are
wolffd@0 132 % filled with sensible values
wolffd@0 133 %
wolffd@0 134 % OUTPUT ARGUMENTS
wolffd@0 135 %
wolffd@0 136 % sT (struct) The training struct.
wolffd@0 137 %
wolffd@0 138 % EXAMPLES
wolffd@0 139 %
wolffd@0 140 % The most important optional argument for the training parameters is
wolffd@0 141 % 'phase'. The second most important are 'previous' and/or 'map'.
wolffd@0 142 %
wolffd@0 143 % To get default initialization parameters, use:
wolffd@0 144 %
wolffd@0 145 % sTrain = som_train_struct('phase','init');
wolffd@0 146 % or
wolffd@0 147 % sTrain = som_train_struct('init');
wolffd@0 148 %
wolffd@0 149 % To get default training parameters, use:
wolffd@0 150 %
wolffd@0 151 % sTrain = som_train_struct('phase','train','data',D,'map',sMap);
wolffd@0 152 % or
wolffd@0 153 % sTrain = som_train_struct('train','data',D,sMap);
wolffd@0 154 % or
wolffd@0 155 % sTrain = som_train_struct('train','dlen',dlen, ...
wolffd@0 156 % 'msize',sMap.topol.msize,'dim',dim);
wolffd@0 157 %
wolffd@0 158 % If you want to first rough train and then finetune, do like this:
wolffd@0 159 %
wolffd@0 160 % sT1 = som_train_struct('rough','dlen',length(D),sMap); % rough training
wolffd@0 161 % sT2 = som_train_struct('finetune','previous',sT1); % finetuning
wolffd@0 162 %
wolffd@0 163 % SEE ALSO
wolffd@0 164 %
wolffd@0 165 % som_make Initialize and train a map using default parameters.
wolffd@0 166 % som_topol_struct Default map topology.
wolffd@0 167 % som_randinint Random initialization algorithm.
wolffd@0 168 % som_lininit Linear initialization algorithm.
wolffd@0 169 % som_seqtrain Sequential training algorithm.
wolffd@0 170 % som_batchtrain Batch training algorithm.
wolffd@0 171
wolffd@0 172 % Copyright (c) 1999-2000 by the SOM toolbox programming team.
wolffd@0 173 % http://www.cis.hut.fi/projects/somtoolbox/
wolffd@0 174
wolffd@0 175 % Version 2.0beta juuso 101199 090200 210301
wolffd@0 176
wolffd@0 177 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
wolffd@0 178 %% check arguments
wolffd@0 179
wolffd@0 180 % initial default structs
wolffd@0 181 sTrain = som_set('som_train');
wolffd@0 182
wolffd@0 183 % initialize optional parameters
wolffd@0 184 dlen = NaN;
wolffd@0 185 msize = 0;
wolffd@0 186 munits = NaN;
wolffd@0 187 sTprev = [];
wolffd@0 188 dim = NaN;
wolffd@0 189 phase = '';
wolffd@0 190
wolffd@0 191 % varargin
wolffd@0 192 i=1;
wolffd@0 193 while i<=length(varargin),
wolffd@0 194 argok = 1;
wolffd@0 195 if ischar(varargin{i}),
wolffd@0 196 switch varargin{i},
wolffd@0 197 case 'dim', i=i+1; dim = varargin{i};
wolffd@0 198 case 'dlen', i=i+1; dlen = varargin{i};
wolffd@0 199 case 'msize', i=i+1; msize = varargin{i};
wolffd@0 200 case 'munits', i=i+1; munits = varargin{i}; msize = 0;
wolffd@0 201 case 'phase', i=i+1; phase = varargin{i};
wolffd@0 202 case 'algorithm', i=i+1; sTrain.algorithm = varargin{i};
wolffd@0 203 case 'mask', i=i+1; sTrain.mask = varargin{i};
wolffd@0 204 case {'previous','map'},
wolffd@0 205 i=i+1;
wolffd@0 206 if strcmp(varargin{i}.type,'som_map'),
wolffd@0 207 if length(varargin{i}.trainhist),
wolffd@0 208 sTprev = varargin{i}.trainhist(end);
wolffd@0 209 msize = varargin{i}.topol.msize;
wolffd@0 210 end
wolffd@0 211 elseif strcmp(varargin{i}.type,'som_train'),
wolffd@0 212 sTprev = varargin{i};
wolffd@0 213 end
wolffd@0 214 case 'data',
wolffd@0 215 i=i+1;
wolffd@0 216 if isstruct(varargin{i}), [dlen dim] = size(varargin{i}.data);
wolffd@0 217 else [dlen dim] = size(varargin{i});
wolffd@0 218 end
wolffd@0 219 case {'init','train','rough','finetune'}, phase = varargin{i};
wolffd@0 220 case {'lininit','randinit','seq','batch'}, sTrain.algorithm = varargin{i};
wolffd@0 221 otherwise argok=0;
wolffd@0 222 end
wolffd@0 223 elseif isstruct(varargin{i}) & isfield(varargin{i},'type'),
wolffd@0 224 switch varargin{i}.type,
wolffd@0 225 case 'som_train',
wolffd@0 226 sT = varargin{i};
wolffd@0 227 if ~isempty(sT.algorithm), sTrain.algorithm = sT.algorithm; end
wolffd@0 228 if ~isempty(sT.neigh), sTrain.neigh = sT.neigh; end
wolffd@0 229 if ~isempty(sT.mask), sTrain.mask = sT.mask; end
wolffd@0 230 if ~isnan(sT.radius_ini), sTrain.radius_ini = sT.radius_ini; end
wolffd@0 231 if ~isnan(sT.radius_fin), sTrain.radius_fin = sT.radius_fin; end
wolffd@0 232 if ~isnan(sT.alpha_ini), sTrain.alpha_ini = sT.alpha_ini; end
wolffd@0 233 if ~isempty(sT.alpha_type), sTrain.alpha_type = sT.alpha_type; end
wolffd@0 234 if ~isnan(sT.trainlen), sTrain.trainlen = sT.trainlen; end
wolffd@0 235 if ~isempty(sT.data_name), sTrain.data_name = sT.data_name; end
wolffd@0 236 if ~isempty(sT.time), sTrain.time = sT.time; end
wolffd@0 237 case 'som_map',
wolffd@0 238 if strcmp(varargin{i}.type,'som_map'),
wolffd@0 239 if length(varargin{i}.trainhist),
wolffd@0 240 sTprev = varargin{i}.trainhist(end);
wolffd@0 241 msize = varargin{i}.topol.msize;
wolffd@0 242 end
wolffd@0 243 if ~isempty(varargin{i}.neigh) & isempty(sTrain.neigh),
wolffd@0 244 sTrain.neigh = varargin{i}.neigh;
wolffd@0 245 end
wolffd@0 246 if ~isempty(varargin{i}.mask) & isempty(sTrain.mask),
wolffd@0 247 sTrain.mask = varargin{i}.mask;
wolffd@0 248 end
wolffd@0 249 elseif strcmp(varargin{i}.type,'som_train'),
wolffd@0 250 sTprev = varargin{i};
wolffd@0 251 end
wolffd@0 252 case 'som_topol', msize = varargin{i}.msize;
wolffd@0 253 case 'som_data', [dlen dim] = size(varargin{i}.data);
wolffd@0 254 otherwise argok=0;
wolffd@0 255 end
wolffd@0 256 else
wolffd@0 257 argok = 0;
wolffd@0 258 end
wolffd@0 259 if ~argok,
wolffd@0 260 disp(['(som_train_struct) Ignoring invalid argument #' num2str(i)]);
wolffd@0 261 end
wolffd@0 262 i = i+1;
wolffd@0 263 end
wolffd@0 264
wolffd@0 265 % dim
wolffd@0 266 if ~isempty(sTprev) & isnan(dim), dim = length(sTprev.mask); end
wolffd@0 267
wolffd@0 268 % mask
wolffd@0 269 if isempty(sTrain.mask) & ~isnan(dim), sTrain.mask = ones(dim,1); end
wolffd@0 270
wolffd@0 271 % msize, munits
wolffd@0 272 if ~msize | isempty(msize),
wolffd@0 273 if isnan(munits), msize = [10 10];
wolffd@0 274 else s = round(sqrt(munits)); msize = [s round(munits/s)];
wolffd@0 275 end
wolffd@0 276 end
wolffd@0 277 munits = prod(msize);
wolffd@0 278
wolffd@0 279 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
wolffd@0 280 %% action
wolffd@0 281
wolffd@0 282 % previous training
wolffd@0 283 prevalg = '';
wolffd@0 284 if ~isempty(sTprev),
wolffd@0 285 if any(findstr(sTprev.algorithm,'init')), prevalg = 'init';
wolffd@0 286 else prevalg = sTprev.algorithm;
wolffd@0 287 end
wolffd@0 288 end
wolffd@0 289
wolffd@0 290 % first determine phase
wolffd@0 291 if isempty(phase),
wolffd@0 292 switch sTrain.algorithm,
wolffd@0 293 case {'lininit','randinit'}, phase = 'init';
wolffd@0 294 case {'batch','seq',''},
wolffd@0 295 if isempty(sTprev), phase = 'rough';
wolffd@0 296 elseif strcmp(prevalg,'init'), phase = 'rough';
wolffd@0 297 else phase = 'finetune';
wolffd@0 298 end
wolffd@0 299 otherwise, phase = 'train';
wolffd@0 300 end
wolffd@0 301 end
wolffd@0 302
wolffd@0 303 % then determine algorithm
wolffd@0 304 if isempty(sTrain.algorithm),
wolffd@0 305 if strcmp(phase,'init'), sTrain.algorithm = 'lininit';
wolffd@0 306 elseif any(strcmp(prevalg,{'init',''})), sTrain.algorithm = 'batch';
wolffd@0 307 else sTrain.algorithm = sTprev.algorithm;
wolffd@0 308 end
wolffd@0 309 end
wolffd@0 310
wolffd@0 311 % mask
wolffd@0 312 if isempty(sTrain.mask),
wolffd@0 313 if ~isempty(sTprev), sTrain.mask = sTprev.mask;
wolffd@0 314 elseif ~isnan(dim), sTrain.mask = ones(dim,1);
wolffd@0 315 end
wolffd@0 316 end
wolffd@0 317
wolffd@0 318 % neighborhood function
wolffd@0 319 if isempty(sTrain.neigh),
wolffd@0 320 if ~isempty(sTprev) & ~isempty(sTprev.neigh), sTrain.neigh = sTprev.neigh;
wolffd@0 321 else sTrain.neigh = 'gaussian';
wolffd@0 322 end
wolffd@0 323 end
wolffd@0 324
wolffd@0 325 if strcmp(phase,'init'),
wolffd@0 326 sTrain.alpha_ini = NaN;
wolffd@0 327 sTrain.alpha_type = '';
wolffd@0 328 sTrain.radius_ini = NaN;
wolffd@0 329 sTrain.radius_fin = NaN;
wolffd@0 330 sTrain.trainlen = NaN;
wolffd@0 331 sTrain.neigh = '';
wolffd@0 332 else
wolffd@0 333 mode = [phase, '-', sTrain.algorithm];
wolffd@0 334
wolffd@0 335 % learning rate
wolffd@0 336 if isnan(sTrain.alpha_ini),
wolffd@0 337 if strcmp(sTrain.algorithm,'batch'), sTrain.alpha_ini = NaN;
wolffd@0 338 else
wolffd@0 339 switch phase,
wolffd@0 340 case {'train','rough'}, sTrain.alpha_ini = 0.5;
wolffd@0 341 case 'finetune', sTrain.alpha_ini = 0.05;
wolffd@0 342 end
wolffd@0 343 end
wolffd@0 344 end
wolffd@0 345 if isempty(sTrain.alpha_type),
wolffd@0 346 if ~isempty(sTprev) & ~isempty(sTprev.alpha_type) ...
wolffd@0 347 & ~strcmp(sTrain.algorithm,'batch'),
wolffd@0 348 sTrain.alpha_type = sTprev.alpha_type;
wolffd@0 349 elseif strcmp(sTrain.algorithm,'seq'),
wolffd@0 350 sTrain.alpha_type = 'inv';
wolffd@0 351 end
wolffd@0 352 end
wolffd@0 353
wolffd@0 354 % radius
wolffd@0 355 ms = max(msize);
wolffd@0 356 if isnan(sTrain.radius_ini),
wolffd@0 357 if isempty(sTprev) | strcmp(sTprev.algorithm,'randinit'),
wolffd@0 358 sTrain.radius_ini = max(1,ceil(ms/4));
wolffd@0 359 elseif strcmp(sTprev.algorithm,'lininit') | isnan(sTprev.radius_fin),
wolffd@0 360 sTrain.radius_ini = max(1,ceil(ms/8));
wolffd@0 361 else
wolffd@0 362 sTrain.radius_ini = sTprev.radius_fin;
wolffd@0 363 end
wolffd@0 364 end
wolffd@0 365 if isnan(sTrain.radius_fin),
wolffd@0 366 if strcmp(phase,'rough'),
wolffd@0 367 sTrain.radius_fin = max(1,sTrain.radius_ini/4);
wolffd@0 368 else
wolffd@0 369 sTrain.radius_fin = 1;
wolffd@0 370 end
wolffd@0 371 end
wolffd@0 372
wolffd@0 373 % trainlen
wolffd@0 374 if isnan(sTrain.trainlen),
wolffd@0 375 mpd = munits/dlen;
wolffd@0 376 if isnan(mpd), mpd = 0.5; end
wolffd@0 377 switch phase,
wolffd@0 378 case 'train', sTrain.trainlen = ceil(50*mpd);
wolffd@0 379 case 'rough', sTrain.trainlen = ceil(10*mpd);
wolffd@0 380 case 'finetune', sTrain.trainlen = ceil(40*mpd);
wolffd@0 381 end
wolffd@0 382 sTrain.trainlen = max(1,sTrain.trainlen);
wolffd@0 383 end
wolffd@0 384
wolffd@0 385 end
wolffd@0 386
wolffd@0 387 return;
wolffd@0 388
wolffd@0 389 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%