1% File src/library/base/man/rank.Rd
2% Part of the R package, https://www.R-project.org
3% Copyright 1995-2017 R Core Team
4% Distributed under GPL 2 or later
5
6\name{rank}
7\alias{rank}
8\title{Sample Ranks}
9\description{
10  Returns the sample ranks of the values in a vector.  Ties (i.e., equal
11  values) and missing values can be handled in several ways.
12}
13\usage{
14rank(x, na.last = TRUE,
15     ties.method = c("average", "first", "last", "random", "max", "min"))
16}
17\arguments{% x: actually, only  x[!is.na(x)]  must be such a vector
18  \item{x}{a numeric, complex, character or logical vector.}
19  \item{na.last}{for controlling the treatment of \code{\link{NA}}s.
20    If \code{TRUE}, missing values in the data are put last; if
21    \code{FALSE}, they are put first; if \code{NA}, they are removed; if
22    \code{"keep"} they are kept with rank \code{NA}.}
23  \item{ties.method}{a character string specifying how ties are treated,
24    see \sQuote{Details}; can be abbreviated.}
25}
26\references{
27  Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
28  \emph{The New S Language}.
29  Wadsworth & Brooks/Cole.
30}
31\details{
32  If all components are different (and no \code{NA}s), the ranks are
33  well defined, with values in \code{seq_along(x)}.  With some values equal
34  (called \sQuote{ties}), the argument \code{ties.method} determines the
35  result at the corresponding indices.  The \code{"first"} method results
36  in a permutation with increasing values at each index set of ties, and
37  analogously \code{"last"} with decreasing values.  The
38  \code{"random"} method puts these in random order whereas the
39  default, \code{"average"}, replaces them by their mean, and
40  \code{"max"} and \code{"min"} replaces them by their maximum and
41  minimum respectively, the latter being the typical sports
42  ranking.
43
44  \code{NA} values are never considered to be equal: for \code{na.last =
45    TRUE} and \code{na.last = FALSE} they are given distinct ranks in
46  the order in which they occur in \code{x}.
47
48  \strong{NB}: \code{rank} is not itself generic but \code{\link{xtfrm}}
49  is, and \code{rank(xtfrm(x), ....)} will have the desired result if
50  there is a \code{xtfrm} method.  Otherwise, \code{rank} will make use
51  of \code{==}, \code{>}, \code{is.na} and extraction methods for
52  classed objects, possibly rather slowly.
53}
54\value{
55  A numeric vector of the same length as \code{x} with names copied from
56  \code{x} (unless \code{na.last = NA}, when missing values are
57  removed).  The vector is of integer type unless \code{x} is a long
58  vector or \code{ties.method = "average"} when it is of double type
59  (whether or not there are any ties).
60}
61\seealso{
62  \code{\link{order}} and \code{\link{sort}};
63  \code{\link{xtfrm}}, see above.
64}
65\examples{
66(r1 <- rank(x1 <- c(3, 1, 4, 15, 92)))
67x2 <- c(3, 1, 4, 1, 5, 9, 2, 6, 5, 3, 5)
68names(x2) <- letters[1:11]
69(r2 <- rank(x2)) # ties are averaged
70
71## rank() is "idempotent": rank(rank(x)) == rank(x) :
72stopifnot(rank(r1) == r1, rank(r2) == r2)
73
74## ranks without averaging
75rank(x2, ties.method= "first")  # first occurrence wins
76rank(x2, ties.method= "last")   #  last occurrence wins
77rank(x2, ties.method= "random") # ties broken at random
78rank(x2, ties.method= "random") # and again
79
80## keep ties ties, no average
81(rma <- rank(x2, ties.method= "max"))  # as used classically
82(rmi <- rank(x2, ties.method= "min"))  # as in Sports
83stopifnot(rma + rmi == round(r2 + r2))
84
85## Comparing all tie.methods:
86tMeth <- eval(formals(rank)$ties.method)
87rx2 <- sapply(tMeth, function(M) rank(x2, ties.method=M))
88cbind(x2, rx2)
89## ties.method's does not matter w/o ties:
90x <- sample(47)
91rx <- sapply(tMeth, function(MM) rank(x, ties.method=MM))
92stopifnot(all(rx[,1] == rx))
93}
94\keyword{univar}
95