function sTrain = som_train_struct(varargin)%SOM_TRAIN_STRUCT Default values for SOM training parameters.%% sT = som_train_struct([[argID,] value, ...])%%  sTrain = som_train_struct('train',sM,sD);%  sTrain = som_train_struct('finetune','data',D); %  sTrain = som_train_struct('previous',sT0);% %  Input and output arguments ([]'s are optional): %    [argID,  (string) Several default values depend on other SOM parameters%     value]  (varies) or on the proporties of a data set. See below for a%                      a list of required and optional arguments for%                      different parameters, and well as the list of valid %                      argIDs and associated values. The values which are %                      unambiguous can be given without the preceeding argID.%%    sT       (struct) The training struct.%% Training struct contains values for training and initialization% parameters. These parameters depend on the number of training samples,% phase of training, the training algorithm.% % Here are the valid argument IDs and corresponding values. The values which% are unambiguous (marked with '*') can be given without the preceeding rgID.%  'dim'          (scalar) input space dimension%  'dlen'         (scalar) length of the training data%  'data'         (matrix / struct) the training data%  'munits'       (scalar) number of map units%  'msize'        (vector) map size%  'previous'     (struct) previous training struct can be given in %                          conjunction with 'finetune' phase (see below) %  'phase'       *(string) training phase: 'init', 'train', 'rough' or 'finetune'%  'algorithm'   *(string) algorithm to use: 'lininit', 'randinit', 'batch' or 'seq'%  'map'         *(struct) If a map struct is given, the last training struct%                          in '.trainhist' field is used as the previous training%                          struct. The map size and input space dimension are %                          extracted from the map struct.%  'sTrain'      *(struct) a train struct, the empty fields of which are%                          filled with sensible values%% For more help, try 'type som_train_struct' or check out online documentation.% See also SOM_SET, SOM_TOPOL_STRUCT, SOM_MAKE.%%%%%%%%%%%%% DETAILED DESCRIPTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% som_train_struct%% PURPOSE%% Default values for SOM training parameters.%% SYNTAX%%  sT = som_train_struct('argID',value,...);%  sT = som_train_struct(value,...);%% DESCRIPTION%% This function is used to give sensible values for SOM training% parameters and returns a training struct. Often, the parameters% depend on the properties of the map and the training data. These are% given as optional arguments to the function. If a partially filled% train struct is given, its empty fields (field value is [] or '' or% NaN) are supplimented with default values.%% The training struct has a number of fields which depend on each other% and the optional arguments in complex ways. The most important argument % is 'phase' which can be either 'init', 'train', 'rough' or 'finetune'.%%  'init'     Map initialization. %  'train'    Map training in a onepass operation, as opposed to the%             rough-finetune combination.%  'rough'    Rough organization of the map: large neighborhood, big%             initial value for learning coefficient. Short training.%  'finetune' Finetuning the map after rough organization phase. Small%             neighborhood, learning coefficient is small already at %             the beginning. Long training.%% The fields of training struct set by this function are listed below.%%  '.mask'  Basically, a column vector of ones. But if a previous%           train or map struct is given, it is copied from there.%  '.neigh' Default value is 'gaussian' but if a previous train or map %           struct is given, it is copied from there.%  '.alpha_type' Default value is 'inv' but if a previous training struct %           is given, it is copied from there.%  '.alpha_ini' For 'train' and 'rough' phases, this is 0.5, for%           'finetune' it is 0.05.%  '.radius_ini' Depends on the previous training operation and the %           maximum sidelength of the map ms = max(msize).%           if there isn't one, or it is 'randinit', rad_ini = max(1,ms/2)%           if it is 'lininit', rad_ini = max(1,ms/8)%           otherwise, rad_ini = rad_fin of the previous training%  '.radius_fin' Default value is 1, but if the training phase is%           'rough', rad_fin = max(1,rad_ini/4).%  '.trainlen' For 'train' phase this is 20 x mpd epochs, for 'rough'%           phase 4 x mpd epochs and for 'finetune' 16 x mpd%           epochs, where mpd = munits/dlen. If mpd cannot be%           calculated, it is set to be = 0.5. In any case,%           trainlen is at least one epoch.%  '.algorithm' Default training algorithm is 'batch' and default%           initialization algorithm is 'lininit'.%% OPTIONAL INPUT ARGUMENTS %%  argID (string) Argument identifier string (see below).%  value (varies) Value for the argument (see below).%%  The optional arguments can be given as 'argID',value -pairs. If an%  argument is given value multiple times, the last one is used.  The%  valid IDs and corresponding values are listed below. The values%  which are unambiguous (marked with '*') can be given without the%  preceeding argID.%%  'dim'          (scalar) input space dimension%  'dlen'         (scalar) length of the training data%  'data'         (matrix / struct) the training data%  'munits'       (scalar) number of map units%  'msize'        (vector) map size%  'previous'     (struct) previous training struct can be given in %                  conjunction with 'finetune' phase. %  'phase'       *(string) training phase: 'init', 'train', 'rough' or 'finetune'%  'algorithm'   *(string) algorithm to use: 'lininit', 'randinit', %                  'batch' or 'seq'%  'map'         *(struct) If a map struc is given, the last training struct%                  in '.trainhist' field is used as the previous training%                  struct. The map size and input space dimension are %                  extracted from the map struct.%  'sTrain'      *(struct) a train struct, the empty fields of which are%                  filled with sensible values%% OUTPUT ARGUMENTS% %  sT     (struct) The training struct.%% EXAMPLES%%  The most important optional argument for the training parameters is%  'phase'. The second most important are 'previous' and/or 'map'. %%  To get default initialization parameters, use: %%    sTrain = som_train_struct('phase','init');%     or%    sTrain = som_train_struct('init');%%  To get default training parameters, use: %%    sTrain = som_train_struct('phase','train','data',D,'map',sMap);%     or  %    sTrain = som_train_struct('train','data',D,sMap);%     or%    sTrain = som_train_struct('train','dlen',dlen, ...%                              'msize',sMap.topol.msize,'dim',dim);%  %  If you want to first rough train and then finetune, do like this: %%   sT1 = som_train_struct('rough','dlen',length(D),sMap); % rough training%   sT2 = som_train_struct('finetune','previous',sT1);     % finetuning%% SEE ALSO%%  som_make         Initialize and train a map using default parameters.%  som_topol_struct Default map topology.%  som_randinint    Random initialization algorithm.%  som_lininit      Linear initialization algorithm.%  som_seqtrain     Sequential training algorithm.%  som_batchtrain   Batch training algorithm.% Copyright (c) 1999-2000 by the SOM toolbox programming team.% http://www.cis.hut.fi/projects/somtoolbox/% Version 2.0beta juuso 101199 090200 210301%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% check arguments% initial default structssTrain = som_set('som_train'); % initialize optional parametersdlen = NaN;msize = 0; munits = NaN;sTprev = [];dim = NaN; phase = '';% varargini=1; while i<=length(varargin),   argok = 1;   if ischar(varargin{i}),     switch varargin{i},      case 'dim',        i=i+1; dim = varargin{i};      case 'dlen',       i=i+1; dlen = varargin{i};      case 'msize',      i=i+1; msize = varargin{i};     case 'munits',     i=i+1; munits = varargin{i}; msize = 0;      case 'phase',      i=i+1; phase = varargin{i};      case 'algorithm',  i=i+1; sTrain.algorithm = varargin{i};      case 'mask',       i=i+1; sTrain.mask = varargin{i};      case {'previous','map'},         i=i+1;       if strcmp(varargin{i}.type,'som_map'), 	if length(varargin{i}.trainhist), 	  sTprev = varargin{i}.trainhist(end); 	  msize = varargin{i}.topol.msize;	end      elseif strcmp(varargin{i}.type,'som_train'), 	sTprev = varargin{i};       end     case 'data',             i=i+1;       if isstruct(varargin{i}), [dlen dim] = size(varargin{i}.data);       else [dlen dim] = size(varargin{i});       end     case {'init','train','rough','finetune'},  phase = varargin{i};            case {'lininit','randinit','seq','batch'}, sTrain.algorithm = varargin{i};      otherwise argok=0;     end  elseif isstruct(varargin{i}) & isfield(varargin{i},'type'),     switch varargin{i}.type,      case 'som_train',       sT = varargin{i};       if ~isempty(sT.algorithm),  sTrain.algorithm = sT.algorithm; end      if ~isempty(sT.neigh),      sTrain.neigh = sT.neigh; end      if ~isempty(sT.mask),       sTrain.mask = sT.mask; end      if ~isnan(sT.radius_ini),   sTrain.radius_ini = sT.radius_ini; end      if ~isnan(sT.radius_fin),   sTrain.radius_fin = sT.radius_fin; end      if ~isnan(sT.alpha_ini),    sTrain.alpha_ini = sT.alpha_ini; end      if ~isempty(sT.alpha_type), sTrain.alpha_type = sT.alpha_type; end      if ~isnan(sT.trainlen),     sTrain.trainlen = sT.trainlen; end      if ~isempty(sT.data_name),  sTrain.data_name = sT.data_name; end      if ~isempty(sT.time),       sTrain.time = sT.time; end     case 'som_map',       if strcmp(varargin{i}.type,'som_map'), 	if length(varargin{i}.trainhist), 	  sTprev = varargin{i}.trainhist(end); 	  msize = varargin{i}.topol.msize; 	end	if ~isempty(varargin{i}.neigh) & isempty(sTrain.neigh), 	  sTrain.neigh = varargin{i}.neigh; 	end	if ~isempty(varargin{i}.mask) & isempty(sTrain.mask),  	  sTrain.mask = varargin{i}.mask; 	end      elseif strcmp(varargin{i}.type,'som_train'), 	sTprev = varargin{i};       end     case 'som_topol', msize = varargin{i}.msize;      case 'som_data', [dlen dim] = size(varargin{i}.data);      otherwise argok=0;     end  else    argok = 0;   end  if ~argok,     disp(['(som_train_struct) Ignoring invalid argument #' num2str(i)]);   end  i = i+1; end% dimif ~isempty(sTprev) & isnan(dim), dim = length(sTprev.mask); end% maskif isempty(sTrain.mask) & ~isnan(dim), sTrain.mask = ones(dim,1); end% msize, munitsif ~msize | isempty(msize),   if isnan(munits), msize = [10 10];   else s = round(sqrt(munits)); msize = [s round(munits/s)];   endendmunits = prod(msize);%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% action% previous trainingprevalg = ''; if ~isempty(sTprev),   if any(findstr(sTprev.algorithm,'init')), prevalg = 'init';  else prevalg = sTprev.algorithm;   endend% first determine phase  if isempty(phase),   switch sTrain.algorithm,   case {'lininit','randinit'},    phase = 'init';    case {'batch','seq',''},     if     isempty(sTprev),        phase = 'rough';     elseif strcmp(prevalg,'init'), phase = 'rough';    else                           phase = 'finetune';     end   otherwise,                      phase = 'train';   endend% then determine algorithm  if isempty(sTrain.algorithm),  if     strcmp(phase,'init'),             sTrain.algorithm = 'lininit';  elseif any(strcmp(prevalg,{'init',''})), sTrain.algorithm = 'batch';  else sTrain.algorithm = sTprev.algorithm;   endend% maskif isempty(sTrain.mask),   if ~isempty(sTprev), sTrain.mask = sTprev.mask;   elseif ~isnan(dim),  sTrain.mask = ones(dim,1);   endend% neighborhood functionif isempty(sTrain.neigh),   if ~isempty(sTprev) & ~isempty(sTprev.neigh), sTrain.neigh = sTprev.neigh;   else sTrain.neigh = 'gaussian';  endendif strcmp(phase,'init'),   sTrain.alpha_ini = NaN;  sTrain.alpha_type = '';  sTrain.radius_ini = NaN;  sTrain.radius_fin = NaN;  sTrain.trainlen = NaN;  sTrain.neigh = '';else  mode = [phase, '-', sTrain.algorithm];    % learning rate  if isnan(sTrain.alpha_ini),     if strcmp(sTrain.algorithm,'batch'), sTrain.alpha_ini = NaN;     else      switch phase,        case {'train','rough'}, sTrain.alpha_ini = 0.5;       case 'finetune',        sTrain.alpha_ini = 0.05;      end    end  end  if isempty(sTrain.alpha_type),         if ~isempty(sTprev) & ~isempty(sTprev.alpha_type) ... 	  & ~strcmp(sTrain.algorithm,'batch'),      sTrain.alpha_type = sTprev.alpha_type;    elseif strcmp(sTrain.algorithm,'seq'),      sTrain.alpha_type = 'inv';    end  end    % radius  ms = max(msize);     if isnan(sTrain.radius_ini),         if isempty(sTprev) | strcmp(sTprev.algorithm,'randinit'),       sTrain.radius_ini = max(1,ceil(ms/4));    elseif strcmp(sTprev.algorithm,'lininit') | isnan(sTprev.radius_fin),      sTrain.radius_ini = max(1,ceil(ms/8));    else      sTrain.radius_ini = sTprev.radius_fin;    end  end  if isnan(sTrain.radius_fin),     if strcmp(phase,'rough'),       sTrain.radius_fin = max(1,sTrain.radius_ini/4);    else      sTrain.radius_fin = 1;    end  end    % trainlen    if isnan(sTrain.trainlen),         mpd = munits/dlen;     if isnan(mpd), mpd = 0.5; end    switch phase,      case 'train',    sTrain.trainlen = ceil(50*mpd);     case 'rough',    sTrain.trainlen = ceil(10*mpd);      case 'finetune', sTrain.trainlen = ceil(40*mpd);    end    sTrain.trainlen = max(1,sTrain.trainlen);  endendreturn;%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%