function ranks=cosmo_tiedrank(data, dim)
% Compute ranks for the input along the specified dimension
%
% ranks=cosmo_tiedrank(data[, dim])
%
% Inputs:
% data numeric N-dimensional array
% dim optional dimension along which the ranks
% are computed (default: 1)
%
% Output:
% ranks numeric N-dimensional array with the same
% size as the input containing the rank of
% each vector along the dim-th dimension.
% Equal values have the same rank, which is
% the average of the rank the values would
% have if they differed by a minimal amount.
% NaN values in the input result in a NaN
% values in the output at the corresponding
% locations.
% If dim is greater than the number of
% dimensions in data, then all values in rank
% are one (or NaN of the corresponding value
% in data is NaN).
%
% Examples:
% cosmo_tiedrank([1 2 2],2)
% %|| [ 1 2.5 2.5]
%
% cosmo_tiedrank([NaN 2 2;3 NaN 4],1)
% %|| [ NaN 1 1;
% %|| 1 NaN 2];
%
% cosmo_tiedrank([NaN 2 2;3 NaN 4],2)
% %|| [ NaN 1.5 1.5;
% %|| 1 NaN 2];
%
% cosmo_tiedrank([2 4 3 3 3 3 5 5 5],2)
% %|| [ 1.0 6.0 3.5 3.5 3.5 3.5 8.0 8.0 8.0 ]
%
% Notes:
% - Unlike the Matlab builtin function 'tiedrank' (part of the statistics
% toolbox), the meaning of the second argument is the dimension along
% which the ranks are computed.
%
% # For CoSMoMVPA's copyright information and license terms, #
% # see the COPYING file distributed with CoSMoMVPA. #
