wolffd@0: function sD = som_denormalize(sD,varargin)
wolffd@0: 
wolffd@0: %SOM_DENORMALIZE Denormalize data.
wolffd@0: %   
wolffd@0: % sS = som_denormalize(sS, [argID, value, ...])               
wolffd@0: %
wolffd@0: %   sS = som_denormalize(sS) 
wolffd@0: %   sS = som_denormalize(sS,[1:3 10],'remove') 
wolffd@0: %    D = som_denormalize(D,sM.comp_norm)
wolffd@0: %    D = som_denormalize(D,sM,[1:3 10])
wolffd@0: %
wolffd@0: %  Input and output arguments ([]'s are optional): 
wolffd@0: %   sS                The data to which the denormalization is applied.
wolffd@0: %                     The modified and updated data is returned.
wolffd@0: %            (struct) data or map struct
wolffd@0: %            (matrix) data matrix (a matrix is also returned)
wolffd@0: %   [argID, (string) See below. The values which are unambiguous can 
wolffd@0: %    value] (varies) be given without the preceeding argID.
wolffd@0: %
wolffd@0: % Here are the valid argument IDs and corresponding values. The values which
wolffd@0: % are unambiguous (marked with '*') can be given without the preceeding argID.
wolffd@0: %   'norm'   *(struct) Normalization struct, or an array of such. 
wolffd@0: %                      Alternatively, a map/data struct can be given 
wolffd@0: %                      in which case its '.comp_norm' field is used 
wolffd@0: %                      (see below).
wolffd@0: %            *(cell array) Of normalization structs. Typically, the
wolffd@0: %                      '.comp_norm' field of a map/data struct. The 
wolffd@0: %                      length of the array must be equal to data dimension.
wolffd@0: %   'remove' *(string) If 'remove' tag is specified, the
wolffd@0: %                      normalization operations are not only undone, 
wolffd@0: %                      they are also removed from the struct.
wolffd@0: %   'comps'  *(vector) the components to which the denormalization is
wolffd@0: %                      applied, default is [1:dim] ie. all components
wolffd@0: %
wolffd@0: % For more help, try 'type som_denormalize' or check out online documentation.
wolffd@0: % See also SOM_NORMALIZE, SOM_NORM_VARIABLE, SOM_INFO.
wolffd@0: 
wolffd@0: %%%%%%%%%%%%% DETAILED DESCRIPTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
wolffd@0: %
wolffd@0: % som_denormalize
wolffd@0: %
wolffd@0: % PURPOSE
wolffd@0: %
wolffd@0: % Undo normalizations of data structs/sets.
wolffd@0: %
wolffd@0: % SYNTAX
wolffd@0: %
wolffd@0: %  sS = som_denormalize(sS)
wolffd@0: %  sS = som_denormalize(...,'argID',value,...);
wolffd@0: %  sS = som_denormalize(...,value,...);
wolffd@0: %   D = som_denormalize(D,sNorm)
wolffd@0: %
wolffd@0: % DESCRIPTION
wolffd@0: %
wolffd@0: % This function is used to undo normalizations of data structs/sets. If a
wolffd@0: % data/map struct is given, all normalizations in the '.comp_norm' field are
wolffd@0: % undone and, thus, the values in the original data context are returned. If
wolffd@0: % a matrix is given, the normalizations to undo must be given as the second
wolffd@0: % argument. SOM_DENORMALIZE actually uses function SOM_NORM_VARIABLE to
wolffd@0: % handle the normalization operations, and only handles the data struct/set
wolffd@0: % specific stuff itself.
wolffd@0: %
wolffd@0: % Normalizations are always one-variable operations. In the data and map
wolffd@0: % structs the normalization information for each component is saved in the
wolffd@0: % '.comp_norm' field, which is a cell array of length dim. Each cell
wolffd@0: % contains normalizations for one vector component in a
wolffd@0: % struct array of normalization structs. Each component may have different
wolffd@0: % amounts of different kinds of normalizations. Typically, all
wolffd@0: % normalizations are either 'undone' or 'done', but in special situations
wolffd@0: % this may not be the case. The easiest way to check out the status of the
wolffd@0: % normalizations is to use function SOM_INFO, e.g. som_info(sS,3)
wolffd@0: % 
wolffd@0: % REQUIRED INPUT ARGUMENTS
wolffd@0: %
wolffd@0: %   sS                The data to which the denormalization is applied.
wolffd@0: %            (struct) Data or map struct. The normalizations in the 
wolffd@0: %                     '.comp_norm' field are undone for the specified 
wolffd@0: %                     components.
wolffd@0: %            (matrix) Data matrix. The normalization to undo must be
wolffd@0: %                     given in the second argument.
wolffd@0: %
wolffd@0: % OPTIONAL INPUT ARGUMENTS
wolffd@0: %
wolffd@0: %  argID (string) Argument identifier string (see below).
wolffd@0: %  value (varies) Value for the argument (see below).
wolffd@0: %
wolffd@0: %  The optional arguments can be given as 'argID',value -pairs. If an
wolffd@0: %  argument is given value multiple times, the last one is used. The
wolffd@0: %  valid IDs and corresponding values are listed below. The values
wolffd@0: %  which are unambiguous (marked with '*') can be given without the
wolffd@0: %  preceeding argID.
wolffd@0: %
wolffd@0: %   sNorm    *(struct) Normalization struct, or an array of structs, which
wolffd@0: %                      is undone for all specified components. If the 
wolffd@0: %                      '.status' field of the struct(s) is 'uninit', 
wolffd@0: %                      the undoing operation is interrupted - it cannot be 
wolffd@0: %                      done. Alternatively, the struct may be map or 
wolffd@0: %                      data struct in which case its '.comp_norm' field 
wolffd@0: %                      is used (see the cell array option below).
wolffd@0: %            *(cell array) In practice, the '.comp_norm' field of 
wolffd@0: %                      a data/map struct. The length of the array 
wolffd@0: %                      must be equal to the dimension of the given 
wolffd@0: %                      data set (sS). Each cell contains the
wolffd@0: %                      normalization(s) for one component. Only the
wolffd@0: %                       normalizations listed in comps argument are
wolffd@0: %                      undone though.
wolffd@0: %
wolffd@0: %   'remove' *(string) If 'remove' tag is specified, the
wolffd@0: %                      normalization operations are not only undone, 
wolffd@0: %                      they are also removed from the struct.
wolffd@0: %
wolffd@0: %   'comps'  *(vector) The components which are denormalized.
wolffd@0: %                      Default is to undo all components.
wolffd@0: %            *(string) 'all'
wolffd@0: %
wolffd@0: % OUTPUT ARGUMENTS
wolffd@0: % 
wolffd@0: %   sS                Modified and/or updated data.
wolffd@0: %            (struct) If a struct was given as input argument, the
wolffd@0: %                     same struct is returned with denormalized data and
wolffd@0: %                     updated '.comp_norm' fields. 
wolffd@0: %            (matrix) If a matrix was given as input argument, the 
wolffd@0: %                     denormalized data matrix is returned.
wolffd@0: % 
wolffd@0: % EXAMPLES
wolffd@0: %
wolffd@0: %  To undo normalization of a data/map struct: 
wolffd@0: %
wolffd@0: %    sD = som_denormalize(sD); 
wolffd@0: %    sM = som_denormalize(sM); 
wolffd@0: %
wolffd@0: %  To completely remove the normalizations, use the 'remove' tag: 
wolffd@0: %
wolffd@0: %    sD = som_denormalize(sD,'remove');
wolffd@0: %
wolffd@0: %  To undo only a few selected components, use the comps argument: 
wolffd@0: % 
wolffd@0: %    sD = som_denormalize(sD,[1 3:5]); 
wolffd@0: % 
wolffd@0: %  To denormalize a set of values from a data set D (which must be 
wolffd@0: %  of equal dimension as the data in sD): 
wolffd@0: %
wolffd@0: %    D = som_denormalize(D,sD); 
wolffd@0: %  or 
wolffd@0: %    D = som_denormalize(D,sD.comp_norm); 
wolffd@0: %  only denormalize a few components
wolffd@0: %    D = som_denormalize(D,sD,[1 3:5]); 
wolffd@0: % 
wolffd@0: %  Assuming you have a few values of a certain vector component (i)
wolffd@0: %  in a vector (x) which you want to denormalize: 
wolffd@0: %
wolffd@0: %    xorig = som_denormalize(x,sD.comp_norm{i}); 
wolffd@0: %  or using SOM_NORM_VARIABLE
wolffd@0: %    xorig = som_norm_variable(x,sD.comp_norm{i},'undo');
wolffd@0: %
wolffd@0: %  To check out the status of normalization in a struct use SOM_INFO: 
wolffd@0: % 
wolffd@0: %    som_info(sM,3)
wolffd@0: %    som_info(sD,3)
wolffd@0: %
wolffd@0: % SEE ALSO
wolffd@0: %  
wolffd@0: %  som_normalize      Add/apply/redo normalizations of a data struct/set.
wolffd@0: %  som_norm_variable  Normalization operations for a set of scalar values.
wolffd@0: %  som_info           User-friendly information of SOM Toolbox structs.
wolffd@0: 
wolffd@0: % Copyright (c) 1998-2000 by the SOM toolbox programming team.
wolffd@0: % http://www.cis.hut.fi/projects/somtoolbox/
wolffd@0: 
wolffd@0: % Version 2.0beta juuso 151199 150300
wolffd@0: 
wolffd@0: %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
wolffd@0: %% check arguments
wolffd@0: 
wolffd@0: error(nargchk(1, 3, nargin));  % check no. of input arguments is correct
wolffd@0: 
wolffd@0: % sD
wolffd@0: struct_mode = isstruct(sD);
wolffd@0: if struct_mode, 
wolffd@0:   switch sD.type
wolffd@0:    case 'som_map', D = sD.codebook; 
wolffd@0:    case 'som_data', D = sD.data; 
wolffd@0:    otherwise, error('Illegal struct.')
wolffd@0:   end
wolffd@0: else 
wolffd@0:   D = sD;
wolffd@0: end
wolffd@0: [dlen dim] = size(D);
wolffd@0: 
wolffd@0: % varargin
wolffd@0: comps = [1:dim];
wolffd@0: remove_tag = 0;
wolffd@0: if struct_mode, sNorm = sD.comp_norm; else sNorm = []; end
wolffd@0: i=1; 
wolffd@0: while i<=length(varargin), 
wolffd@0:   argok = 1; 
wolffd@0:   if ischar(varargin{i}), 
wolffd@0:     switch varargin{i}, 
wolffd@0:      % argument IDs
wolffd@0:      case 'comps', i=i+1; comps = varargin{i}; 
wolffd@0:      case {'norm','sNorm','som_norm'}, i=i+1; sNorm = varargin{i};
wolffd@0:      % unambiguous values
wolffd@0:      case 'remove', remove_tag = 1;
wolffd@0:      otherwise argok=0; 
wolffd@0:     end    
wolffd@0:   elseif isnumeric(varargin{i}), 
wolffd@0:     comps = varargin{i};
wolffd@0:   elseif isstruct(varargin{i}), 
wolffd@0:     sNorm = varargin{i};
wolffd@0:   elseif iscell(varargin{i}), 
wolffd@0:     sNorm = varargin{i};
wolffd@0:   else
wolffd@0:     argok = 0; 
wolffd@0:   end
wolffd@0:   if ~argok, 
wolffd@0:     disp(['(som_denormalize) Ignoring invalid argument #' num2str(i+1)]); 
wolffd@0:   end
wolffd@0:   i = i+1; 
wolffd@0: end
wolffd@0: 
wolffd@0: % check comps
wolffd@0: if ischar(comps), comps = [1:dim]; end
wolffd@0: if isempty(comps), return; end
wolffd@0: if size(comps,1)>1, comps = comps'; end  % make it a row vector
wolffd@0: 
wolffd@0: % sNorm
wolffd@0: % check out the given normalization
wolffd@0: % (and if necessary, copy it for each specified component)
wolffd@0: if isstruct(sNorm),
wolffd@0:   switch sNorm(1).type, 
wolffd@0:    case {'som_map','som_data'}, csNorm = sNorm(1).comp_norm; 
wolffd@0:    case {'som_norm'}, for i=comps, csNorm{i} = sNorm; end
wolffd@0:    otherwise, 
wolffd@0:     error('Invalid struct for sNorm.')
wolffd@0:   end
wolffd@0: elseif iscell(sNorm), 
wolffd@0:   csNorm = sNorm; 
wolffd@0: else
wolffd@0:   error('Illegal value for sNorm.')
wolffd@0: end
wolffd@0: 
wolffd@0: % check that csNorm and comps possibly agree
wolffd@0: if max(comps) > length(csNorm), 
wolffd@0:   error('Given normalizations does not match the components.')
wolffd@0: end  
wolffd@0: if length(csNorm) ~= dim, 
wolffd@0:   error('Given normalizations does not match data dimension.')
wolffd@0: end  
wolffd@0: 
wolffd@0: %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
wolffd@0: %% action
wolffd@0: 
wolffd@0: % undo the normalizations 
wolffd@0: for i = comps, 
wolffd@0:   len = length(csNorm{i});
wolffd@0:   for j=len:-1:1, 
wolffd@0:     sN = csNorm{i}(j); 
wolffd@0:     if struct_mode, 
wolffd@0:       if strcmp(sN.status,'done'), 
wolffd@0: 	[x,sN] = som_norm_variable(D(:,i), sN, 'undo'); 
wolffd@0: 	D(:,i) = x; 
wolffd@0: 	csNorm{i}(j) = sN; 
wolffd@0:       end      
wolffd@0:     else
wolffd@0:       D(:,i) = som_norm_variable(D(:,i), sN, 'undo'); 
wolffd@0:     end
wolffd@0:   end
wolffd@0: end
wolffd@0: 
wolffd@0: % remove normalizations
wolffd@0: if struct_mode & remove_tag, 
wolffd@0:   for i = comps, csNorm{i} = []; end
wolffd@0: end
wolffd@0: 
wolffd@0: %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
wolffd@0: %% output 
wolffd@0: 
wolffd@0: 
wolffd@0: if struct_mode, 
wolffd@0:   switch sD.type
wolffd@0:    case 'som_map', sD.codebook = D; 
wolffd@0:    case 'som_data', sD.data = D; 
wolffd@0:    otherwise, error('Illegal struct.')
wolffd@0:   end
wolffd@0:   sD.comp_norm = csNorm; 
wolffd@0: else
wolffd@0:   sD = D;
wolffd@0: end
wolffd@0: 
wolffd@0: %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
wolffd@0: 
wolffd@0: 
wolffd@0: