Contents

grade()

Usage:

grade(x [ ,down:T]), x REAL or CHARACTER or a structure with all REAL
  or all CHARACTER components.

Keywords: ordering

grade(a) is similar to rank(a), producing a vector, matrix, or array of
the same shape as a, but with the indices of the minimum, second
smallest, ..., maximum values in each column in place of the ranks.
For example, if x is vector(3.2,1.4,5.6,2.1), grade(x) computes the
vector(2,4,1,3) since x[2], x[4], x[1], x[3] are the values of x in
increasing order.  The basic property is that, if x is a vector,
x[grade(x)] is the same as sort(x).

Argument a can be either REAL or CHARACTER.  When a is CHARACTER,
ordering is based on the ASCII collating sequence.  See sort() for the
complete ordering of characters.

grade(a,down:T) or simply grade(a,T) does the same except the underlying
sort is in decreasing order so that grade(a,down:T)[1,] computes the
case (row) numbers of the maximum of each column.

Two uses for grade() are x[grade(x[,i]),] which reorders the rows of x
so that column i is ordered, and grade(x)[1,] or grade(x,T)[1,] which
compute the indices of the minimum and maximum of each column of x.

It is also acceptable for x to be a structure, whose non-structure
components are all REAL or all CHARACTER.  In that case, grade() returns
a structure of the same form, each of whose non-structure components is
the result of applying grade() to the corresponding component of x.

If there are k MISSING values of a column, the last k elements of the
result are the indices of the MISSING values.  For example,
grade(vector(3,1,?,0,?)) computes vector(4,2,1,3,5).  Consequently, if x
is a vector, x[grade(x)] and x[grade(x,down:T)] compute the same vector
as sort(x) and sort(x,down:T), even when there are MISSING values.

When there are ties, the values computed for the tied elements are
unpredictable but still satisfy that x[grade(x),] is the same as
sort(x).

Examples:
  Cmd> grade(vector(27,22,25,26,22,21,?,24))
yields vector(6,2,5,8,3, 4,1,7), since the minimum (21) is in position
6, the 2nd and 3rd smallest (22) are in positions 2 and 5, . . ., the
largest (27) is in position 1, and the only MISSING value is in position
7.

  Cmd> grade(vector(27,22,25,26,22,21,?,24),down:T)
yields vector(1,4,3,8,2,5,6,7).

See also sort(), rank().