S4Vectors (version 0.10.2)

Vector-comparison: Compare, order, tabulate vector-like objects

Description

Generic functions and methods for comparing, ordering, and tabulating vector-like objects.

Usage

```## Element-wise (aka "parallel") comparison of 2 Vector objects
## ------------------------------------------------------------
pcompare(x, y)
"=="(e1, e2)
"=="(e1, e2)
"=="(e1, e2)
"<="(e1, e2)="" "<="(e1, e2)
" <="(e1, e2)
" !="(e1, e2)
">="(e1, e2)
">="(e1, e2)
">="(e1, e2)
"<"(e1, e2)="" "<"(e1,="" e2)<="" div="">
">"(e1, e2)
">"(e1, e2)
">"(e1, e2)
## selfmatch()
## -----------
selfmatch(x, ...)
## duplicated() & unique()
## -----------------------
"duplicated"(x, incomparables=FALSE, ...)
"unique"(x, incomparables=FALSE, ...)
## %in%
## ----
"%in%"(x, table)
"%in%"(x, table)
"%in%"(x, table)
## findMatches() & countMatches()
## ------------------------------
findMatches(x, table, select=c("all", "first", "last"), ...)
countMatches(x, table, ...)
## sort()
## ------
"sort"(x, decreasing=FALSE, na.last = NA, by)
## table()
## -------
"table"(...)```

Arguments

x, y, e1, e2, table
Vector-like objects.
incomparables
The `duplicated` method for Vector objects does NOT support this argument.

The `unique` method for Vector objects, which is implemented on top of `duplicated`, propagates this argument to its call to `duplicated`.

See `?base::duplicated` and `?base::unique` for more information about this argument.

select
Only `select="all"` is supported at the moment. Note that you can use `match` if you want to do `select="first"`. Otherwise you're welcome to request this on the Bioconductor mailing list.
decreasing, na.last
See `?base::sort`.
by
A formula referencing the metadata columns by which to sort, e.g., `~ x + y` sorts by column “x”, breaking ties with column “y”.
...
A Vector object for `table` (the `table` method for Vector objects can only take one input object).

Otherwise, extra arguments supported by specific methods. In particular:

• The default `selfmatch` method, which is implemented on top of `match`, propagates the extra arguments to its call to `match`.

• The `duplicated` method for Vector objects, which is implemented on top of `selfmatch`, accepts extra argument `fromLast` and propagates the other extra arguments to its call to `selfmatch`. See `?base::duplicated` for more information about this argument.
• The `unique` method for Vector objects, which is implemented on top of `duplicated`, propagates the extra arguments to its call to `duplicated`.
• The default `findMatches` and `countMatches` methods, which are implemented on top of `match` and `selfmatch`, propagate the extra arguments to their calls to `match` and `selfmatch`.
• The `sort` method for Vector objects, which is implemented on top of `order`, only accepts extra argument `na.last` and propagates it to its call to `order`.
• 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.

Details

Doing `pcompare(x, y)` on 2 vector-like 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 element-wise, that is, in that case it returns an integer vector of the same length as `x` and `y` where the i-th element is the result of compairing `x[i]` and `y[i]`. If `x` and `y` don't have the same length and are not zero-length vectors, then the shortest is first recycled to the length of the longest. If one of them is a zero-length vector then `pcompare(x, y)` returns a zero-length 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 vector-like 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`.

• The Vector class.

• Hits-comparison for comparing and ordering hits.

• Vector-setops for set operations on vector-like objects.

• Ranges-comparison 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.

Examples

Run this code
``````## ---------------------------------------------------------------------
## 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 ?`Ranges-comparison` 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
## ---------------------------------------------------------------------

## The answer is: don't implement them. Just implement pcompare() and the
## binary comparison operators will work out-of-the-box. 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.x0a-BAA+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(".-+"))))
``````

Run the code above in your browser using DataLab