som_denormalize

Purpose

 Undo normalizations of data structs/sets.

Syntax

  sS = som_denormalize(sS)
  sS = som_denormalize(...,'argID',value,...);
  sS = som_denormalize(...,value,...);
   D = som_denormalize(D,sNorm)

Description

 This function is used to undo normalizations of data structs/sets. If a
 data/map struct is given, all normalizations in the '.comp_norm' field are
 undone and, thus, the values in the original data context are returned. If
 a matrix is given, the normalizations to undo must be given as the second
 argument. SOM_DENORMALIZE actually uses function SOM_NORM_VARIABLE to
 handle the normalization operations, and only handles the data struct/set
 specific stuff itself.

 Normalizations are always one-variable operations. In the data and map
 structs the normalization information for each component is saved in the
 '.comp_norm' field, which is a cell array of length dim. Each cell
 contains normalizations for one vector component in a
 struct array of normalization structs. Each component may have different
 amounts of different kinds of normalizations. Typically, all
 normalizations are either 'undone' or 'done', but in special situations
 this may not be the case. The easiest way to check out the status of the
 normalizations is to use function SOM_INFO, e.g. som_info(sS,3)

Required input arguments

   sS                The data to which the denormalization is applied.
            (struct) Data or map struct. The normalizations in the 
                     '.comp_norm' field are undone for the specified 
                     components.
            (matrix) Data matrix. The normalization to undo must be
                     given in the second argument.

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.

   sNorm    *(struct) Normalization struct, or an array of structs, which
                      is undone for all specified components. If the 
                      '.status' field of the struct(s) is 'uninit', 
                      the undoing operation is interrupted - it cannot be 
                      done. Alternatively, the struct may be map or 
                      data struct in which case its '.comp_norm' field 
                      is used (see the cell array option below).
            *(cell array) In practice, the '.comp_norm' field of 
                      a data/map struct. The length of the array 
                      must be equal to the dimension of the given 
                      data set (sS). Each cell contains the
                      normalization(s) for one component. Only the
                       normalizations listed in comps argument are
                      undone though.

   'remove' *(string) If 'remove' tag is specified, the
                      normalization operations are not only undone, 
                      they are also removed from the struct.

   'comps'  *(vector) The components which are denormalized.
                      Default is to undo all components.
            *(string) 'all'

Output arguments

   sS                Modified and/or updated data.
            (struct) If a struct was given as input argument, the
                     same struct is returned with denormalized data and
                     updated '.comp_norm' fields. 
            (matrix) If a matrix was given as input argument, the 
                     denormalized data matrix is returned.

Examples

  To undo normalization of a data/map struct: 

    sD = som_denormalize(sD); 
    sM = som_denormalize(sM); 

  To completely remove the normalizations, use the 'remove' tag: 

    sD = som_denormalize(sD,'remove');

  To undo only a few selected components, use the comps argument: 

    sD = som_denormalize(sD,[1 3:5]); 

  To denormalize a set of values from a data set D (which must be 
  of equal dimension as the data in sD): 

    D = som_denormalize(D,sD); 
  or 
    D = som_denormalize(D,sD.comp_norm); 
  only denormalize a few components
    D = som_denormalize(D,sD,[1 3:5]); 

  Assuming you have a few values of a certain vector component (i)
  in a vector (x) which you want to denormalize: 

    xorig = som_denormalize(x,sD.comp_norm{i}); 
  or using SOM_NORM_VARIABLE
    xorig = som_norm_variable(x,sD.comp_norm{i},'undo');

  To check out the status of normalization in a struct use SOM_INFO: 

    som_info(sM,3)
    som_info(sD,3)

See also