Generic functions and methods for comparing, ordering, and tabulating vectorlike objects.
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  ## Elementwise (aka "parallel") comparison of 2 Vector objects
## 
pcompare(x, y)
## S4 method for signature 'Vector,Vector'
e1 == e2
## S4 method for signature 'Vector,ANY'
e1 == e2
## S4 method for signature 'ANY,Vector'
e1 == e2
## S4 method for signature 'Vector,Vector'
e1 <= e2
## S4 method for signature 'Vector,ANY'
e1 <= e2
## S4 method for signature 'ANY,Vector'
e1 <= e2
## S4 method for signature 'Vector,Vector'
e1 != e2
## S4 method for signature 'Vector,ANY'
e1 != e2
## S4 method for signature 'ANY,Vector'
e1 != e2
## S4 method for signature 'Vector,Vector'
e1 >= e2
## S4 method for signature 'Vector,ANY'
e1 >= e2
## S4 method for signature 'ANY,Vector'
e1 >= e2
## S4 method for signature 'Vector,Vector'
e1 < e2
## S4 method for signature 'Vector,ANY'
e1 < e2
## S4 method for signature 'ANY,Vector'
e1 < e2
## S4 method for signature 'Vector,Vector'
e1 > e2
## S4 method for signature 'Vector,ANY'
e1 > e2
## S4 method for signature 'ANY,Vector'
e1 > e2
## selfmatch()
## 
selfmatch(x, ...)
## duplicated() & unique()
## 
## S4 method for signature 'Vector'
duplicated(x, incomparables=FALSE, ...)
## S4 method for signature 'Vector'
unique(x, incomparables=FALSE, ...)
## %in%
## 
## S4 method for signature 'Vector,Vector'
x %in% table
## S4 method for signature 'Vector,ANY'
x %in% table
## S4 method for signature 'ANY,Vector'
x %in% table
## findMatches() & countMatches()
## 
findMatches(x, table, select=c("all", "first", "last"), ...)
countMatches(x, table, ...)
## sort()
## 
## S4 method for signature 'Vector'
sort(x, decreasing=FALSE, na.last = NA, by)
## table()
## 
## S4 method for signature 'Vector'
table(...)

x, y, e1, e2, table 
Vectorlike objects. 
incomparables 
The The See 
select 
Only 
decreasing, na.last 
See 
by 
A formula referencing the metadata columns by which to sort,
e.g., 
... 
A Vector object for Otherwise, extra arguments supported by specific methods. In particular:

Doing pcompare(x, y)
on 2 vectorlike objects x
and y
of length 1 must return an integer less than, equal to, or greater than zero
if the single element in x
is considered to be respectively less than,
equal to, or greater than the single element in y
.
If x
or y
have a length != 1, then they are typically expected
to have the same length so pcompare(x, y)
can operate elementwise,
that is, in that case it returns an integer vector of the same length
as x
and y
where the ith element is the result of compairing
x[i]
and y[i]
. If x
and y
don't have the same
length and are not zerolength vectors, then the shortest is first
recycled to the length of the longest. If one of them is a zerolength
vector then pcompare(x, y)
returns a zerolength integer vector.
selfmatch(x, ...)
is equivalent to match(x, x, ...)
. This
is actually how the default method is implemented. However note that
selfmatch(x, ...)
will typically be more efficient than
match(x, x, ...)
on vectorlike objects for which a specific
selfmatch
method is implemented.
findMatches
is an enhanced version of match
which, by default
(i.e. if select="all"
), returns all the matches in a Hits
object.
countMatches
returns an integer vector of the length of x
containing the number of matches in table
for each element
in x
.
For pcompare
: see Details section above.
For selfmatch
: an integer vector of the same length as x
.
For duplicated
, unique
, and %in%
: see
?BiocGenerics::duplicated
,
?BiocGenerics::unique
,
and ?`%in%`
.
For findMatches
: a Hits object by default (i.e. if
select="all"
).
For countMatches
: an integer vector of the length of x
containing the number of matches in table
for each element
in x
.
For sort
: see ?BiocGenerics::sort
.
For table
: a 1D array of integer values promoted to the
"table"
class. See ?BiocGeneric::table
for more information.
The following notes are for developers who want to implement comparing, ordering, and tabulating methods for their own Vector subclass:
The 6 traditional binary comparison operators are: ==
,
!=
, <=
, >=
, <
, and >
.
The S4Vectors package provides the following methods for
these operators:
setMethod("==", c("Vector", "Vector"), function(e1, e2) { pcompare(e1, e2) == 0L } ) setMethod("<=", c("Vector", "Vector"), function(e1, e2) { pcompare(e1, e2) <= 0L } ) setMethod("!=", c("Vector", "Vector"), function(e1, e2) { !(e1 == e2) } ) setMethod(">=", c("Vector", "Vector"), function(e1, e2) { e2 <= e1 } ) setMethod("<", c("Vector", "Vector"), function(e1, e2) { !(e2 <= e1) } ) setMethod(">", c("Vector", "Vector"), function(e1, e2) { !(e1 <= e2) } )
With these definitions, the 6 binary operators work outofthebox
on Vector objects for which pcompare
works the
expected way. If pcompare
is not implemented, then it's
enough to implement ==
and <=
methods to have the
4 remaining operators (!=
, >=
, <
, and
>
) work outofthebox.
The S4Vectors package provides no pcompare
method for
Vector objects. Specific pcompare
methods need to be
implemented for specific Vector subclasses (e.g. for
Hits and Ranges objects). These specific
methods must obey the rules described in the Details section above.
The duplicated
, unique
, and %in%
methods for
Vector objects are implemented on top of selfmatch
,
duplicated
, and match
, respectively, so they work
outofthebox on Vector objects for which selfmatch
,
duplicated
, and match
work the expected way.
Also the default findMatches
and countMatches
methods
are implemented on top of match
and selfmatch
so they
work outofthebox on Vector objects for which those things
work the expected way.
However, since selfmatch
itself is also implemented on top of
match
, then having match
work the expected way is
actually enough to get selfmatch
, duplicated
,
unique
, %in%
, findMatches
, and
countMatches
work outofthebox on Vector objects.
The sort
method for Vector objects is implemented on
top of order
, so it works outofthebox on Vector
objects for which order
works the expected way.
The table
method for Vector objects is implemented on
top of selfmatch
, order
, and as.character
, so
it works outofthebox on a Vector object for which those
things work the expected way.
The S4Vectors package provides no match
or order
methods for Vector objects. Specific methods need to be
implemented for specific Vector subclasses (e.g. for
Hits and Ranges objects).
Hervé Pagès
The Vector class.
Hitscomparison for comparing and ordering hits.
Vectorsetops for set operations on vectorlike objects.
Vectormerge for merging vectorlike objects.
Rangescomparison in the IRanges package for comparing and ordering ranges.
==
and %in%
in the base package,
and BiocGenerics::match
,
BiocGenerics::duplicated
,
BiocGenerics::unique
,
BiocGenerics::order
,
BiocGenerics::sort
,
BiocGenerics::rank
in the
BiocGenerics package for general information about
the comparison/ordering operators and functions.
The Hits class.
BiocGeneric::table
in the
BiocGenerics package.
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  ## 
## A. SIMPLE EXAMPLES
## 
y < c(16L, 3L, 2L, 15L, 15L, 0L, 8L, 15L, 2L)
selfmatch(y)
x < c(unique(y), 999L)
findMatches(x, y)
countMatches(x, y)
## See ?`Rangescomparison` for more examples (on Ranges objects). You
## might need to load the IRanges package first.
## 
## B. FOR DEVELOPERS: HOW TO IMPLEMENT THE BINARY COMPARISON OPERATORS
## FOR YOUR Vector SUBCLASS
## 
## The answer is: don't implement them. Just implement pcompare() and the
## binary comparison operators will work outofthebox. Here is an
## example:
## (1) Implement a simple Vector subclass.
setClass("Raw", contains="Vector", representation(data="raw"))
setMethod("length", "Raw", function(x) length(x@data))
setMethod("[", "Raw",
function(x, i, j, ..., drop) { x@data < x@data[i]; x }
)
x < new("Raw", data=charToRaw("AB.x0aBAA+C"))
stopifnot(identical(length(x), 12L))
stopifnot(identical(x[7:3], new("Raw", data=charToRaw("a0x."))))
## (2) Implement a "pcompare" method for Raw objects.
setMethod("pcompare", c("Raw", "Raw"),
function(x, y) {as.integer(x@data)  as.integer(y@data)}
)
stopifnot(identical(which(x == x[1]), c(1L, 9L, 10L)))
stopifnot(identical(x[x < x[5]], new("Raw", data=charToRaw(".+"))))

Questions? Problems? Suggestions? Tweet to @rdrrHQ or email at ian@mutexlabs.com.
All documentation is copyright its authors; we didn't write any of that.