Vector-merge: Merge vector-like objects

In AdamLeckenby/S4Vectors_Fix: S4 implementation of vector-like and list-like objects

Description

A merge method for vector-like objects.

Usage

## S4 method for signature 'Vector,Vector'
merge(x, y, ..., all=FALSE, all.x=NA, all.y=NA, sort=TRUE)

Arguments

x, y, ...	Vector-like objects, typically all of the same class and typically not list-like objects (even though some list-like objects like Ranges and DNAStringSet are supported). Duplicated elements in each object are removed with a warning.
all	TRUE or FALSE. Whether the vector elements in the result should be the union (when all=TRUE) or intersection (when all=FALSE) of the vector elements in x, y, ....
all.x, all.y	To be used only when merging 2 objects (binary merge). Both all.x and all.y must be single logicals. If any of them is NA, then it's set to the value of all. Setting both of them to TRUE or both of them to FALSE is equivalent to setting all to TRUE or to FALSE, respectively (see above). If all.x is TRUE and all.y is FALSE then the vector elements in the result will be the unique elements in x. If all.x is FALSE and all.y is TRUE then the vector elements in the result will be the unique elements in y.
sort	Whether to sort the merged result.

Details

This merge method acts much like merge.data.frame, except for 3 important differences:

1. The matching is based on the vector values, not arbitrary columns in a table.

2. Self merging is a no-op if sort=FALSE (or object already sorted) and if the object has no duplicates.

3. This merge method accepts an arbitrary number of vector-like objects (n-ary merge).

If some of the objects to merge are list-like objects not supported by the method described here, then the merging is simply done by calling base::merge() on the objects. This might succeed or not...

Value

A vector-like object of the same class as the input objects (if they all have the same class) containing the merged vector values and metadata columns.

See Also

• The Vector class.

• Vector-comparison for comparing and ordering vector-like objects.

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

Examples

library(GenomicRanges)
x <- GRanges(c("chr1:1-1000", "chr2:2000-3000"),
             score=c(0.45, 0.1), a1=c(5L, 7L), a2=c(6, 8))
y <- GRanges(c("chr2:150-151", "chr1:1-10", "chr2:2000-3000"),
             score=c(0.7, 0.82, 0.1), b1=c(0L, 5L, 1L), b2=c(1, -2, 1))
merge(x, y)
merge(x, y, all=TRUE)
merge(x, y, all.x=TRUE)
merge(x, y, all.y=TRUE)

## Shared metadata columns must agree:
mcols(x)$score[2] <- 0.11
#merge(x, y)  # error!

## NAs agree with anything:
mcols(x)$score[2] <- NA
merge(x, y)

AdamLeckenby/S4Vectors_Fix documentation built on May 23, 2019, 2:42 p.m.