Daniel@0: function [adm,admu,tdmu] = som_distortion(sM, D, arg1, arg2)
Daniel@0: 
Daniel@0: %SOM_DISTORTION Calculate distortion measure for the map.
Daniel@0: %
Daniel@0: % [adm,admu,tdmu] = som_distortion(sMap, D, [radius], ['prob'])
Daniel@0: %
Daniel@0: %  adm = som_distortion(sMap,D);
Daniel@0: %  [adm,admu] = som_distortion(sMap,D);
Daniel@0: %  som_show(sMap,'color',admu);
Daniel@0: %
Daniel@0: %  Input and output arguments: 
Daniel@0: %   sMap     (struct) a map struct
Daniel@0: %   D        (struct) a data struct
Daniel@0: %            (matrix) size dlen x dim, a data matrix
Daniel@0: %   [radius] (scalar) neighborhood function radius to be used.
Daniel@0: %                     Defaults to the last radius_fin in the 
Daniel@0: %                     trainhist field of the map struct, or 1 if
Daniel@0: %                     that is missing.
Daniel@0: %   ['prob'] (string) If given, this argument forces the 
Daniel@0: %                     neigborhood function values for each map
Daniel@0: %                     unit to be normalized so that they sum to 1.
Daniel@0: %
Daniel@0: %   adm      (scalar) average distortion measure (sum(dm)/dlen)
Daniel@0: %   admu     (vector) size munits x 1, average distortion in each unit 
Daniel@0: %   tdmu     (vector) size munits x 1, total distortion for each unit
Daniel@0: %
Daniel@0: % The distortion measure is defined as: 
Daniel@0: %                                           2
Daniel@0: %    E = sum sum h(bmu(i),j) ||m(j) - x(i)|| 
Daniel@0: %         i   j    
Daniel@0: % 
Daniel@0: % where m(i) is the ith prototype vector of SOM, x(j) is the jth data
Daniel@0: % vector, and h(.,.) is the neighborhood function. In case of fixed
Daniel@0: % neighborhood and discreet data, the distortion measure can be
Daniel@0: % interpreted as the energy function of the SOM. Note, though, that
Daniel@0: % the learning rule that follows from the distortion measure is
Daniel@0: % different from the SOM training rule, so SOM only minimizes the
Daniel@0: % distortion measure approximately.
Daniel@0: % 
Daniel@0: % If the 'prob' argument is given, the distortion measure can be 
Daniel@0: % interpreted as an expected quantization error when the neighborhood 
Daniel@0: % function values give the likelyhoods of accidentally assigning 
Daniel@0: % vector j to unit i. The normal quantization error is a special case 
Daniel@0: % of this with zero incorrect assignement likelihood. 
Daniel@0: % 
Daniel@0: % NOTE: when calculating BMUs and distances, the mask of the given 
Daniel@0: %       map is used.
Daniel@0: %
Daniel@0: % See also SOM_QUALITY, SOM_BMUS, SOM_HITS.
Daniel@0: 
Daniel@0: % Reference: Kohonen, T., "Self-Organizing Map", 2nd ed., 
Daniel@0: %    Springer-Verlag, Berlin, 1995, pp. 120-121.
Daniel@0: %
Daniel@0: %    Graepel, T., Burger, M. and Obermayer, K., 
Daniel@0: %    "Phase Transitions in Stochastic Self-Organizing Maps",
Daniel@0: %    Physical Review E, Vol 56, No 4, pp. 3876-3890 (1997).
Daniel@0: 
Daniel@0: % Contributed to SOM Toolbox vs2, Feb 3rd, 2000 by Juha Vesanto
Daniel@0: % Copyright (c) by Juha Vesanto
Daniel@0: % http://www.cis.hut.fi/projects/somtoolbox/
Daniel@0: 
Daniel@0: % Version 2.0beta juuso 030200
Daniel@0: 
Daniel@0: %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Daniel@0: %% check arguments
Daniel@0: 
Daniel@0: % input arguments
Daniel@0: if nargin < 2, error('Not enough input arguments.'); end
Daniel@0: 
Daniel@0: % map
Daniel@0: M = sM.codebook;
Daniel@0: munits = prod(sM.topol.msize);
Daniel@0: 
Daniel@0: % data
Daniel@0: if isstruct(D), D = D.data; end
Daniel@0: [dlen dim] = size(D);
Daniel@0: 
Daniel@0: % arg1, arg2
Daniel@0: rad = NaN;
Daniel@0: normalize = 0;
Daniel@0: if nargin>2, 
Daniel@0:   if isnumeric(arg1), rad = arg1;
Daniel@0:   elseif ischar(arg1) & strcmp(arg1,'prob'), normalize = 0;
Daniel@0:   end
Daniel@0: end
Daniel@0: if nargin>3, 
Daniel@0:   if isnumeric(arg2), rad = arg2;
Daniel@0:   elseif ischar(arg2) & strcmp(arg2,'prob'), normalize = 0;
Daniel@0:   end
Daniel@0: end
Daniel@0: 
Daniel@0: % neighborhood radius
Daniel@0: if isempty(rad) | isnan(rad), 
Daniel@0:   if ~isempty(sM.trainhist), rad = sM.trainhist(end).radius_fin;
Daniel@0:   else rad = 1; 
Daniel@0:   end
Daniel@0: end
Daniel@0: if rad<eps, rad = eps; end
Daniel@0: 
Daniel@0: % neighborhood  
Daniel@0: Ud = som_unit_dists(sM.topol); 
Daniel@0: switch sM.neigh, 
Daniel@0:  case 'bubble',   H = (Ud <= rad);
Daniel@0:  case 'gaussian', H = exp(-(Ud.^2)/(2*rad*rad)); 
Daniel@0:  case 'cutgauss', H = exp(-(Ud.^2)/(2*rad*rad)) .* (Ud <= rad);
Daniel@0:  case 'ep',       H = (1 - (Ud.^2)/rad) .* (Ud <= rad);
Daniel@0: end  
Daniel@0: if normalize, 
Daniel@0:   for i=1:munits, H(:,i) = H(:,i)/sum(H(:,i)); end
Daniel@0: end
Daniel@0: 
Daniel@0: % total distortion measure
Daniel@0: mu_x_1 = ones(munits,1);
Daniel@0: tdmu = zeros(munits,1);
Daniel@0: hits = zeros(munits,1);
Daniel@0: for i=1:dlen,
Daniel@0:   x = D(i,:);                        % data sample
Daniel@0:   known = ~isnan(x);                 % its known components
Daniel@0:   Dx = M(:,known) - x(mu_x_1,known); % each map unit minus the vector
Daniel@0:   dist2 = (Dx.^2)*sM.mask(known);    % squared distances  
Daniel@0:   [qerr bmu] = min(dist2);           % find BMU
Daniel@0:   tdmu = tdmu + dist2.*H(:,bmu);     % add to distortion measure
Daniel@0:   hits(bmu) = hits(bmu)+1;           % add to hits
Daniel@0: end 
Daniel@0: 
Daniel@0: % average distortion per unit
Daniel@0: admu = tdmu; 
Daniel@0: ind = find(hits>0);
Daniel@0: admu(ind) = admu(ind) ./ hits(ind);
Daniel@0:   
Daniel@0: % average distortion measure
Daniel@0: adm = sum(tdmu)/dlen;
Daniel@0: 
Daniel@0: return;
Daniel@0: 
Daniel@0: %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Daniel@0: 
Daniel@0: