function d=cosmo_pdist(x, distance)
% compute pair-wise distance between samples in a matrix
%
% d=cosmo_pdist(x[, distance])
%
% Inputs:
% x PxM matrix for P samples and M features
% distance distance metric: one of 'euclidean' (default),
% 'correlation' (computing one-minus-correlation), or any
% other metric supported by matlab's built-in 'pdist'
%
% Outputs:
% d 1xN row vector with pairwise distances, where N=M*(M-1),
% containing the distances of the lower triangle of the
% distance matrix
%
% Examples:
% data=[1 4 3; 2 2 3; 4 2 0;0 1 1];
% % compute pair-wise distances with euclidean distance metric.
% % since there are 4 samples, there are 4*3/2=6 pairs of samples.
% d=cosmo_pdist(data);
% cosmo_disp(d);
% %|| [ 2.24 4.69 3.74 3.61 3 4.24 ]
% %
% % this gives the same output
% d=cosmo_pdist(data,'euclidean');
% cosmo_disp(d);
% %|| [ 2.24 4.69 3.74 3.61 3 4.24 ]
% %
% % compute distances with one-minus-correlation distance metric
% d_c=cosmo_pdist(data,'correlation');
% cosmo_disp(d_c);
% %|| [ 0.811 1.65 0.0551 1.87 0.5 1.87 ]
%
% Notes:
% - this function provides a native implementation for 'euclidean' and
% 'correlation'; other distance metrics require the pdist function
% supplied in the matlab stats toolbox, or the octave statistics
% package
% - the rationale for providing this function is to support pair-wise
% distances on platforms without the stats toolbox
% - to compute pair-wise distances on a dataset struct, use
% cosmo_dissimilarity_matrix_measure
% - the output of this function can be given to [cosmo_]squareform to
% recreate a PxP distance matrix
%
% See also: cosmo_dissimilarity_matrix_measure, cosmo_squareform
%
% # For CoSMoMVPA's copyright information and license terms, #
% # see the COPYING file distributed with CoSMoMVPA. #
