annotate toolboxes/MIRtoolbox1.3.2/somtoolbox/som_sompaktrain.m @ 0:cc4b1211e677 tip

initial commit to HG from
Changeset:
646 (e263d8a21543) added further path and more save "camirversion.m"

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 arguments

error(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);

% data
givendatafile = '';
if ischar(D), 
  data_name = D; 
  givendatafile = D;
  D = [];
  dlen = NaN;
else
  if isstruct(D), 
    data_name = D.name; 
    D = D.data;   
  else
    data_name = inputname(2); 
  end
  D = D(find(sum(isnan(D),2) < dim),:); % remove empty vectors from the data
  [dlen ddim] = size(D);                % check input dimension
  if ddim ~= dim, error('Map and data dimensions must agree.'); end
end

% varargin
sTrain = som_set('som_train','algorithm','seq',...
			     'neigh',sMap.neigh,...
			     'mask',ones(dim,1),...
			     'data_name',data_name);
tlen_type  = 'epochs';
random_seed = 0; 
snapshotname = ''; 
snapshotinterval = 0;

i=1; 
while i<=length(varargin), 
  argok = 1; 
  if ischar(varargin{i}), 
    switch varargin{i}, 
     % argument IDs
     case 'msize',       i=i+1; sTopol.msize = varargin{i}; 
     case 'lattice',     i=i+1; sTopol.lattice = varargin{i};
     case 'neigh',       i=i+1; sTrain.neigh = varargin{i};
     case 'trainlen',    i=i+1; sTrain.trainlen = varargin{i};
     case 'tlen_type',   i=i+1; tlen_type = varargin{i}; 
     case 'radius_ini',  i=i+1; sTrain.radius_ini = varargin{i};
     case 'radius',      i=i+1; sTrain.radius_ini = varargin{i}(1);
     case 'alpha_type',  i=i+1; sTrain.alpha_type = varargin{i};
     case 'alpha_ini',   i=i+1; sTrain.alpha_ini = varargin{i};
     case 'alpha',       i=i+1; sTrain.alpha_ini = varargin{i}(1);
     case 'seed',        i=i+1; random_seed = varargin{i};
     case 'snapshotname',i=i+1; snapshotname = varargin{i};
     case 'snapshotinterval',i=i+1; snapshotinterval = varargin{i};
     case {'sTrain','train','som_train'}, i=i+1; sTrain = varargin{i};
     case {'topol','sTopol','som_topol'}, 
      i=i+1; 
      sTopol = varargin{i};
      if prod(sTopol.msize) ~= munits, 
        error('Given map grid size does not match the codebook size.');
      end
      % unambiguous values
     case {'inv','linear'}, sTrain.alpha_type = varargin{i}; 
     case {'hexa','rect'}, sTopol.lattice = varargin{i};
     case {'gaussian','bubble'}, sTrain.neigh = varargin{i};
     case {'epochs','samples'}, tlen_type = varargin{i};
     otherwise argok=0; 
    end
  elseif isstruct(varargin{i}) & isfield(varargin{i},'type'), 
    switch varargin{i}(1).type, 
     case 'som_topol', 
      sTopol = varargin{i}; 
      if prod(sTopol.msize) ~= munits, 
        error('Given map grid size does not match the codebook size.');
      end
     case 'som_train', sTrain = varargin{i};
     otherwise argok=0; 
    end
  else
    argok = 0; 
  end
  if ~argok, 
    disp(['(som_sompaktrain) Ignoring invalid argument #' num2str(i+2)]); 
  end
  i = i+1; 
end

% check topology
if struct_mode, 
  if ~strcmp(sTopol.lattice,sMap.topol.lattice) | ...
	~strcmp(sTopol.shape,sMap.topol.shape) | ...
	any(sTopol.msize ~= sMap.topol.msize), 
    warning('Changing the original map topology.');
  end
end
sMap.topol = sTopol; 

% complement the training struct
if ~isnan(dlen), 
  sTrain = som_train_struct(sTrain,sMap,'dlen',dlen);
else
  sTrain = som_train_struct(sTrain,sMap); 
end
if isempty(sTrain.mask), sTrain.mask = ones(dim,1); end

% training length
if strcmp(tlen_type,'epochs'), 
  if isnan(dlen),   
    error('Training length given as epochs, but data length is not known.\n');
  else
    rlen = sTrain.trainlen*dlen;
  end
else
  rlen = sTrain.trainlen;
  sTrain.trainlen = sTrain.trainlen/dlen;   
end 

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% check arguments

% mask
if any(sTrain.mask~=1), 
  sTrain.mask = ones(dim,1); 
  fprintf(1,'Ignoring given mask.\n');
end

% learning rate
if strcmp(sTrain.alpha_type,'power'), 
  sTrain.alpha_type = 'inv';
  fprintf(1,'Using ''inv'' learning rate type instead of ''power''\n');
end
  
% neighborhood
if any(strcmp(sTrain.neigh,{'cutgauss','ep'})), 
  fprintf(1,'Using ''gaussian'' neighborhood function instead of %s.\n',sTrain.neigh);
  sTrain.neigh = 'gaussian'; 
end

% map shape
if ~strcmp(sMap.topol.shape,'sheet'), 
  fprintf(1,'Using ''sheet'' map shape of %s.\n',sMap.topol.shape);
  sMap.topol.shape = 'sheet'; 
end

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Action

% write files
if ~isempty(givendatafile), 
  temp_din = givendatafile; 
else 
  temp_din = tempname; 
  som_write_data(D, temp_din, 'x')
end
temp_cin  = tempname;
som_write_cod(sMap, temp_cin)
temp_cout = tempname;

% check if the environment variable 'SOM_PAKDIR' has been defined
if any(strcmp('SOM_PAKDIR', evalin('base', 'who')))
  som_pak_dir = evalin('base', 'SOM_PAKDIR');
else
  som_pak_dir = '';
end
if ~isempty(som_pak_dir) & ~strncmp(som_pak_dir(end), '/', 1)
  som_pak_dir(end + 1) = '/';
end

aini  = sTrain.alpha_ini; 
atype = sTrain.alpha_type;
if strcmp(atype,'inv'), atype = 'inverse_t'; end
rad   = sTrain.radius_ini;
str = [som_pak_dir 'vsom ' ...
       sprintf('-cin %s -din %s -cout %s', temp_cin, temp_din, temp_cout) ...
       sprintf(' -rlen %d -alpha %g -alpha_type %s', rlen, aini, atype) ...
       sprintf(' -radius %g -rand %g ',rad,random_seed)];
if ~isempty(snapshotname) & snapinterval>0, 
  str = [str, sprintf(' -snapfile %s -snapinterval %d',snapshotname,snapshotinterval)];
end

fprintf(1,'Execute: %s\n',str);
if isunix, 
  [status,w] = unix(str); 
  if status, fprintf(1,'Execution failed.\n'); end
  if ~isempty(w), fprintf(1,'%s\n',w); end
else 
  [status,w] = dos(str); 
  if status, fprintf(1,'Execution failed.\n'); end
  if ~isempty(w), fprintf(1,'%s\n',w); end
end

sMap_temp = som_read_cod(temp_cout);
M = sMap_temp.codebook;

if isunix
  unix(['/bin/rm -f ' temp_din ' ' temp_cin ' ' temp_cout]);
else
  dos(['del ' temp_din ' ' temp_cin ' ' temp_cout]);
end

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Build / clean up the return arguments

% update structures
sTrain = som_set(sTrain,'time',datestr(now,0));
if struct_mode, 
  sMap = som_set(sMap,'codebook',M,'mask',sTrain.mask,'neigh',sTrain.neigh);
  tl = length(sMap.trainhist);
  sMap.trainhist(tl+1) = sTrain;
else
  sMap = reshape(M,orig_size);
end

return;

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%