1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
|
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/rowRanks.R
\name{rowRanks}
\alias{rowRanks}
\alias{colRanks}
\title{Gets the rank of the elements in each row (column) of a matrix}
\usage{
rowRanks(x, rows = NULL, cols = NULL, ties.method = c("max", "average",
"first", "last", "random", "max", "min", "dense"), dim. = dim(x), ...,
useNames = TRUE)
colRanks(x, rows = NULL, cols = NULL, ties.method = c("max", "average",
"first", "last", "random", "max", "min", "dense"), dim. = dim(x),
preserveShape = FALSE, ..., useNames = TRUE)
}
\arguments{
\item{x}{An NxK \code{\link[base]{matrix}} or, if \code{dim.} is specified,
an N * K \code{\link[base]{vector}}.}
\item{rows}{A \code{\link[base]{vector}} indicating subset of rows to
operate over. If \code{\link[base]{NULL}}, no subsetting is done.}
\item{cols}{A \code{\link[base]{vector}} indicating subset of columns to
operate over. If \code{\link[base]{NULL}}, no subsetting is done.}
\item{ties.method}{A \code{\link[base]{character}} string specifying how
ties are treated. For details, see below.}
\item{dim.}{An \code{\link[base]{integer}} \code{\link[base]{vector}} of
length two specifying the dimension of \code{x}, also when not a
\code{\link[base]{matrix}}. \emph{Comment:} The reason for this argument
being named with a period at the end is purely technical (we get a run-time
error if we try to name it \code{dim}).}
\item{...}{Not used.}
\item{useNames}{If \code{\link[base:logical]{TRUE}} (default), names
attributes of the result are set, otherwise not.}
\item{preserveShape}{A \code{\link[base]{logical}} specifying whether the
\code{\link[base]{matrix}} returned should preserve the input shape of
\code{x}, or not.}
}
\value{
A \code{\link[base]{matrix}} of type \code{\link[base]{integer}} is
returned, unless \code{ties.method = "average"} when it is of type
\code{\link[base]{numeric}}.
The \code{rowRanks()} function always returns an NxK
\code{\link[base]{matrix}}, where N (K) is the number of rows (columns)
whose ranks are calculated.
The \code{colRanks()} function returns an NxK \code{\link[base]{matrix}}, if
\code{preserveShape = TRUE}, otherwise a KxN \code{\link[base]{matrix}}.
Any \code{\link[base]{names}} of \code{x} are ignored and absent in the
result.
}
\description{
Gets the rank of the elements in each row (column) of a matrix.
}
\details{
These functions rank values and treats missing values the same way as
\code{\link[base]{rank}}().
For equal values ("ties"), argument \code{ties.method} determines how these
are ranked among each other. More precisely, for the following values of
\code{ties.method}, each index set of ties consists of:
\itemize{
\item{\code{"first"} - increasing values that are all unique}
\item{\code{"last"} - decreasing values that are all unique}
\item{\code{"min"} - identical values equaling the minimum of
their original ranks}
\item{\code{"max"} - identical values equaling the maximum of
their original ranks}
\item{\code{"average"} - identical values that equal the sample mean of
their original ranks. Because the average is calculated, the returned
ranks may be non-integer values}
\item{\code{"random"} - randomly shuffled values of their original ranks.}
\item{\code{"dense"} - increasing values that are all unique and,
contrary to \code{"first"}, never contain any gaps}
}
For more information on \code{ties.method = "dense"}, see \code{frank()} of
the \pkg{data.table} package.
For more information on the other alternatives, see \code{\link[base]{rank}}().
Note that, due to different randomization strategies, the shuffling order
produced by these functions when using \code{ties.method = "random"} does
not reproduce that of \code{\link[base]{rank}}().
\emph{WARNING: For backward-compatibility reasons, the default is
\code{ties.method = "max"}, which differs from \code{\link[base]{rank}}()
which uses \code{ties.method = "average"} by default.
Since we plan to change the default behavior in a future version, we recommend
to explicitly specify the intended value of argument \code{ties.method}.}
}
\section{Missing values}{
Missing values are ranked as \code{NA_integer_}, as with \code{na.last = "keep"}
in the \code{\link[base]{rank}}() function.
}
\section{Performance}{
The implementation is optimized for both speed and memory. To avoid
coercing to \code{\link[base]{double}}s (and hence memory allocation),
there is a unique implementation for \code{\link[base]{integer}} matrices.
Furthermore, it is more memory efficient to do
\code{colRanks(x, preserveShape = TRUE)} than
\code{t(colRanks(x, preserveShape = FALSE))}.
}
\seealso{
For developers, see also Section Utility functions' in
'Writing R Extensions manual', particularly the
native functions \code{R_qsort_I()} and \code{R_qsort_int_I()}.
}
\author{
Hector Corrada Bravo and Harris Jaffee. Peter Langfelder for adding
'ties.method' support. Brian Montgomery for adding more 'ties.method's.
Henrik Bengtsson adapted the original native
implementation of \code{rowRanks()} from Robert Gentleman's \code{rowQ()} in
the \pkg{Biobase} package.
}
\keyword{array}
\keyword{iteration}
\keyword{robust}
\keyword{univar}
|
