function [sMap, sTrain] = som_sompaktrain(sMap, D, varargin)%SOM_SOMPAKTRAIN  Use SOM_PAK to train the Self-Organizing Map.%% [sM,sT] = som_sompaktrain(sM, D, [[argID,] value, ...])% %  sM     = som_sompaktrain(sM,D);%  sM     = som_sompaktrain(sM,sD,'alpha_type','inv');%  [M,sT] = som_sompaktrain(M,D,'bubble','trainlen',10,'inv','hexa');%%  Input and output arguments ([]'s are optional): %   sM      (struct) map struct, the trained and updated map is returned%           (matrix) codebook matrix of a self-organizing map%                    size munits x dim or  msize(1) x ... x msize(k) x dim%                    The trained map codebook is returned.%   D       (struct) training data; data struct%           (matrix) training data, size dlen x dim%           (string) name of data file%   [argID, (string) See below. The values which are unambiguous can %    value] (varies) be given without the preceeding argID.%%   sT      (struct) learning parameters used during the training%% Here are the valid argument IDs and corresponding values. The values which% are unambiguous (marked with '*') can be given without the preceeding argID.%   'msize'        (vector) map size%   'radius_ini'   (scalar) neighborhood radius%   'radius' = 'radius_ini'%   'alpha_ini'    (scalar) initial learning rate%   'alpha' = 'alpha_ini'%   'trainlen'     (scalar) training length%   'seed'         (scalar) seed for random number generator%   'snapfile'     (string) base name for snapshot files%   'snapinterval' (scalar) snapshot interval%   'tlen_type'   *(string) is the given trainlen 'samples' or 'epochs'%   'train'       *(struct) train struct, parameters for training%   'sTrain','som_train' = 'train'%   'alpha_type'  *(string) learning rate function, 'inv' or 'linear'%   'neigh'       *(string) neighborhood function, 'gaussian' or 'bubble'%   'topol'       *(struct) topology struct%   'som_topol','sTopol' = 'topol'%   'lattice'     *(string) map lattice, 'hexa' or 'rect'%% For more help, try 'type som_sompaktrain' or check out online documentation.% See also  SOM_MAKE, SOM_SEQTRAIN, SOM_BATCHTRAIN, SOM_TRAIN_STRUCT.%%%%%%%%%%%%% DETAILED DESCRIPTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% som_sompaktrain%% PURPOSE%% Use SOM_PAK to train the Self-Organizing Map.%% SYNTAX%%  sM = som_sompaktrain(sM,D);%  sM = som_sompaktrain(sM,sD);%  sM = som_sompaktrain(...,'argID',value,...);%  sM = som_sompaktrain(...,value,...);%  [sM,sT] = som_sompaktrain(M,D,...);%% DESCRIPTION%% Trains the given SOM (sM or M above) with the given training data (sD or% D) using SOM_PAK. If no optional arguments (argID, value) are% given, a default training is done, the parameters are obtained from% SOM_TRAIN_STRUCT function.  Using optional arguments the training% parameters can be specified. Returns the trained and updated SOM and a% train struct which contains information on the training.%% Notice that the SOM_PAK program 'vsom' must be in the search path of your% shell. Alternatively, you can set a variable 'SOM_PAKDIR' in the Matlab% workspace to tell the som_sompaktrain where to find the 'vsom' program.%% Notice also that many of the training parameters are much more limited in% values than when using SOM Toolbox function for training:%   - the map shape is always 'sheet'%   - only initial value for neighborhood radius can be given%   - neighborhood function can only be 'bubble' or 'gaussian'%   - only initial value for learning rate can be given%   - learning rate can only be 'linear' or 'inv'%   - mask cannot be used: all variables are always used in BMU search% Any parameters not confirming to these restrictions will be converted% so that they do before training. On the other hand, there are some % additional options that are not present in the SOM Toolbox: %   - random seed%   - snapshot file and interval%% REQUIRED INPUT ARGUMENTS%%  sM          The map to be trained. %     (struct) map struct%     (matrix) codebook matrix (field .data of map struct)%              Size is either [munits dim], in which case the map grid %              dimensions (msize) should be specified with optional arguments,%              or [msize(1) ... msize(k) dim] in which case the map %              grid dimensions are taken from the size of the matrix. %              Lattice, by default, is 'rect' and shape 'sheet'.%  D           Training data.%     (struct) data struct%     (matrix) data matrix, size [dlen dim]%     (string) name of data file%  % 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.%%   'msize'        (vector) map grid dimensions. Default is the one%                           in sM (field sM.topol.msize) or %                           'si = size(sM); msize = si(1:end-1);' %                           if only a codebook matrix was given. %   'radius_ini'   (scalar) initial neighborhood radius %   'radius'       (scalar) = 'radius_ini'%   'alpha_ini'    (vector) initial learning rate%   'alpha'        (scalar) = 'alpha_ini'%   'trainlen'     (scalar) training length (see also 'tlen_type')%   'seed'         (scalar) seed for random number generator%   'snapfile'     (string) base name for snapshot files%   'snapinterval' (scalar) snapshot interval%   'tlen_type'   *(string) is the trainlen argument given in 'epochs' or%                           in 'samples'. Default is 'epochs'.%   'train'       *(struct) train struct, parameters for training. %                           Default parameters, unless specified, %                           are acquired using SOM_TRAIN_STRUCT (this %                           also applies for 'trainlen', 'alpha_type',%                           'alpha_ini', 'radius_ini' and 'radius_fin').%   'sTrain', 'som_topol' (struct) = 'train'%   'neigh'       *(string) The used neighborhood function. Default is %                           the one in sM (field '.neigh') or 'gaussian'%                           if only a codebook matrix was given. The other %                           possible value is 'bubble'.%   'topol'       *(struct) topology of the map. Default is the one%                           in sM (field '.topol').%   'sTopol', 'som_topol' (struct) = 'topol'%   'alpha_type'  *(string) learning rate function, 'inv' or 'linear'%   'lattice'     *(string) map lattice. Default is the one in sM%                           (field sM.topol.lattice) or 'rect' %                           if only a codebook matrix was given. %   % OUTPUT ARGUMENTS% %  sM          the trained map%     (struct) if a map struct was given as input argument, a %              map struct is also returned. The current training %              is added to the training history (sM.trainhist).%              The 'neigh' and 'mask' fields of the map struct%              are updated to match those of the training.%     (matrix) if a matrix was given as input argument, a matrix%              is also returned with the same size as the input %              argument.%  sT (struct) train struct; information of the accomplished training%  % EXAMPLES%% Simplest case:%  sM = som_sompaktrain(sM,D);  %  sM = som_sompaktrain(sM,sD);  %% The change training parameters, the optional arguments 'train', % 'neigh','mask','trainlen','radius','radius_ini', 'alpha', % 'alpha_type' and 'alpha_ini' are used. %  sM = som_sompaktrain(sM,D,'bubble','trainlen',10,'radius_ini',3);%% Another way to specify training parameters is to create a train struct:%  sTrain = som_train_struct(sM,'dlen',size(D,1),'algorithm','seq');%  sTrain = som_set(sTrain,'neigh','gaussian');%  sM = som_sompaktrain(sM,D,sTrain);%% You don't necessarily have to use the map struct, but you can operate% directly with codebook matrices. However, in this case you have to% specify the topology of the map in the optional arguments. The% following commads are identical (M is originally a 200 x dim sized matrix):%  M = som_sompaktrain(M,D,'msize',[20 10],'lattice','hexa');%%  M = som_sompaktrain(M,D,'msize',[20 10],'hexa');%%  sT= som_set('som_topol','msize',[20 10],'lattice','hexa');%  M = som_sompaktrain(M,D,sT);%%  M = reshape(M,[20 10 dim]);%  M = som_sompaktrain(M,D,'hexa');%% The som_sompaktrain also returns a train struct with information on the % accomplished training. This is the same one as is added to the end of the % trainhist field of map struct, in case a map struct is given.%  [M,sTrain] = som_sompaktrain(M,D,'msize',[20 10]);%%  [sM,sTrain] = som_sompaktrain(sM,D); % sM.trainhist(end)==sTrain%% SEE ALSO% %  som_make         Initialize and train a SOM using default parameters.%  som_seqtrain     Train SOM with sequential algorithm.%  som_batchtrain   Train SOM with batch algorithm.%  som_train_struct Determine default training parameters.% Copyright (c) 1999-2000 by the SOM toolbox programming team.% http://www.cis.hut.fi/projects/somtoolbox/% Version 2.0beta juuso 151199 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Check argumentserror(nargchk(2, Inf, nargin));  % check the number of input arguments% map struct_mode = isstruct(sMap);if struct_mode,   sTopol = sMap.topol;else    orig_size = size(sMap);  if ndims(sMap) > 2,     si = size(sMap); dim = si(end); msize = si(1:end-1);