Mercurial > hg > camir-aes2014

annotate toolboxes/MIRtoolbox1.3.2/somtoolbox/som_denormalize.m @ 0:e9a9cd732c1e tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
first hg version after svn
author wolffd
date Tue, 10 Feb 2015 15:05:51 +0000
parents
children
rev   line source
wolffd@0 1 function sD = som_denormalize(sD,varargin)
wolffd@0 2
wolffd@0 3 %SOM_DENORMALIZE Denormalize data.
wolffd@0 4 %
wolffd@0 5 % sS = som_denormalize(sS, [argID, value, ...])
wolffd@0 6 %
wolffd@0 7 % sS = som_denormalize(sS)
wolffd@0 8 % sS = som_denormalize(sS,[1:3 10],'remove')
wolffd@0 9 % D = som_denormalize(D,sM.comp_norm)
wolffd@0 10 % D = som_denormalize(D,sM,[1:3 10])
wolffd@0 11 %
wolffd@0 12 % Input and output arguments ([]'s are optional):
wolffd@0 13 % sS The data to which the denormalization is applied.
wolffd@0 14 % The modified and updated data is returned.
wolffd@0 15 % (struct) data or map struct
wolffd@0 16 % (matrix) data matrix (a matrix is also returned)
wolffd@0 17 % [argID, (string) See below. The values which are unambiguous can
wolffd@0 18 % value] (varies) be given without the preceeding argID.
wolffd@0 19 %
wolffd@0 20 % Here are the valid argument IDs and corresponding values. The values which
wolffd@0 21 % are unambiguous (marked with '*') can be given without the preceeding argID.
wolffd@0 22 % 'norm' *(struct) Normalization struct, or an array of such.
wolffd@0 23 % Alternatively, a map/data struct can be given
wolffd@0 24 % in which case its '.comp_norm' field is used
wolffd@0 25 % (see below).
wolffd@0 26 % *(cell array) Of normalization structs. Typically, the
wolffd@0 27 % '.comp_norm' field of a map/data struct. The
wolffd@0 28 % length of the array must be equal to data dimension.
wolffd@0 29 % 'remove' *(string) If 'remove' tag is specified, the
wolffd@0 30 % normalization operations are not only undone,
wolffd@0 31 % they are also removed from the struct.
wolffd@0 32 % 'comps' *(vector) the components to which the denormalization is
wolffd@0 33 % applied, default is [1:dim] ie. all components
wolffd@0 34 %
wolffd@0 35 % For more help, try 'type som_denormalize' or check out online documentation.
wolffd@0 36 % See also SOM_NORMALIZE, SOM_NORM_VARIABLE, SOM_INFO.
wolffd@0 37
wolffd@0 38 %%%%%%%%%%%%% DETAILED DESCRIPTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
wolffd@0 39 %
wolffd@0 40 % som_denormalize
wolffd@0 41 %
wolffd@0 42 % PURPOSE
wolffd@0 43 %
wolffd@0 44 % Undo normalizations of data structs/sets.
wolffd@0 45 %
wolffd@0 46 % SYNTAX
wolffd@0 47 %
wolffd@0 48 % sS = som_denormalize(sS)
wolffd@0 49 % sS = som_denormalize(...,'argID',value,...);
wolffd@0 50 % sS = som_denormalize(...,value,...);
wolffd@0 51 % D = som_denormalize(D,sNorm)
wolffd@0 52 %
wolffd@0 53 % DESCRIPTION
wolffd@0 54 %
wolffd@0 55 % This function is used to undo normalizations of data structs/sets. If a
wolffd@0 56 % data/map struct is given, all normalizations in the '.comp_norm' field are
wolffd@0 57 % undone and, thus, the values in the original data context are returned. If
wolffd@0 58 % a matrix is given, the normalizations to undo must be given as the second
wolffd@0 59 % argument. SOM_DENORMALIZE actually uses function SOM_NORM_VARIABLE to
wolffd@0 60 % handle the normalization operations, and only handles the data struct/set
wolffd@0 61 % specific stuff itself.
wolffd@0 62 %
wolffd@0 63 % Normalizations are always one-variable operations. In the data and map
wolffd@0 64 % structs the normalization information for each component is saved in the
wolffd@0 65 % '.comp_norm' field, which is a cell array of length dim. Each cell
wolffd@0 66 % contains normalizations for one vector component in a
wolffd@0 67 % struct array of normalization structs. Each component may have different
wolffd@0 68 % amounts of different kinds of normalizations. Typically, all
wolffd@0 69 % normalizations are either 'undone' or 'done', but in special situations
wolffd@0 70 % this may not be the case. The easiest way to check out the status of the
wolffd@0 71 % normalizations is to use function SOM_INFO, e.g. som_info(sS,3)
wolffd@0 72 %
wolffd@0 73 % REQUIRED INPUT ARGUMENTS
wolffd@0 74 %
wolffd@0 75 % sS The data to which the denormalization is applied.
wolffd@0 76 % (struct) Data or map struct. The normalizations in the
wolffd@0 77 % '.comp_norm' field are undone for the specified
wolffd@0 78 % components.
wolffd@0 79 % (matrix) Data matrix. The normalization to undo must be
wolffd@0 80 % given in the second argument.
wolffd@0 81 %
wolffd@0 82 % OPTIONAL INPUT ARGUMENTS
wolffd@0 83 %
wolffd@0 84 % argID (string) Argument identifier string (see below).
wolffd@0 85 % value (varies) Value for the argument (see below).
wolffd@0 86 %
wolffd@0 87 % The optional arguments can be given as 'argID',value -pairs. If an
wolffd@0 88 % argument is given value multiple times, the last one is used. The
wolffd@0 89 % valid IDs and corresponding values are listed below. The values
wolffd@0 90 % which are unambiguous (marked with '*') can be given without the
wolffd@0 91 % preceeding argID.
wolffd@0 92 %
wolffd@0 93 % sNorm *(struct) Normalization struct, or an array of structs, which
wolffd@0 94 % is undone for all specified components. If the
wolffd@0 95 % '.status' field of the struct(s) is 'uninit',
wolffd@0 96 % the undoing operation is interrupted - it cannot be
wolffd@0 97 % done. Alternatively, the struct may be map or
wolffd@0 98 % data struct in which case its '.comp_norm' field
wolffd@0 99 % is used (see the cell array option below).
wolffd@0 100 % *(cell array) In practice, the '.comp_norm' field of
wolffd@0 101 % a data/map struct. The length of the array
wolffd@0 102 % must be equal to the dimension of the given
wolffd@0 103 % data set (sS). Each cell contains the
wolffd@0 104 % normalization(s) for one component. Only the
wolffd@0 105 % normalizations listed in comps argument are
wolffd@0 106 % undone though.
wolffd@0 107 %
wolffd@0 108 % 'remove' *(string) If 'remove' tag is specified, the
wolffd@0 109 % normalization operations are not only undone,
wolffd@0 110 % they are also removed from the struct.
wolffd@0 111 %
wolffd@0 112 % 'comps' *(vector) The components which are denormalized.
wolffd@0 113 % Default is to undo all components.
wolffd@0 114 % *(string) 'all'
wolffd@0 115 %
wolffd@0 116 % OUTPUT ARGUMENTS
wolffd@0 117 %
wolffd@0 118 % sS Modified and/or updated data.
wolffd@0 119 % (struct) If a struct was given as input argument, the
wolffd@0 120 % same struct is returned with denormalized data and
wolffd@0 121 % updated '.comp_norm' fields.
wolffd@0 122 % (matrix) If a matrix was given as input argument, the
wolffd@0 123 % denormalized data matrix is returned.
wolffd@0 124 %
wolffd@0 125 % EXAMPLES
wolffd@0 126 %
wolffd@0 127 % To undo normalization of a data/map struct:
wolffd@0 128 %
wolffd@0 129 % sD = som_denormalize(sD);
wolffd@0 130 % sM = som_denormalize(sM);
wolffd@0 131 %
wolffd@0 132 % To completely remove the normalizations, use the 'remove' tag:
wolffd@0 133 %
wolffd@0 134 % sD = som_denormalize(sD,'remove');
wolffd@0 135 %
wolffd@0 136 % To undo only a few selected components, use the comps argument:
wolffd@0 137 %
wolffd@0 138 % sD = som_denormalize(sD,[1 3:5]);
wolffd@0 139 %
wolffd@0 140 % To denormalize a set of values from a data set D (which must be
wolffd@0 141 % of equal dimension as the data in sD):
wolffd@0 142 %
wolffd@0 143 % D = som_denormalize(D,sD);
wolffd@0 144 % or
wolffd@0 145 % D = som_denormalize(D,sD.comp_norm);
wolffd@0 146 % only denormalize a few components
wolffd@0 147 % D = som_denormalize(D,sD,[1 3:5]);
wolffd@0 148 %
wolffd@0 149 % Assuming you have a few values of a certain vector component (i)
wolffd@0 150 % in a vector (x) which you want to denormalize:
wolffd@0 151 %
wolffd@0 152 % xorig = som_denormalize(x,sD.comp_norm{i});
wolffd@0 153 % or using SOM_NORM_VARIABLE
wolffd@0 154 % xorig = som_norm_variable(x,sD.comp_norm{i},'undo');
wolffd@0 155 %
wolffd@0 156 % To check out the status of normalization in a struct use SOM_INFO:
wolffd@0 157 %
wolffd@0 158 % som_info(sM,3)
wolffd@0 159 % som_info(sD,3)
wolffd@0 160 %
wolffd@0 161 % SEE ALSO
wolffd@0 162 %
wolffd@0 163 % som_normalize Add/apply/redo normalizations of a data struct/set.
wolffd@0 164 % som_norm_variable Normalization operations for a set of scalar values.
wolffd@0 165 % som_info User-friendly information of SOM Toolbox structs.
wolffd@0 166
wolffd@0 167 % Copyright (c) 1998-2000 by the SOM toolbox programming team.
wolffd@0 168 % http://www.cis.hut.fi/projects/somtoolbox/
wolffd@0 169
wolffd@0 170 % Version 2.0beta juuso 151199 150300
wolffd@0 171
wolffd@0 172 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
wolffd@0 173 %% check arguments
wolffd@0 174
wolffd@0 175 error(nargchk(1, 3, nargin)); % check no. of input arguments is correct
wolffd@0 176
wolffd@0 177 % sD
wolffd@0 178 struct_mode = isstruct(sD);
wolffd@0 179 if struct_mode,
wolffd@0 180 switch sD.type
wolffd@0 181 case 'som_map', D = sD.codebook;
wolffd@0 182 case 'som_data', D = sD.data;
wolffd@0 183 otherwise, error('Illegal struct.')
wolffd@0 184 end
wolffd@0 185 else
wolffd@0 186 D = sD;
wolffd@0 187 end
wolffd@0 188 [dlen dim] = size(D);
wolffd@0 189
wolffd@0 190 % varargin
wolffd@0 191 comps = [1:dim];
wolffd@0 192 remove_tag = 0;
wolffd@0 193 if struct_mode, sNorm = sD.comp_norm; else sNorm = []; end
wolffd@0 194 i=1;
wolffd@0 195 while i<=length(varargin),
wolffd@0 196 argok = 1;
wolffd@0 197 if ischar(varargin{i}),
wolffd@0 198 switch varargin{i},
wolffd@0 199 % argument IDs
wolffd@0 200 case 'comps', i=i+1; comps = varargin{i};
wolffd@0 201 case {'norm','sNorm','som_norm'}, i=i+1; sNorm = varargin{i};
wolffd@0 202 % unambiguous values
wolffd@0 203 case 'remove', remove_tag = 1;
wolffd@0 204 otherwise argok=0;
wolffd@0 205 end
wolffd@0 206 elseif isnumeric(varargin{i}),
wolffd@0 207 comps = varargin{i};
wolffd@0 208 elseif isstruct(varargin{i}),
wolffd@0 209 sNorm = varargin{i};
wolffd@0 210 elseif iscell(varargin{i}),
wolffd@0 211 sNorm = varargin{i};
wolffd@0 212 else
wolffd@0 213 argok = 0;
wolffd@0 214 end
wolffd@0 215 if ~argok,
wolffd@0 216 disp(['(som_denormalize) Ignoring invalid argument #' num2str(i+1)]);
wolffd@0 217 end
wolffd@0 218 i = i+1;
wolffd@0 219 end
wolffd@0 220
wolffd@0 221 % check comps
wolffd@0 222 if ischar(comps), comps = [1:dim]; end
wolffd@0 223 if isempty(comps), return; end
wolffd@0 224 if size(comps,1)>1, comps = comps'; end % make it a row vector
wolffd@0 225
wolffd@0 226 % sNorm
wolffd@0 227 % check out the given normalization
wolffd@0 228 % (and if necessary, copy it for each specified component)
wolffd@0 229 if isstruct(sNorm),
wolffd@0 230 switch sNorm(1).type,
wolffd@0 231 case {'som_map','som_data'}, csNorm = sNorm(1).comp_norm;
wolffd@0 232 case {'som_norm'}, for i=comps, csNorm{i} = sNorm; end
wolffd@0 233 otherwise,
wolffd@0 234 error('Invalid struct for sNorm.')
wolffd@0 235 end
wolffd@0 236 elseif iscell(sNorm),
wolffd@0 237 csNorm = sNorm;
wolffd@0 238 else
wolffd@0 239 error('Illegal value for sNorm.')
wolffd@0 240 end
wolffd@0 241
wolffd@0 242 % check that csNorm and comps possibly agree
wolffd@0 243 if max(comps) > length(csNorm),
wolffd@0 244 error('Given normalizations does not match the components.')
wolffd@0 245 end
wolffd@0 246 if length(csNorm) ~= dim,
wolffd@0 247 error('Given normalizations does not match data dimension.')
wolffd@0 248 end
wolffd@0 249
wolffd@0 250 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
wolffd@0 251 %% action
wolffd@0 252
wolffd@0 253 % undo the normalizations
wolffd@0 254 for i = comps,
wolffd@0 255 len = length(csNorm{i});
wolffd@0 256 for j=len:-1:1,
wolffd@0 257 sN = csNorm{i}(j);
wolffd@0 258 if struct_mode,
wolffd@0 259 if strcmp(sN.status,'done'),
wolffd@0 260 [x,sN] = som_norm_variable(D(:,i), sN, 'undo');
wolffd@0 261 D(:,i) = x;
wolffd@0 262 csNorm{i}(j) = sN;
wolffd@0 263 end
wolffd@0 264 else
wolffd@0 265 D(:,i) = som_norm_variable(D(:,i), sN, 'undo');
wolffd@0 266 end
wolffd@0 267 end
wolffd@0 268 end
wolffd@0 269
wolffd@0 270 % remove normalizations
wolffd@0 271 if struct_mode & remove_tag,
wolffd@0 272 for i = comps, csNorm{i} = []; end
wolffd@0 273 end
wolffd@0 274
wolffd@0 275 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
wolffd@0 276 %% output
wolffd@0 277
wolffd@0 278
wolffd@0 279 if struct_mode,
wolffd@0 280 switch sD.type
wolffd@0 281 case 'som_map', sD.codebook = D;
wolffd@0 282 case 'som_data', sD.data = D;
wolffd@0 283 otherwise, error('Illegal struct.')
wolffd@0 284 end
wolffd@0 285 sD.comp_norm = csNorm;
wolffd@0 286 else
wolffd@0 287 sD = D;
wolffd@0 288 end
wolffd@0 289
wolffd@0 290 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
wolffd@0 291
wolffd@0 292
wolffd@0 293