%DISNORM Trainable mapping for dissimilarity matrix normalization
%
% V = DISNORM(D,OPT)
% V = D*DISNORM([],OPT)
% V = D*DISNORM(OPT)
% F = E*V
%
% INPUT
% D NxN dissimilarity matrix or dataset, which defines the norm
% E Matrix to be normalized, e.g. D itself
% OPT 'max' : maximum dissimilarity is set to 1 by global rescaling
% 'mean': average dissimilarity is set to 1 by global rescaling (default)
%
% OUTPUT
% V Trained mapping
% F Normalized dissimilarity data
%
% DEFAULT
% OPT = 'mean'
%
% DESCRIPTION
% Operation on dissimilarity matrices, like the computation of classifiers
% in dissimilarity space, may depend on the scaling of the dissimilarities
% (a single scalar for the entire matrix). This routine computes a scaling
% for a giving matrix, e.g. a training set and applies it to other
% matrices, e.g. the same training set or based on a test set.
%
% Note that DNORM = (DISNORM*MAPEX); F = D*DNORM is equivalent to
% F = D*DISNORM(D). So the user defined DNORM can be treated as a fixed
% mapping for normalizing dissimilarity matrices by themselves.
%
% SEE ALSO (<a href="http://37steps.com/prtools">PRTools Guide</a>)
% DATASETS, MAPPINGS, MAPEX
% Copyright: R.P.W. Duin, r.p.w.duin@37steps.com
function out = disnorm(varargin)
argin = shiftargin(varargin,'char');
argin = setdefaults(argin,[],'mean');
if mapping_task(argin,'definition')
% call like U=disnorm or U=disnorm('mean') or U=disnorm([],'mean')
out = define_mapping(argin,'untrained');
out = setname(out,'Disnorm');
elseif mapping_task(argin,'training')
% call like W=disnorm(D,'mean') or W=D*U
[D,opt] = deal(argin{:});
if ~isdataset(D)
D = prdataset(D,1);
D = setfeatlab(D,getlabels(D));
end
if strcmpi(opt,'mean')
n = size(D,1);
m = sum(sum(+D))/(n*(n-1));
elseif strcmpi(opt,'max')
m = max(D(:));
else
error('Wrong OPT')
end
out = prmapping(mfilename,'trained',{m},[],size(D,2),size(D,2));
elseif mapping_task(argin,'trained execution')
% call like E=D*W
[D,W] = deal(argin{:});
m = getdata(W,1);
out = D./m;
else
error('Illegal input')
end