% -*- texinfo -*-
% @deftypefn {Function File} @var{y} = pdist (@var{x})
% @deftypefnx {Function File} @var{y} = pdist (@var{x}, @var{metric})
% @deftypefnx {Function File} @var{y} = pdist (@var{x}, @var{metric}, @var{metricarg}, @dots{})
%
% Return the distance between any two rows in @var{x}.
%
% @var{x} is the @var{n}x@var{d} matrix representing @var{q} row vectors of
% size @var{d}.
%
% The output is a dissimilarity matrix formatted as a row vector
% @var{y}, @math{(n-1)*n/2} long, where the distances are in
% the order [(1, 2) (1, 3) @dots{} (2, 3) @dots{} (n-1, n)]. You can
% use the @code{squareform} function to display the distances between
% the vectors arranged into an @var{n}x@var{n} matrix.
%
% @code{metric} is an optional argument specifying how the distance is
% computed. It can be any of the following ones, defaulting to
% 'euclidean', or a user defined function that takes two arguments
% @var{x} and @var{y} plus any number of optional arguments,
% where @var{x} is a row vector and and @var{y} is a matrix having the
% same number of columns as @var{x}. @code{metric} returns a column
% vector where row @var{i} is the distance between @var{x} and row
% @var{i} of @var{y}. Any additional arguments after the @code{metric}
% are passed as metric (@var{x}, @var{y}, @var{metricarg1},
% @var{metricarg2} @dots{}).
%
% Predefined distance functions are:
%
% @table @samp
% @item 'euclidean'
% Euclidean distance (default).
%
% @item 'seuclidean'
% Standardized Euclidean distance. Each coordinate in the sum of
% squares is inverse weighted by the sample variance of that
% coordinate.
%
% @item 'mahalanobis'
% Mahalanobis distance: @seealso{mahalanobis}.
%
% @item 'cityblock'
% City Block metric, aka Manhattan distance.
%
% @item 'minkowski'
% Minkowski metric. Accepts a numeric parameter @var{p}: for @var{p}=1
% this is the same as the cityblock metric, with @var{p}=2 (default) it
% is equal to the euclidean metric.
%
% @item 'cosine'
% One minus the cosine of the included angle between rows, seen as
% vectors.
%
% @item 'correlation'
% One minus the sample correlation between points (treated as
% sequences of values).
%
% @item 'spearman'
% One minus the sample Spearman's rank correlation between
% observations, treated as sequences of values.
%
% @item 'hamming'
% Hamming distance: the quote of the number of coordinates that differ.
%
% @item 'jaccard'
% One minus the Jaccard coefficient, the quote of nonzero
% coordinates that differ.
%
% @item 'chebychev'
% Chebychev distance: the maximum coordinate difference.
% @end table
% @seealso{linkage,squareform}
% @end deftypefn