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 structs
sTrain = som_set('som_train');
% initialize optional parameters
dlen = NaN;
msize = 0;
munits = NaN;
sTprev = [];
dim = NaN;
phase = '';
% varargin
i=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
% dim
if ~isempty(sTprev) & isnan(dim), dim = length(sTprev.mask); end
% mask
if isempty(sTrain.mask) & ~isnan(dim), sTrain.mask = ones(dim,1); end
% msize, munits
if ~msize | isempty(msize),
if isnan(munits), msize = [10 10];
else s = round(sqrt(munits)); msize = [s round(munits/s)];
end
end
munits = prod(msize);
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% action
% previous training
prevalg = '';
if ~isempty(sTprev),
if any(findstr(sTprev.algorithm,'init')), prevalg = 'init';
else prevalg = sTprev.algorithm;
end
end
% 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';
end
end
% 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;
end
end
% mask
if isempty(sTrain.mask),
if ~isempty(sTprev), sTrain.mask = sTprev.mask;
elseif ~isnan(dim), sTrain.mask = ones(dim,1);
end
end
% neighborhood function
if isempty(sTrain.neigh),
if ~isempty(sTprev) & ~isempty(sTprev.neigh), sTrain.neigh = sTprev.neigh;
else sTrain.neigh = 'gaussian';
end
end
if 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);
end
end
return;
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%