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 IntegerRanges 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)

[Package S4Vectors version 0.20.1 Index]