wolffd@0: function [mqe,tge] = som_quality(sMap, D)
wolffd@0: 
wolffd@0: %SOM_QUALITY Calculate the mean quantization and topographic error.
wolffd@0: %
wolffd@0: % [qe,te] = som_quality(sMap, D)
wolffd@0: %
wolffd@0: %  qe = som_quality(sMap,D);
wolffd@0: %  [qe,te] = som_quality(sMap,sD);
wolffd@0: %
wolffd@0: %  Input and output arguments: 
wolffd@0: %   sMap     (struct) a map struct
wolffd@0: %   D                 the data
wolffd@0: %            (struct) a data struct
wolffd@0: %            (matrix) a data matrix, size dlen x dim
wolffd@0: %
wolffd@0: %   qe       (scalar) mean quantization error
wolffd@0: %   te       (scalar) topographic error
wolffd@0: %
wolffd@0: % The issue of SOM quality is a complicated one. Typically two
wolffd@0: % evaluation criterias are used: resolution and topology preservation.
wolffd@0: % If the dimension of the data set is higher than the dimension of the 
wolffd@0: % map grid, these usually become contradictory goals. 
wolffd@0: %
wolffd@0: % The first value returned by this function measures resolution and the
wolffd@0: % second the topology preservation.
wolffd@0: %  qe : Average distance between each data vector and its BMU.
wolffd@0: %  te : Topographic error, the proportion of all data vectors
wolffd@0: %       for which first and second BMUs are not adjacent units.
wolffd@0: %
wolffd@0: % NOTE: when calculating BMUs of data vectors, the mask of the given 
wolffd@0: %       map is used.
wolffd@0: %
wolffd@0: % For more help, try 'type som_quality' or check out the online documentation.
wolffd@0: % See also SOM_BMUS.
wolffd@0: 
wolffd@0: %%%%%%%%%%%%% DETAILED DESCRIPTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
wolffd@0: %
wolffd@0: % som_quality
wolffd@0: %
wolffd@0: % PURPOSE
wolffd@0: %
wolffd@0: % Calculates two quality measures for the given map.
wolffd@0: %
wolffd@0: % SYNTAX
wolffd@0: %
wolffd@0: %  qe = som_quality(sM,sD);
wolffd@0: %  qe = som_quality(sM,D);
wolffd@0: %  [qe,te] = som_quality(...);
wolffd@0: %
wolffd@0: % DESCRIPTION
wolffd@0: %
wolffd@0: % This function measures the quality of the given map. The measures are
wolffd@0: % data-dependent: they measure the map in terms of the given
wolffd@0: % data. Typically, the quality of the map is measured in terms of the
wolffd@0: % training data. The returned quality measures are average quantization
wolffd@0: % error and topographic error.
wolffd@0: %
wolffd@0: % The issue of SOM quality is a complicated one. Typically two evaluation
wolffd@0: % criterias are used: resolution and topology preservation. There are
wolffd@0: % many ways to measure them. The ones implemented here were chosen for
wolffd@0: % their simplicity.
wolffd@0: %
wolffd@0: %  qe : Average distance between each data vector and its BMU.
wolffd@0: %       Measures map resolution.
wolffd@0: %  te : Topographic error, the proportion of all data vectors
wolffd@0: %       for which first and second BMUs are not adjacent units.
wolffd@0: %       Measures topology preservation.
wolffd@0: %
wolffd@0: % NOTE: when calculating BMUs of data vectors, the mask of the given 
wolffd@0: %       map is used. The mask affects the quantization errors, too.
wolffd@0: %       If you want the quantization errors without the weighting given
wolffd@0: %       by the mask, you can use the following code: 
wolffd@0: %         bmus = som_bmus(sMap,D); % this uses the mask in finding the BMUs
wolffd@0: %         for i=1:length(bmus), 
wolffd@0: %           dx = sMap.codebook(bmus(i),:)-D(i,:); % m - x
wolffd@0: %           dx(isnan(dx)) = 0;                    % remove NaNs 
wolffd@0: %           qerr(i) = sqrt(sum(dx.^2));           % euclidian distance
wolffd@0: %         end
wolffd@0: %         qe = mean(qerr); % average quantization error
wolffd@0: %
wolffd@0: % Please note that you should _not_ trust the measures blindly. Generally,
wolffd@0: % both measures give the best results when the map has overfitted the
wolffd@0: % data. This may happen when the number of map units is as large or larger
wolffd@0: % than the number of training samples. Beware when you have such a case.
wolffd@0: %
wolffd@0: % REFERENCES
wolffd@0: %
wolffd@0: % Kohonen, T., "Self-Organizing Map", 2nd ed., Springer-Verlag, 
wolffd@0: %    Berlin, 1995, pp. 113.
wolffd@0: % Kiviluoto, K., "Topology Preservation in Self-Organizing Maps", 
wolffd@0: %    in the proceeding of International Conference on Neural
wolffd@0: %    Networks (ICNN), 1996, pp. 294-299.
wolffd@0: %
wolffd@0: % INPUT ARGUMENTS
wolffd@0: %
wolffd@0: %  sMap    (struct) Map struct.
wolffd@0: %  D                The data to be used.
wolffd@0: %          (matrix) A data matrix, size dlen x dim.
wolffd@0: %          (struct) A data struct.
wolffd@0: %
wolffd@0: % OUTPUT ARGUMENTS
wolffd@0: % 
wolffd@0: %  qe      (scalar) mean quantization error
wolffd@0: %  te      (scalar) topographic error
wolffd@0: %
wolffd@0: % EXAMPLES
wolffd@0: %
wolffd@0: %  qe = som_quality(sMap,D);
wolffd@0: %  [qe,te] = som_quality(sMap,sD);
wolffd@0: %
wolffd@0: % SEE ALSO
wolffd@0: % 
wolffd@0: %  som_bmus         Find BMUs for the given set of data vectors.
wolffd@0: 
wolffd@0: % Copyright (c) 1997-2000 by the SOM toolbox programming team.
wolffd@0: % http://www.cis.hut.fi/projects/somtoolbox/
wolffd@0: 
wolffd@0: % Version 1.0beta juuso 220997
wolffd@0: % Version 2.0beta juuso 151199
wolffd@0: 
wolffd@0: %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
wolffd@0: %% check arguments
wolffd@0: 
wolffd@0: % input arguments
wolffd@0: if nargin < 2, error('Not enough input arguments.'); end
wolffd@0: 
wolffd@0: % data
wolffd@0: if isstruct(D), D = D.data; end
wolffd@0: [dlen dim] = size(D);
wolffd@0: 
wolffd@0: % calculate topographic error, too?
wolffd@0: if nargout==1, b=1; else b=[1:2]; end
wolffd@0: [bmus qerrs]= som_bmus(sMap,D,b);
wolffd@0: inds = find(~isnan(bmus(:,1)));
wolffd@0: bmus = bmus(inds,:);
wolffd@0: qerrs = qerrs(inds,:);
wolffd@0: l = length(inds);
wolffd@0: if ~l, error('Empty data set.'); end
wolffd@0: 
wolffd@0: % mean quantization error
wolffd@0: mqe = mean(qerrs(:,1));
wolffd@0: 
wolffd@0: if length(b)==2, % topographic error
wolffd@0:   Ne = full(som_unit_neighs(sMap.topol));
wolffd@0:   tge = 0;
wolffd@0:   for i=1:l, tge = tge+(Ne(bmus(i,1),bmus(i,2)) ~= 1); end
wolffd@0:   tge = tge / l;
wolffd@0: else
wolffd@0:   tge = NaN;
wolffd@0: end
wolffd@0: 
wolffd@0: return;
wolffd@0: 
wolffd@0: %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
wolffd@0: 
wolffd@0: