Compare, order, tabulate vectorlike objects
Description
Generic functions and methods for comparing, ordering, and tabulating vectorlike objects.
Usage
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(...)

Arguments
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:

Details
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
.
Value
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.
Note
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. Ifpcompare
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. Specificpcompare
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 ofselfmatch
,duplicated
, andmatch
, respectively, so they work outofthebox on Vector objects for whichselfmatch
,duplicated
, andmatch
work the expected way.Also the default
findMatches
andcountMatches
methods are implemented on top ofmatch
andselfmatch
so they work outofthebox on Vector objects for which those things work the expected way.However, since
selfmatch
itself is also implemented on top ofmatch
, then havingmatch
work the expected way is actually enough to getselfmatch
,duplicated
,unique
,%in%
,findMatches
, andcountMatches
work outofthebox on Vector objects.The
sort
method for Vector objects is implemented on top oforder
, so it works outofthebox on Vector objects for whichorder
works the expected way.The
table
method for Vector objects is implemented on top ofselfmatch
,order
, andas.character
, so it works outofthebox on a Vector object for which those things work the expected way.The S4Vectors package provides no
match
ororder
methods for Vector objects. Specific methods need to be implemented for specific Vector subclasses (e.g. for Hits and Ranges objects).
Author(s)
Hervé Pagès
See Also
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, andBiocGenerics::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.
Examples
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(".+"))))
