rank                  package:base                  R Documentation

_S_a_m_p_l_e _R_a_n_k_s

_D_e_s_c_r_i_p_t_i_o_n:

     Returns the sample ranks of the values in a vector.  Ties (i.e.,
     equal values) and missing values can be handled in several ways.

_U_s_a_g_e:

     rank(x, na.last = TRUE,
          ties.method = c("average", "first", "random", "max", "min"))

_A_r_g_u_m_e_n_t_s:

       x: a numeric, complex, character or logical vector.

 na.last: for controlling the treatment of 'NA's. If 'TRUE', missing
          values in the data are put last; if 'FALSE', they are put
          first; if 'NA', they are removed; if '"keep"' they are kept
          with rank 'NA'.

ties.method: a character string specifying how ties are treated, see
          'Details'; can be abbreviated.

_D_e_t_a_i_l_s:

     If all components are different (and no 'NA's), the ranks are well
     defined, with values in 'seq_len(x)'.  With some values equal
     (called 'ties'), the argument 'ties.method' determines the result
     at the corresponding indices. The '"first"' method results in a
     permutation with increasing values at each index set of ties. The
     '"random"' method puts these in random order whereas the default,
     '"average"', replaces them by their mean, and '"max"' and '"min"'
     replaces them by their maximum and minimum respectively, the
     latter being the typical sports ranking.

     'NA' values are never considered to be equal: for 'na.last = TRUE'
     and 'na.last = FALSE' they are given distinct ranks in the order
     in which they occur in 'x'.

     *NB*: 'rank' is not itself generic but 'xtfrm' is, and
     'rank(xtfrm(x), ....)' will have the desired result if there is a
     'xtfrm' method.  Otherwise, 'rank' will make use of '==', '>' and
     'is.na' methods for classed objects, possibly rather slowly.

_V_a_l_u_e:

     A numeric vector of the same length as 'x' with names copied from
     'x' (unless 'na.last = NA', when missing values are removed).  The
     vector is of integer type unless 'ties.method = "average"' when it
     is of double type (whether or not there are any ties).

_R_e_f_e_r_e_n_c_e_s:

     Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) _The New S
     Language_. Wadsworth & Brooks/Cole.

_S_e_e _A_l_s_o:

     'order' and 'sort'.

_E_x_a_m_p_l_e_s:

     (r1 <- rank(x1 <- c(3, 1, 4, 15, 92)))
     x2 <- c(3, 1, 4, 1, 5, 9, 2, 6, 5, 3, 5)
     names(x2) <- letters[1:11]
     (r2 <- rank(x2)) # ties are averaged

     ## rank() is "idempotent": rank(rank(x)) == rank(x) :
     stopifnot(rank(r1) == r1, rank(r2) == r2)

     ## ranks without averaging
     rank(x2, ties.method= "first")  # first occurrence wins
     rank(x2, ties.method= "random") # ties broken at random
     rank(x2, ties.method= "random") # and again

     ## keep ties ties, no average
     (rma <- rank(x2, ties.method= "max"))  # as used classically
     (rmi <- rank(x2, ties.method= "min"))  # as in Sports
     stopifnot(rma + rmi == round(r2 + r2))