function [sMap, sTrain] = som_seqtrain(sMap, D, varargin)%SOM_SEQTRAIN  Use sequential algorithm to train the Self-Organizing Map.%% [sM,sT] = som_seqtrain(sM, D, [[argID,] value, ...])% %  sM     = som_seqtrain(sM,D);%  sM     = som_seqtrain(sM,sD,'alpha_type','power','tracking',3);%  [M,sT] = som_seqtrain(M,D,'ep','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%   [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.%   'mask'        (vector) BMU search mask, size dim x 1%   'msize'       (vector) map size%   'radius'      (vector) neighborhood radiuses, length 1, 2 or trainlen%   'radius_ini'  (scalar) initial training radius%   'radius_fin'  (scalar) final training radius%   'alpha'       (vector) learning rates, length trainlen%   'alpha_ini'   (scalar) initial learning rate%   'tracking'    (scalar) tracking level, 0-3 %   'trainlen'    (scalar) training length%   'trainlen_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', 'linear' or 'power'%   'sample_order'*(string) order of samples: 'random' or 'ordered'%   'neigh'      *(string) neighborhood function, 'gaussian', 'cutgauss',%                          'ep' or 'bubble'%   'topol'      *(struct) topology struct%   'som_topol','sTopo l'  = 'topol'%   'lattice'    *(string) map lattice, 'hexa' or 'rect'%   'shape'      *(string) map shape, 'sheet', 'cyl' or 'toroid'%% For more help, try 'type som_seqtrain' or check out online documentation.% See also  SOM_MAKE, SOM_BATCHTRAIN, SOM_TRAIN_STRUCT.%%%%%%%%%%%%% DETAILED DESCRIPTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% som_seqtrain%% PURPOSE%% Trains a Self-Organizing Map using the sequential algorithm. %% SYNTAX%%  sM = som_seqtrain(sM,D);%  sM = som_seqtrain(sM,sD);%  sM = som_seqtrain(...,'argID',value,...);%  sM = som_seqtrain(...,value,...);%  [sM,sT] = som_seqtrain(M,D,...);%% DESCRIPTION%% Trains the given SOM (sM or M above) with the given training data% (sD or D) using sequential SOM training algorithm. 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.%% REFERENCES%% Kohonen, T., "Self-Organizing Map", 2nd ed., Springer-Verlag, %    Berlin, 1995, pp. 78-82.% Kohonen, T., "Clustering, Taxonomy, and Topological Maps of%    Patterns", International Conference on Pattern Recognition%    (ICPR), 1982, pp. 114-128.% Kohonen, T., "Self-Organized formation of topologically correct%    feature maps", Biological Cybernetics 43, 1982, pp. 59-69.%% 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]%  % 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.%%   'mask'       (vector) BMU search mask, size dim x 1. Default is %                         the one in sM (field '.mask') or a vector of%                         ones if only a codebook matrix was given.%   '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'     (vector) neighborhood radius %                         length = 1: radius_ini = radius%                         length = 2: [radius_ini radius_fin] = radius%                         length > 2: the vector given neighborhood%                                     radius for each step separately%                                     trainlen = length(radius)%   'radius_ini' (scalar) initial training radius%   'radius_fin' (scalar) final training radius%   'alpha'      (vector) learning rate%                         length = 1: alpha_ini = alpha%                         length > 1: the vector gives learning rate%                                     for each step separately%                                     trainlen is set to length(alpha)%                                     alpha_type is set to 'user defined'%   'alpha_ini'  (scalar) initial learning rate%   'tracking'   (scalar) tracking level: 0, 1 (default), 2 or 3%                         0 - estimate time %                         1 - track time and quantization error %                         2 - plot quantization error%                         3 - plot quantization error and two first %                             components %   'trainlen'   (scalar) training length (see also 'tlen_type')%   'trainlen_type' *(string) is the trainlen argument given in 'epochs'%                         or in 'samples'. Default is 'epochs'.%   'sample_order'*(string) is the sample order 'random' (which is the %                         the default) or 'ordered' in which case%                         samples are taken in the order in which they %                         appear in the data set%   '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_train' (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. Other %                         possible values is 'cutgauss', 'ep' and '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', 'linear' or 'power'%   'lattice'   *(string) map lattice. Default is the one in sM%                         (field sM.topol.lattice) or 'rect' %                         if only a codebook matrix was given. %   'shape'     *(string) map shape. Default is the one in sM%                         (field sM.topol.shape) or 'sheet' %                         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_seqtrain(sM,D);  %  sM = som_seqtrain(sM,sD);  %% To change the tracking level, 'tracking' argument is specified:%  sM = som_seqtrain(sM,D,'tracking',3);%% The change training parameters, the optional arguments 'train', % 'neigh','mask','trainlen','radius','radius_ini', 'radius_fin', % 'alpha', 'alpha_type' and 'alpha_ini' are used. %  sM = som_seqtrain(sM,D,'neigh','cutgauss','trainlen',10,'radius_fin',0);%% 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','cutgauss');%  sM = som_seqtrain(sM,D,sTrain);%% By default the neighborhood radius goes linearly from radius_ini to% radius_fin. If you want to change this, you can use the 'radius' argument% to specify the neighborhood radius for each step separately:%  sM = som_seqtrain(sM,D,'radius',[5 3 1 1 1 1 0.5 0.5 0.5]);%% By default the learning rate (alpha) goes from the alpha_ini to 0% along the function defined by alpha_type. If you want to change this, % you can use the 'alpha' argument to specify the learning rate% for each step separately: %  alpha = 0.2*(1 - log([1:100]));%  sM = som_seqtrain(sM,D,'alpha',alpha);%% 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_seqtrain(M,D,'msize',[20 10],'lattice','hexa','shape','cyl');%%  M = som_seqtrain(M,D,'msize',[20 10],'hexa','cyl');%%  sT= som_set('som_topol','msize',[20 10],'lattice','hexa','shape','cyl');%  M = som_seqtrain(M,D,sT);%%  M = reshape(M,[20 10 dim]);%  M = som_seqtrain(M,D,'hexa','cyl');%% The som_seqtrain 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_seqtrain(M,D,'msize',[20 10]);%%  [sM,sTrain] = som_seqtrain(sM,D); % sM.trainhist{end}==sTrain%% SEE ALSO% %  som_make         Initialize and train a SOM using default parameters.%  som_batchtrain   Train SOM with batch algorithm.%  som_train_struct Determine default training parameters.% Copyright (c) 1997-2000 by the SOM toolbox programming team.% http://www.cis.hut.fi/projects/somtoolbox/% Version 1.0beta juuso 220997% Version 2.0beta juuso 101199 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 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);    M = reshape(sMap,[prod(msize) dim]);  else    msize = [orig_size(1) 1];     dim = orig_size(2);  end  sMap   = som_map_struct(dim,'msize',msize);  sTopol = sMap.topol;end[munits dim] = size(sMap.codebook);% dataif isstruct(D),   data_name = D.name;   D = D.data; else   data_name = inputname(2); endD = D(find(sum(isnan(D),2) < dim),:); % remove empty vectors from the data[dlen ddim] = size(D);                % check input dimensionif dim ~= ddim, error('Map and data input space dimensions disagree.'); end% vararginsTrain = som_set('som_train','algorithm','seq','neigh', ...		 sMap.neigh,'mask',sMap.mask,'data_name',data_name);