function P = sammon(D, P, varargin)
%SAMMON Computes Sammon's mapping of a data set.
%
% P = sammon(D, P, [value], [mode], [alpha], [Mdist])
%
% P = sammon(D,2); % projection to 2-dim space
% P = sammon(sMap,3); % projects the codebook vectors
% P = sammon(sMap,3,[],[],[],Md) % uses distance matrix Md
% som_grid(sMap,'Coord',P) % visualization of map projection
%
% Input and output arguments ([]'s are optional):
% D (matrix) size dlen x dim, data to be projected
% (struct) data or map struct
% P (scalar) output dimension
% (matrix) size dlen x odim, initial projection matrix
% [value] (scalar) all different modes (the next argument) require
% a value, default = 100
% [mode] (string) 'steps' or 'errlimit' or 'errchange' or 'seconds',
% see below, default is 'steps'
% [alpha] (scalar) iteration step size, default = 0.2
% [Dist] (matrix) pairwise distance matrix, size dlen x dlen.
% If the distances in the input space should
% be calculated otherwise than as euclidian
% distances, the distance from each vector
% to each other vector can be given here,
% size dlen x dlen. For example PDIST
% function can be used to calculate the
% distances: Dist = squareform(pdist(D,'mahal'));
%
% P (matrix) size dlen x odim, the projections
%
% The output dimension must be 2 or higher but (naturally) lower
% than data set dimension.
%
% The mode argument determines the end condition for iteration. If
% the mode argument is used, also the value argument has to be
% specified. Different mode possibilities are:
% 'steps' the iteration is terminated when it is run <value>
% 'errlimit' steps, the iteration is terminated when projection error
% is lower than <value>,
% 'errchange' the iteration is terminated when change between
% projection error on two successive iteration rounds
% is less than <value> percent of total error, and
% 'seconds' the iteration is terminated after <value> seconds
% of iteration.
%
% See also CCA, PCAPROJ, SOM_GRID.
% Reference: Sammon, J.W. Jr., "A nonlinear mapping for data
% structure analysis", IEEE Transactions on Computers, vol. C-18,
