Daniel@0: function sD = som_normalize(sD,method,comps) Daniel@0: Daniel@0: %SOM_NORMALIZE (Re)normalize data or add new normalizations. Daniel@0: % Daniel@0: % sS = som_normalize(sS,[method],[comps]) Daniel@0: % Daniel@0: % sS = som_normalize(sD) Daniel@0: % sS = som_normalize(sS,sNorm) Daniel@0: % D = som_normalize(D,'var') Daniel@0: % sS = som_normalize(sS,'histC',[1:3 10]) Daniel@0: % Daniel@0: % Input and output arguments ([]'s are optional): Daniel@0: % sS The data to which the normalization is applied. Daniel@0: % The modified and updated data is returned. Daniel@0: % (struct) data or map struct Daniel@0: % (matrix) data matrix (a matrix is also returned) Daniel@0: % [method] The normalization method(s) to add/use. If missing, Daniel@0: % or an empty variable ('') is given, the Daniel@0: % normalizations in sS are used. Daniel@0: % (string) identifier for a normalization method to be added: Daniel@0: % 'var', 'range', 'log', 'logistic', 'histD' or 'histC'. Daniel@0: % (struct) Normalization struct, or an array of such. Daniel@0: % Alternatively, a map/data struct can be given Daniel@0: % in which case its '.comp_norm' field is used Daniel@0: % (see below). Daniel@0: % (cell array) Of normalization structs. Typically, the Daniel@0: % '.comp_norm' field of a map/data struct. The Daniel@0: % length of the array must be equal to data dimension. Daniel@0: % (cellstr array) norm and denorm operations in a cellstr array Daniel@0: % which are evaluated with EVAL command with variable Daniel@0: % name 'x' reserved for the variable. Daniel@0: % [comps] (vector) the components to which the normalization is Daniel@0: % applied, default is [1:dim] ie. all components Daniel@0: % Daniel@0: % For more help, try 'type som_normalize' or check out online documentation. Daniel@0: % See also SOM_DENORMALIZE, SOM_NORM_VARIABLE, SOM_INFO. Daniel@0: Daniel@0: %%%%%%%%%%%%% DETAILED DESCRIPTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Daniel@0: % Daniel@0: % som_normalize Daniel@0: % Daniel@0: % PURPOSE Daniel@0: % Daniel@0: % Add/apply/redo normalization on data structs/sets. Daniel@0: % Daniel@0: % SYNTAX Daniel@0: % Daniel@0: % sS = som_normalize(sS) Daniel@0: % sS = som_normalize(sS,method) Daniel@0: % D = som_normalize(D,sNorm) Daniel@0: % sS = som_normalize(sS,csNorm) Daniel@0: % sS = som_normalize(...,comps) Daniel@0: % Daniel@0: % DESCRIPTION Daniel@0: % Daniel@0: % This function is used to (initialize and) add, redo and apply Daniel@0: % normalizations on data/map structs/sets. If a data/map struct is given, Daniel@0: % the specified normalizations are added to the '.comp_norm' field of the Daniel@0: % struct after ensuring that all normalizations specified therein have Daniel@0: % status 'done'. SOM_NORMALIZE actually uses function SOM_NORM_VARIABLE Daniel@0: % to handle the normalization operations, and only handles the data Daniel@0: % struct/set specific stuff itself. Daniel@0: % Daniel@0: % The different normalization methods are listed below. For more Daniel@0: % detailed descriptions, see SOM_NORM_VARIABLE. Daniel@0: % Daniel@0: % method description Daniel@0: % 'var' Variance is normalized to one (linear operation). Daniel@0: % 'range' Values are normalized between [0,1] (linear operation). Daniel@0: % 'log' Natural logarithm is applied to the values: Daniel@0: % xnew = log(x-m+1) Daniel@0: % where m = min(x). Daniel@0: % 'logistic' Logistic or softmax trasformation which scales all Daniel@0: % possible values between [0,1]. Daniel@0: % 'histD' Histogram equalization, values scaled between [0,1]. Daniel@0: % 'histC' Approximate histogram equalization with partially Daniel@0: % linear operations. Values scaled between [0,1]. Daniel@0: % 'eval' freeform operations Daniel@0: % Daniel@0: % To enable undoing and applying the exactly same normalization to Daniel@0: % other data sets, normalization information is saved into a Daniel@0: % normalization struct, which has the fields: Daniel@0: % Daniel@0: % .type ; struct type, ='som_norm' Daniel@0: % .method ; normalization method, a string Daniel@0: % .params ; normalization parameters Daniel@0: % .status ; string: 'uninit', 'undone' or 'done' Daniel@0: % Daniel@0: % Normalizations are always one-variable operations. In the data and map Daniel@0: % structs the normalization information for each component is saved in the Daniel@0: % '.comp_norm' field, which is a cell array of length dim. Each cell Daniel@0: % contains normalizations for one vector component in a struct array of Daniel@0: % normalization structs. Each component may have different amounts of Daniel@0: % different kinds of normalizations. Typically, all normalizations are Daniel@0: % either 'undone' or 'done', but in special situations this may not be the Daniel@0: % case. The easiest way to check out the status of the normalizations is to Daniel@0: % use function SOM_INFO, e.g. som_info(sS,3) Daniel@0: % Daniel@0: % REQUIRED INPUT ARGUMENTS Daniel@0: % Daniel@0: % sS The data to which the normalization is applied. Daniel@0: % (struct) Data or map struct. Before adding any new Daniel@0: % normalizations, it is ensured that the Daniel@0: % normalizations for the specified components in the Daniel@0: % '.comp_norm' field have status 'done'. Daniel@0: % (matrix) data matrix Daniel@0: % Daniel@0: % OPTIONAL INPUT ARGUMENTS Daniel@0: % Daniel@0: % method The normalization(s) to add/use. If missing, Daniel@0: % or an empty variable ('' or []) is given, the Daniel@0: % normalizations in the data struct are used. Daniel@0: % (string) Identifier for a normalization method to be added: Daniel@0: % 'var', 'range', 'log', 'logistic', 'histD' or 'histC'. The Daniel@0: % same method is applied to all specified components Daniel@0: % (given in comps). The normalizations are first Daniel@0: % initialized (for each component separately, of Daniel@0: % course) and then applied. Daniel@0: % (struct) Normalization struct, or an array of structs, which Daniel@0: % is applied to all specified components. If the Daniel@0: % '.status' field of the struct(s) is 'uninit', Daniel@0: % the normalization(s) is initialized first. Daniel@0: % Alternatively, the struct may be map or data struct Daniel@0: % in which case its '.comp_norm' field is used Daniel@0: % (see the cell array option below). Daniel@0: % (cell array) In practice, the '.comp_norm' field of Daniel@0: % a data/map struct. The length of the array Daniel@0: % must be equal to the dimension of the given Daniel@0: % data set (sS). Each cell contains the Daniel@0: % normalization(s) for one component. Only the Daniel@0: % normalizations listed in comps argument are Daniel@0: % applied though. Daniel@0: % (cellstr array) norm and denorm operations in a cellstr array Daniel@0: % which are evaluated with EVAL command with variable Daniel@0: % name 'x' reserved for the variable. Daniel@0: % Daniel@0: % comps (vector) The components to which the normalization(s) is Daniel@0: % applied. Default is to apply to all components. Daniel@0: % Daniel@0: % OUTPUT ARGUMENTS Daniel@0: % Daniel@0: % sS Modified and/or updated data. Daniel@0: % (struct) If a struct was given as input argument, the Daniel@0: % same struct is returned with normalized data and Daniel@0: % updated '.comp_norm' fields. Daniel@0: % (matrix) If a matrix was given as input argument, the Daniel@0: % normalized data matrix is returned. Daniel@0: % Daniel@0: % EXAMPLES Daniel@0: % Daniel@0: % To add (initialize and apply) a normalization to a data struct: Daniel@0: % Daniel@0: % sS = som_normalize(sS,'var'); Daniel@0: % Daniel@0: % This uses 'var'-method to all components. To add a method only to Daniel@0: % a few selected components, use the comps argument: Daniel@0: % Daniel@0: % sS = som_normalize(sS,'log',[1 3:5]); Daniel@0: % Daniel@0: % To ensure that all normalization operations have indeed been done: Daniel@0: % Daniel@0: % sS = som_normalize(sS); Daniel@0: % Daniel@0: % The same for only a few components: Daniel@0: % Daniel@0: % sS = som_normalize(sS,'',[1 3:5]); Daniel@0: % Daniel@0: % To apply the normalizations of a data struct sS to a new data set D: Daniel@0: % Daniel@0: % D = som_normalize(D,sS); Daniel@0: % or Daniel@0: % D = som_normalize(D,sS.comp_norm); Daniel@0: % Daniel@0: % To normalize a data set: Daniel@0: % Daniel@0: % D = som_normalize(D,'histD'); Daniel@0: % Daniel@0: % Note that in this case the normalization information is lost. Daniel@0: % Daniel@0: % To check out the status of normalization in a struct use SOM_INFO: Daniel@0: % Daniel@0: % som_info(sS,3) Daniel@0: % Daniel@0: % Daniel@0: % SEE ALSO Daniel@0: % Daniel@0: % som_denormalize Undo normalizations of a data struct/set. Daniel@0: % som_norm_variable Normalization operations for a set of scalar values. Daniel@0: % som_info User-friendly information of SOM Toolbox structs. Daniel@0: Daniel@0: % Copyright (c) 1998-2000 by the SOM toolbox programming team. Daniel@0: % http://www.cis.hut.fi/projects/somtoolbox/ Daniel@0: Daniel@0: % Version 2.0beta juuso 151199 150500 Daniel@0: Daniel@0: %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Daniel@0: %% check arguments Daniel@0: Daniel@0: error(nargchk(1, 3, nargin)); % check no. of input arguments is correct Daniel@0: Daniel@0: % sD Daniel@0: struct_mode = isstruct(sD); Daniel@0: if struct_mode, Daniel@0: switch sD.type Daniel@0: case 'som_map', D = sD.codebook; Daniel@0: case 'som_data', D = sD.data; Daniel@0: otherwise, error('Illegal struct.') Daniel@0: end Daniel@0: else Daniel@0: D = sD; Daniel@0: end Daniel@0: [dlen dim] = size(D); Daniel@0: Daniel@0: % comps Daniel@0: if nargin<3 | (ischar(comps) & strcmp(comps,'all')), Daniel@0: comps = [1:dim]; Daniel@0: end Daniel@0: if isempty(comps), return; end Daniel@0: if size(comps,1)>1, comps = comps'; end % make it a row vector Daniel@0: Daniel@0: % method Daniel@0: csNorm = cell(dim,1); Daniel@0: if nargin<2 | isempty(method), Daniel@0: if ~struct_mode, Daniel@0: warning('No normalization method given. Data left unchanged.'); Daniel@0: return; Daniel@0: end Daniel@0: method = ''; Daniel@0: else Daniel@0: % check out the given method Daniel@0: % (and if necessary, copy it for each specified component) Daniel@0: if ischar(method), Daniel@0: switch method, Daniel@0: case {'var','range','log','histD','histC','logistic'}, Daniel@0: sN = som_set('som_norm','method',method); Daniel@0: otherwise, Daniel@0: error(['Unrecognized method: ' method]); Daniel@0: end Daniel@0: for i=comps, csNorm{i} = sN; end Daniel@0: elseif isstruct(method), Daniel@0: switch method(1).type, Daniel@0: case {'som_map','som_data'}, csNorm = method(1).comp_norm; Daniel@0: case {'som_norm'}, for i=comps, csNorm{i} = method; end Daniel@0: otherwise, Daniel@0: error('Invalid struct given as normalization method.') Daniel@0: end Daniel@0: elseif iscellstr(method), Daniel@0: [dummy,sN] = som_norm_variable(1,method,'init'); Daniel@0: for i=comps, csNorm{i} = sN; end Daniel@0: elseif iscell(method), Daniel@0: csNorm = method; Daniel@0: else Daniel@0: error('Illegal method argument.') Daniel@0: end Daniel@0: % check the size of csNorm is the same as data dimension Daniel@0: if length(csNorm) ~= dim, Daniel@0: error('Given number of normalizations does not match data dimension.') Daniel@0: end Daniel@0: end Daniel@0: Daniel@0: %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Daniel@0: %% initialize Daniel@0: Daniel@0: % make sure all the current normalizations for current Daniel@0: % components have been done Daniel@0: if struct_mode, Daniel@0: alldone = 1; Daniel@0: for i = comps, Daniel@0: for j=1:length(sD.comp_norm{i}), Daniel@0: sN = sD.comp_norm{i}(j); Daniel@0: if ~strcmp(sN.status,'done'), Daniel@0: alldone = 0; Daniel@0: [x,sN] = som_norm_variable(D(:,i), sN, 'do'); Daniel@0: D(:,i) = x; Daniel@0: sD.comp_norm{i}(j) = sN; Daniel@0: end Daniel@0: end Daniel@0: end Daniel@0: if isempty(method), Daniel@0: if alldone, Daniel@0: warning('No ''undone'' normalizations found. Data left unchanged.'); Daniel@0: else Daniel@0: fprintf(1,'Normalizations have been redone.\n'); Daniel@0: end Daniel@0: end Daniel@0: end Daniel@0: Daniel@0: %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Daniel@0: %% action Daniel@0: Daniel@0: % add the new normalizations to the old ones Daniel@0: for i = comps, Daniel@0: if ~isempty(csNorm{i}), Daniel@0: [x,sN] = som_norm_variable(D(:,i), csNorm{i}, 'do'); Daniel@0: D(:,i) = x; Daniel@0: if struct_mode, Daniel@0: if isempty(sD.comp_norm{i}), sD.comp_norm{i} = sN; Daniel@0: else sD.comp_norm{i} = [sD.comp_norm{i}, sN]; end Daniel@0: end Daniel@0: end Daniel@0: end Daniel@0: Daniel@0: %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Daniel@0: %% output Daniel@0: Daniel@0: if struct_mode, Daniel@0: switch sD.type Daniel@0: case 'som_map', sD.codebook = D; Daniel@0: case 'som_data', sD.data = D; Daniel@0: otherwise, error('Illegal struct.') Daniel@0: end Daniel@0: else Daniel@0: sD = D; Daniel@0: end Daniel@0: Daniel@0: %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Daniel@0: Daniel@0: Daniel@0: