R: Merge vector-like objects

Vector-merge {S4Vectors}

R Documentation

Merge vector-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:

The matching is based on the vector values, not arbitrary columns in a table.
Self merging is a no-op if sort=FALSE (or object already sorted) and if the object has no duplicates.
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.

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)

[Package S4Vectors version 0.16.0 Index]