naginterfaces.library.sort.arbitrary_​rank

naginterfaces.library.sort.arbitrary_rank(compar, m1, m2, data=None)

arbitrary_rank ranks arbitrary data according to a user-supplied comparison function.

For full information please refer to the NAG Library document for m01dz

https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/m01/m01dzf.html

Parameters

comparcallable retval = compar(i, j, data=None)

$compar$ must specify the relative ordering of any two data items; it must return $True$ if item $i$ must come strictly after item $j$ in the rank ordering.

Parameters

iint

$i$ and $j$ identify the data items to be compared.

jint

$i$ and $j$ identify the data items to be compared.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns

retvalbool

Must be $True$ if item $i$ must come strictly after item $j$ in the rank ordering.

m1int

Note: this argument represents an array index; the value you supply must be base-1 for compatibility with the NAG Engine.

$m1$ must specify the lower bound of the range of data items to be ranked, and the range of ranks to be assigned. Specifically, arbitrary_rank ranks the data items identified by integers in the range $m1$ to $m2$, and assigns ranks in the range $m1$ to $m2$ which are stored in elements $m1-1$ to $m2-1$ of $irank$.

m2int

Note: this argument represents an array index; the value you supply must be base-1 for compatibility with the NAG Engine.

$m2$ must specify the upper bound of the range of data items to be ranked, and the range of ranks to be assigned. Specifically, arbitrary_rank ranks the data items identified by integers in the range $m1$ to $m2$, and assigns ranks in the range $m1$ to $m2$ which are stored in elements $m1-1$ to $m2-1$ of $irank$.

dataarbitrary, optional

User-communication data for callback functions.

Returns

irankint, ndarray, shape $\left(m2\right)$

Elements $m1-1$ to $m2-1$ of $irank$ contain the ranks of the data items $m1$ to $m2$. Note that the ranks are in the range $m1$ to $m2$: thus, if item $i$ is first in the rank ordering, $irank[i-1]$ contains $m1$.

Raises

NagValueError

(errno $1$)

On entry, $m1=⟨value⟩$ and $m2=⟨value⟩$.

Constraint: $m1\le m2$.

(errno $1$)

On entry, $m1=⟨value⟩$.

Constraint: $m1\ge 1$.

(errno $1$)

On entry, $m2=⟨value⟩$.

Constraint: $m2\ge 1$.

Notes

No equivalent traditional C interface for this routine exists in the NAG Library.

arbitrary_rank is a general purpose function for ranking arbitrary data. arbitrary_rank does not access the data directly; instead it calls $compar$ to determine the relative ordering of any two data items. The data items are identified simply by an integer in the range $m1$ to $m2$.

arbitrary_rank 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$.

References

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