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