nag_sort_realvec_rank (m01da) uses a variant of list-merging, as described on pages 165–166 in Knuth (1973). The function takes advantage of natural ordering in the data, and uses a simple list insertion in a preparatory pass to generate ordered lists of length at least

10

. The ranking is stable: equal elements preserve their ordering in the input data.

References

Knuth D E (1973) The Art of Computer Programming (Volume 3) (2nd Edition) Addison–Wesley

Parameters

Compulsory Input Parameters

1: $rv (m2)$ – double array: Elements m1 to m2 of rv must contain double values to be ranked.
2: $m1$ – int64int32nag_int scalar: The index of the first element of rv to be ranked.

Constraint: $m1 > 0$ .
3: $order$ – string (length ≥ 1): If $order ='A'$ , the values will be ranked in ascending (i.e., nondecreasing) order.
If $order ='D'$ , into descending order.

Constraint: $order ='A'$ or $'D'$ .

Optional Input Parameters

1: $m2$ – int64int32nag_int scalar: Default: the dimension of the array rv.
The index of the last element of rv to be ranked.

Constraint: $m2 \geq m1$ .

Output Parameters

1: $irank (m2)$ – int64int32nag_int array: Elements m1 to m2 of irank contain the ranks of the corresponding elements of rv. Note that the ranks are in the range m1 to m2: thus, if $rv (i)$ is the first element in the rank order, $irank (i)$ is set to m1.
2: $ifail$ – int64int32nag_int scalar: $ifail = 0$ unless the function detects an error (see Error Indicators and Warnings).

Error Indicators and Warnings

Errors or warnings detected by the function:

$ifail = 1$

On entry,	$m2 < 1$ ,
or	$m1 < 1$ ,
or	$m1 > m2$ .

$ifail = 2$

On entry,

order is not 'A' or 'D'.

$ifail = - 99$: An unexpected error has been triggered by this routine. Please contact NAG.

$ifail = - 399$: Your licence key may have expired or may not have been installed correctly.

$ifail = - 999$: Dynamic memory allocation failed.

Accuracy

Not applicable.

Further Comments

The average time taken by the function is approximately proportional to

n \times \log (n)

, where

n = m2 - m1 + 1

Example

This example reads a list of double numbers and ranks them in ascending order.

Open in the MATLAB editor: m01da_example

function m01da_example


fprintf('m01da example results\n\n');

rv = [5.3     4.6     7.8     1.7     5.3     9.9 ...
      3.2     4.3     7.8     4.5     1.2     7.6];

m1 = int64(1);
order = 'Ascending';
[irank, ifail] = m01da(rv, m1, order);

fprintf('   Data   Ranks\n\n');
for i = 1:numel(rv)
  fprintf('%7.1f%7d\n',rv(i),irank(i));
end

m01da example results

   Data   Ranks

    5.3      7
    4.6      6
    7.8     10
    1.7      2
    5.3      8
    9.9     12
    3.2      3
    4.3      4
    7.8     11
    4.5      5
    1.2      1
    7.6      9

PDF version (NAG web site, 64-bit version, 64-bit version)

Chapter Contents

Chapter Introduction

NAG Toolbox