nag_sort_intvec_rank (m01db) 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: $iv (m2)$ – int64int32nag_int array: Elements m1 to m2 of iv must contain integer values to be ranked.
2: $m1$ – int64int32nag_int scalar: The index of the first element of iv 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 iv.
m2 must specify the index of the last element of iv 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 iv. Note that the ranks are in the range m1 to m2: thus, if $iv (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 integers and ranks them in descending order.

Open in the MATLAB editor: m01db_example

function m01db_example


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

iv = [int64(34) 44 89 64 69 69 23 1 999 65 22 76];
m1 = int64(1);
order = 'Descending';

[irank, ifail] = m01db(iv, m1, order);

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

m01db example results

   Data   Ranks

     34      9
     44      8
     89      2
     64      7
     69      4
     69      5
     23     10
      1     12
    999      1
     65      6
     22     11
     76      3

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

Chapter Contents

Chapter Introduction

NAG Toolbox