-
Notifications
You must be signed in to change notification settings - Fork 33
/
rowRanks.R
163 lines (152 loc) · 5.51 KB
/
rowRanks.R
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
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
###########################################################################/**
# @RdocFunction rowRanks
# @alias colRanks
#
# @title "Gets the rank of each row (column) of a matrix"
#
# \description{
# @get "title".
# }
#
# \usage{
# @usage rowRanks
# @usage colRanks
# }
#
# \arguments{
# \item{x}{A @numeric or @integer NxK @matrix.}
# \item{rows, cols}{A @vector indicating subset of rows (and/or columns)
# to operate over. If @NULL, no subsetting is done.}
# \item{ties.method}{A @character string specifying how ties are treated.
# For details, see below.}
# \item{dim.}{An @integer @vector of length two specifying the
# dimension of \code{x}, also when not a @matrix.}
# \item{preserveShape}{A @logical specifying whether the @matrix
# returned should preserve the input shape of \code{x}, or not.}
# \item{mc.cores}{The number of cores to use, i.e. at most how many child
# threads will be run simultaneously.}
# \item{...}{Not used.}
# }
#
# \value{
# An @integer @matrix is returned.
# The \code{rowRanks()} function always returns an NxK @matrix,
# where N (K) is the number of rows (columns) whose ranks are calculated.
#
# The \code{colRanks()} function returns an NxK @matrix,
# if \code{preserveShape = TRUE}, otherwise a KxN @matrix.
#
# %% The mode of the returned matrix is @integer, except for
# %% \code{ties.method == "average"} when it is @double.
# }
#
# \details{
# The row ranks of \code{x} are collected as \emph{rows}
# of the result matrix.
#
# The column ranks of \code{x} are collected as \emph{rows}
# if \code{preserveShape = FALSE}, otherwise as \emph{columns}.
#
# The implementation is optimized for both speed and memory.
# To avoid coercing to @doubles (and hence memory allocation), there
# is a unique implementation for @integer matrices.
# It is more memory efficient to do
# \code{colRanks(x, preserveShape=TRUE)} than
# \code{t(colRanks(x, preserveShape=FALSE))}.
#
# Any @names of \code{x} are ignored and absent in the result.
# }
#
# \section{Missing and non- values}{
# These are ranked as \code{NA}, as with \code{na.last="keep"}
# in the @see "base::rank" function.
# }
#
# \section{Ties}{
# When some values are equal ("ties"), argument \code{ties.method}
# specifies what their ranks should be.
# If \code{ties.method} is \code{"max"}, ties
# are ranked as the maximum value.
# If \code{ties.method} is \code{"average"}, ties are ranked
# by their average.
# If \code{ties.method} is \code{"max"} (\code{"min"}), ties
# are ranked as the maximum (minimum) value.
# If \code{ties.method} is \code{"average"}, ties are ranked
# by their average.
# For further details, see @see "base::rank".
# }
#
# \author{
# Hector Corrada Bravo and Harris Jaffee.
# Peter Langfelder for adding 'ties.method' support.
# Henrik Bengtsson adapted the original native implementation
# of \code{rowRanks()} from Robert Gentleman's \code{rowQ()}
# in the \pkg{Biobase} package.
# }
#
# \seealso{
# @see "base::rank".
# 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()}.
# }
#
# @keyword array
# @keyword iteration
# @keyword robust
# @keyword univar
#*/###########################################################################
rowRanks <- function(x, rows=NULL, cols=NULL, ties.method=c("max", "average", "min"), dim.=dim(x), mc.cores=1L, ...) {
# Argument 'ties.method':
ties.method <- ties.method[1L]
if (is.element("flavor", names(list(...)))) {
.Deprecated(old="Argument 'flavor' of rowRanks()", package="matrixStats")
}
tiesMethod <- charmatch(ties.method, c("max", "average", "min"), nomatch=0L)
if (tiesMethod == 0L) {
stop("Unknown value of argument 'ties.method': ", ties.method)
}
dim. <- as.integer(dim.)
# byrow=TRUE
.Call("rowRanksWithTies", x, dim., rows, cols, tiesMethod, TRUE, mc.cores, PACKAGE="matrixStats")
}
colRanks <- function(x, rows=NULL, cols=NULL, ties.method=c("max", "average", "min"), dim.=dim(x), preserveShape=FALSE, mc.cores=1L, ...) {
# Argument 'ties.method':
ties.method <- ties.method[1L]
if (is.element("flavor", names(list(...)))) {
.Deprecated(old="Argument 'flavor' of rowRanks()", package="matrixStats")
}
# Argument 'preserveShape'
preserveShape <- as.logical(preserveShape)
tiesMethod <- charmatch(ties.method, c("max", "average", "min"), nomatch=0L)
if (tiesMethod == 0L) {
stop("Unknown value of argument 'ties.method': ", ties.method)
}
dim. <- as.integer(dim.)
# byrow=FALSE
y <- .Call("rowRanksWithTies", x, dim., rows, cols, tiesMethod, FALSE, mc.cores, PACKAGE="matrixStats")
if (!preserveShape) y <- t(y)
y
}
############################################################################
# HISTORY:
# 2015-07-24 [DJ]
# o Provided multicore processing APIs.
# 2015-05-30 [DJ]
# o Supported subsetted computation.
# 2014-12-17 [HB]
# o CLEANUP: Made col- and rowRanks() plain R functions.
# 2014-11-15 [HB]
# o SPEEDUP: No longer using match.arg() due to its overhead.
# 2013-04-23 [HB]
# o Added argument 'preserveShape' to colRanks(), cf. private email
# 'row- and colRanks in package matrixStats' on 2012-10-05 until
# 2013-02-28.
# 2013-01-14 [HB]
# o Added internal support for rowRanks() with ties "max", "min" and
# "average".
# 2011-11-11 [HB]
# o Added '...' to generic functions rowRanks() and colRanks().
# 2011-10-17 [HJ]
# o Added rowRanks and colRanks().
############################################################################