Mercurial > hg > camir-aes2014

comparison toolboxes/MIRtoolbox1.3.2/somtoolbox/som_normalize.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
comparison
equal deleted inserted replaced
-1:000000000000 0:e9a9cd732c1e
1 function sD = som_normalize(sD,method,comps)
2
3 %SOM_NORMALIZE (Re)normalize data or add new normalizations.
4 %
5 % sS = som_normalize(sS,[method],[comps])
6 %
7 % sS = som_normalize(sD)
8 % sS = som_normalize(sS,sNorm)
9 % D = som_normalize(D,'var')
10 % sS = som_normalize(sS,'histC',[1:3 10])
11 %
12 % Input and output arguments ([]'s are optional):
13 % sS The data to which the normalization is applied.
14 % The modified and updated data is returned.
15 % (struct) data or map struct
16 % (matrix) data matrix (a matrix is also returned)
17 % [method] The normalization method(s) to add/use. If missing,
18 % or an empty variable ('') is given, the
19 % normalizations in sS are used.
20 % (string) identifier for a normalization method to be added:
21 % 'var', 'range', 'log', 'logistic', 'histD' or 'histC'.
22 % (struct) Normalization struct, or an array of such.
23 % Alternatively, a map/data struct can be given
24 % in which case its '.comp_norm' field is used
25 % (see below).
26 % (cell array) Of normalization structs. Typically, the
27 % '.comp_norm' field of a map/data struct. The
28 % length of the array must be equal to data dimension.
29 % (cellstr array) norm and denorm operations in a cellstr array
30 % which are evaluated with EVAL command with variable
31 % name 'x' reserved for the variable.
32 % [comps] (vector) the components to which the normalization is
33 % applied, default is [1:dim] ie. all components
34 %
35 % For more help, try 'type som_normalize' or check out online documentation.
36 % See also SOM_DENORMALIZE, SOM_NORM_VARIABLE, SOM_INFO.
37
38 %%%%%%%%%%%%% DETAILED DESCRIPTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
39 %
40 % som_normalize
41 %
42 % PURPOSE
43 %
44 % Add/apply/redo normalization on data structs/sets.
45 %
46 % SYNTAX
47 %
48 % sS = som_normalize(sS)
49 % sS = som_normalize(sS,method)
50 % D = som_normalize(D,sNorm)
51 % sS = som_normalize(sS,csNorm)
52 % sS = som_normalize(...,comps)
53 %
54 % DESCRIPTION
55 %
56 % This function is used to (initialize and) add, redo and apply
57 % normalizations on data/map structs/sets. If a data/map struct is given,
58 % the specified normalizations are added to the '.comp_norm' field of the
59 % struct after ensuring that all normalizations specified therein have
60 % status 'done'. SOM_NORMALIZE actually uses function SOM_NORM_VARIABLE
61 % to handle the normalization operations, and only handles the data
62 % struct/set specific stuff itself.
63 %
64 % The different normalization methods are listed below. For more
65 % detailed descriptions, see SOM_NORM_VARIABLE.
66 %
67 % method description
68 % 'var' Variance is normalized to one (linear operation).
69 % 'range' Values are normalized between [0,1] (linear operation).
70 % 'log' Natural logarithm is applied to the values:
71 % xnew = log(x-m+1)
72 % where m = min(x).
73 % 'logistic' Logistic or softmax trasformation which scales all
74 % possible values between [0,1].
75 % 'histD' Histogram equalization, values scaled between [0,1].
76 % 'histC' Approximate histogram equalization with partially
77 % linear operations. Values scaled between [0,1].
78 % 'eval' freeform operations
79 %
80 % To enable undoing and applying the exactly same normalization to
81 % other data sets, normalization information is saved into a
82 % normalization struct, which has the fields:
83 %
84 % .type ; struct type, ='som_norm'
85 % .method ; normalization method, a string
86 % .params ; normalization parameters
87 % .status ; string: 'uninit', 'undone' or 'done'
88 %
89 % Normalizations are always one-variable operations. In the data and map
90 % structs the normalization information for each component is saved in the
91 % '.comp_norm' field, which is a cell array of length dim. Each cell
92 % contains normalizations for one vector component in a struct array of
93 % normalization structs. Each component may have different amounts of
94 % different kinds of normalizations. Typically, all normalizations are
95 % either 'undone' or 'done', but in special situations this may not be the
96 % case. The easiest way to check out the status of the normalizations is to
97 % use function SOM_INFO, e.g. som_info(sS,3)
98 %
99 % REQUIRED INPUT ARGUMENTS
100 %
101 % sS The data to which the normalization is applied.
102 % (struct) Data or map struct. Before adding any new
103 % normalizations, it is ensured that the
104 % normalizations for the specified components in the
105 % '.comp_norm' field have status 'done'.
106 % (matrix) data matrix
107 %
108 % OPTIONAL INPUT ARGUMENTS
109 %
110 % method The normalization(s) to add/use. If missing,
111 % or an empty variable ('' or []) is given, the
112 % normalizations in the data struct are used.
113 % (string) Identifier for a normalization method to be added:
114 % 'var', 'range', 'log', 'logistic', 'histD' or 'histC'. The
115 % same method is applied to all specified components
116 % (given in comps). The normalizations are first
117 % initialized (for each component separately, of
118 % course) and then applied.
119 % (struct) Normalization struct, or an array of structs, which
120 % is applied to all specified components. If the
121 % '.status' field of the struct(s) is 'uninit',
122 % the normalization(s) is initialized first.
123 % Alternatively, the struct may be map or data struct
124 % in which case its '.comp_norm' field is used
125 % (see the cell array option below).
126 % (cell array) In practice, the '.comp_norm' field of
127 % a data/map struct. The length of the array
128 % must be equal to the dimension of the given
129 % data set (sS). Each cell contains the
130 % normalization(s) for one component. Only the
131 % normalizations listed in comps argument are
132 % applied though.
133 % (cellstr array) norm and denorm operations in a cellstr array
134 % which are evaluated with EVAL command with variable
135 % name 'x' reserved for the variable.
136 %
137 % comps (vector) The components to which the normalization(s) is
138 % applied. Default is to apply to all components.
139 %
140 % OUTPUT ARGUMENTS
141 %
142 % sS Modified and/or updated data.
143 % (struct) If a struct was given as input argument, the
144 % same struct is returned with normalized data and
145 % updated '.comp_norm' fields.
146 % (matrix) If a matrix was given as input argument, the
147 % normalized data matrix is returned.
148 %
149 % EXAMPLES
150 %
151 % To add (initialize and apply) a normalization to a data struct:
152 %
153 % sS = som_normalize(sS,'var');
154 %
155 % This uses 'var'-method to all components. To add a method only to
156 % a few selected components, use the comps argument:
157 %
158 % sS = som_normalize(sS,'log',[1 3:5]);
159 %
160 % To ensure that all normalization operations have indeed been done:
161 %
162 % sS = som_normalize(sS);
163 %
164 % The same for only a few components:
165 %
166 % sS = som_normalize(sS,'',[1 3:5]);
167 %
168 % To apply the normalizations of a data struct sS to a new data set D:
169 %
170 % D = som_normalize(D,sS);
171 % or
172 % D = som_normalize(D,sS.comp_norm);
173 %
174 % To normalize a data set:
175 %
176 % D = som_normalize(D,'histD');
177 %
178 % Note that in this case the normalization information is lost.
179 %
180 % To check out the status of normalization in a struct use SOM_INFO:
181 %
182 % som_info(sS,3)
183 %
184 %
185 % SEE ALSO
186 %
187 % som_denormalize Undo normalizations of a data struct/set.
188 % som_norm_variable Normalization operations for a set of scalar values.
189 % som_info User-friendly information of SOM Toolbox structs.
190
191 % Copyright (c) 1998-2000 by the SOM toolbox programming team.
192 % http://www.cis.hut.fi/projects/somtoolbox/
193
194 % Version 2.0beta juuso 151199 150500
195
196 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
197 %% check arguments
198
199 error(nargchk(1, 3, nargin)); % check no. of input arguments is correct
200
201 % sD
202 struct_mode = isstruct(sD);
203 if struct_mode,
204 switch sD.type
205 case 'som_map', D = sD.codebook;
206 case 'som_data', D = sD.data;
207 otherwise, error('Illegal struct.')
208 end
209 else
210 D = sD;
211 end
212 [dlen dim] = size(D);
213
214 % comps
215 if nargin<3 | (ischar(comps) & strcmp(comps,'all')),
216 comps = [1:dim];
217 end
218 if isempty(comps), return; end
219 if size(comps,1)>1, comps = comps'; end % make it a row vector
220
221 % method
222 csNorm = cell(dim,1);
223 if nargin<2 | isempty(method),
224 if ~struct_mode,
225 warning('No normalization method given. Data left unchanged.');
226 return;
227 end
228 method = '';
229 else
230 % check out the given method
231 % (and if necessary, copy it for each specified component)
232 if ischar(method),
233 switch method,
234 case {'var','range','log','histD','histC','logistic'},
235 sN = som_set('som_norm','method',method);
236 otherwise,
237 error(['Unrecognized method: ' method]);
238 end
239 for i=comps, csNorm{i} = sN; end
240 elseif isstruct(method),
241 switch method(1).type,
242 case {'som_map','som_data'}, csNorm = method(1).comp_norm;
243 case {'som_norm'}, for i=comps, csNorm{i} = method; end
244 otherwise,
245 error('Invalid struct given as normalization method.')
246 end
247 elseif iscellstr(method),
248 [dummy,sN] = som_norm_variable(1,method,'init');
249 for i=comps, csNorm{i} = sN; end
250 elseif iscell(method),
251 csNorm = method;
252 else
253 error('Illegal method argument.')
254 end
255 % check the size of csNorm is the same as data dimension
256 if length(csNorm) ~= dim,
257 error('Given number of normalizations does not match data dimension.')
258 end
259 end
260
261 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
262 %% initialize
263
264 % make sure all the current normalizations for current
265 % components have been done
266 if struct_mode,
267 alldone = 1;
268 for i = comps,
269 for j=1:length(sD.comp_norm{i}),
270 sN = sD.comp_norm{i}(j);
271 if ~strcmp(sN.status,'done'),
272 alldone = 0;
273 [x,sN] = som_norm_variable(D(:,i), sN, 'do');
274 D(:,i) = x;
275 sD.comp_norm{i}(j) = sN;
276 end
277 end
278 end
279 if isempty(method),
280 if alldone,
281 warning('No ''undone'' normalizations found. Data left unchanged.');
282 else
283 fprintf(1,'Normalizations have been redone.\n');
284 end
285 end
286 end
287
288 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
289 %% action
290
291 % add the new normalizations to the old ones
292 for i = comps,
293 if ~isempty(csNorm{i}),
294 [x,sN] = som_norm_variable(D(:,i), csNorm{i}, 'do');
295 D(:,i) = x;
296 if struct_mode,
297 if isempty(sD.comp_norm{i}), sD.comp_norm{i} = sN;
298 else sD.comp_norm{i} = [sD.comp_norm{i}, sN]; end
299 end
300 end
301 end
302
303 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
304 %% output
305
306 if struct_mode,
307 switch sD.type
308 case 'som_map', sD.codebook = D;
309 case 'som_data', sD.data = D;
310 otherwise, error('Illegal struct.')
311 end
312 else
313 sD = D;
314 end
315
316 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
317
318
319