setops-methods: Set operations on genomic ranges
In GenomicRanges: Representation and manipulation of genomic intervals

Description Usage Arguments Details Value Author(s) See Also Examples

Performs set operations on GRanges and GRangesList objects.

NOTE: The punion, pintersect, psetdiff, and pgap generic functions and methods for IntegerRanges objects are defined and documented in the IRanges package.

## Vector-wise set operations
## --------------------------

## S4 method for signature 'GenomicRanges,GenomicRanges'
union(x, y, ignore.strand=FALSE)

## S4 method for signature 'GenomicRanges,GenomicRanges'
intersect(x, y, ignore.strand=FALSE)

## S4 method for signature 'GenomicRanges,GenomicRanges'
setdiff(x, y, ignore.strand=FALSE)

## Element-wise (aka "parallel") set operations
## --------------------------------------------

## S4 method for signature 'GRanges,GRanges'
punion(x, y, fill.gap=FALSE, ignore.strand=FALSE)

## S4 method for signature 'GRanges,GRanges'
pintersect(x, y, drop.nohit.ranges=FALSE,
           ignore.strand=FALSE, strict.strand=FALSE)

## S4 method for signature 'GRanges,GRanges'
psetdiff(x, y, ignore.strand=FALSE)

`x, y`	For `union`, `intersect`, and `setdiff`: 2 GenomicRanges objects or 2 GRangesList objects. For `punion` and `pintersect`: 2 GRanges objects, or 1 GRanges object and 1 GRangesList object. For `psetdiff`: `x` must be a GRanges object and `y` can be a GRanges or GRangesList object. For `pgap`: 2 GRanges objects. In addition, for the parallel operations, `x` and `y` must be of equal length (i.e. `length(x) == length(y)`).
`fill.gap`	Logical indicating whether or not to force a union by using the rule `start = min(start(x), start(y)), end = max(end(x), end(y))`.
`ignore.strand`	For set operations: If set to TRUE, then the strand of `x` and `y` is set to `"*"` prior to any computation. For parallel set operations: If set to TRUE, the strand information is ignored in the computation and the result has the strand information of `x`.
`drop.nohit.ranges`	If TRUE then elements in `x` that don't intersect with their corresponding element in `y` are removed from the result (so the returned object is no more parallel to the input). If FALSE (the default) then nothing is removed and a `hit` metadata column is added to the returned object to indicate elements in `x` that intersect with the corresponding element in `y`. For those that don't, the reported intersection is a zero-width range that has the same start as `x`.
`strict.strand`	If set to FALSE (the default), features on the `"*"` strand are treated as occurring on both the `"+"` and `"-"` strand. If set to TRUE, the strand of intersecting elements must be strictly the same.

The pintersect methods involving GRanges and/or GRangesList objects use the triplet (sequence name, range, strand) to determine the element by element intersection of features, where a strand value of "*" is treated as occurring on both the "+" and "-" strand (unless strict.strand is set to TRUE, in which case the strand of intersecting elements must be strictly the same).

The psetdiff methods involving GRanges and/or GRangesList objects use the triplet (sequence name, range, strand) to determine the element by element set difference of features, where a strand value of "*" is treated as occurring on both the "+" and "-" strand.

For union, intersect, and setdiff: a GRanges object if x and y are GenomicRanges objects, and a GRangesList object if they are GRangesList objects.

For punion and pintersect: when x or y is not a GRanges object, an object of the same class as this non-GRanges object. Otherwise, a GRanges object.

For psetdiff: either a GRanges object when both x and y are GRanges objects, or a GRangesList object when y is a GRangesList object.

For pgap: a GRanges object.

P. Aboyoun and H. Pag<c3><a8>s

setops-methods in the IRanges package for set operations on IntegerRanges and IntegerRangesList objects.
findOverlaps-methods for finding/counting overlapping genomic ranges.
intra-range-methods and inter-range-methods for intra range and inter range transformations of a GRanges object.
GRanges and GRangesList objects.
mendoapply in the S4Vectors package.

## ---------------------------------------------------------------------
## A. SET OPERATIONS
## ---------------------------------------------------------------------

x <- GRanges("chr1", IRanges(c(2, 9) , c(7, 19)), strand=c("+", "-"))
y <- GRanges("chr1", IRanges(5, 10), strand="-") 

union(x, y)
union(x, y, ignore.strand=TRUE)

intersect(x, y)
intersect(x, y, ignore.strand=TRUE)

setdiff(x, y)
setdiff(x, y, ignore.strand=TRUE)

## With 2 GRangesList objects:
gr1 <- GRanges(seqnames="chr2",
               ranges=IRanges(3, 6))
gr2 <- GRanges(seqnames=c("chr1", "chr1"),
               ranges=IRanges(c(7,13), width = 3),
               strand=c("+", "-"))
gr3 <- GRanges(seqnames=c("chr1", "chr2"),
               ranges=IRanges(c(1, 4), c(3, 9)),
               strand=c("-", "-"))
grlist <- GRangesList(gr1=gr1, gr2=gr2, gr3=gr3)

union(grlist, shift(grlist, 3))
intersect(grlist, shift(grlist, 3))
setdiff(grlist, shift(grlist, 3))

## Sanity checks:
grlist2 <- shift(grlist, 3)
stopifnot(identical(
    union(grlist, grlist2),
    mendoapply(union, grlist, grlist2)
))
stopifnot(identical(
    intersect(grlist, grlist2),
    mendoapply(intersect, grlist, grlist2)
))
stopifnot(identical(
    setdiff(grlist, grlist2),
    mendoapply(setdiff, grlist, grlist2)
))

## ---------------------------------------------------------------------
## B. PARALLEL SET OPERATIONS
## ---------------------------------------------------------------------

punion(x, shift(x, 6))
## Not run: 
punion(x, shift(x, 7))  # will fail

## End(Not run)
punion(x, shift(x, 7), fill.gap=TRUE)

pintersect(x, shift(x, 6))
pintersect(x, shift(x, 7))

psetdiff(x, shift(x, 7))

## ---------------------------------------------------------------------
## C. MORE EXAMPLES
## ---------------------------------------------------------------------

## GRanges object:
gr <- GRanges(seqnames=c("chr2", "chr1", "chr1"),
              ranges=IRanges(1:3, width = 12),
              strand=Rle(strand(c("-", "*", "-"))))

## Parallel intersection of a GRanges and a GRangesList object
pintersect(gr, grlist)
pintersect(grlist, gr)

## For a fast 'mendoapply(intersect, grlist, as(gr, "GRangesList"))'
## call pintersect() with 'strict.strand=TRUE' and call reduce() on
## the result with 'drop.empty.ranges=TRUE':
reduce(pintersect(grlist, gr, strict.strand=TRUE),
       drop.empty.ranges=TRUE)

## Parallel set difference of a GRanges and a GRangesList object
psetdiff(gr, grlist)