setops-methods: Set operations on GRanges and GRangesList objects

Description

Performs set operations on GRanges and GRangesList objects.

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

Usage

## Set operations
"union"(x, y, ignore.strand=FALSE, ...)
"intersect"(x, y, ignore.strand=FALSE, ...)
"setdiff"(x, y, ignore.strand=FALSE, ...)
## Parallel set operations
"punion"(x, y, fill.gap=FALSE, ignore.strand=FALSE, ...)
"pintersect"(x, y, drop.nohit.ranges=FALSE, ignore.strand=FALSE, strict.strand=FALSE)
"psetdiff"(x, y, ignore.strand=FALSE, ...)

Arguments

x, y

For union, intersect, setdiff, pgap: x and y must both be GRanges objects.

For punion: one of x or y must be a GRanges object, the other one can be a GRanges or GRangesList object.

For pintersect: x and y can be any combination of GRanges and/or GRangesList objects.

For psetdiff: x and y can be any combination of GRanges and/or GRangesList objects, with the exception that if x is a GRangesList object then y must be a GRangesList too.

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.

...

Further arguments to be passed to or from other methods.

Value

For union, intersect, setdiff, and pgap: a GRanges object.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.

Details

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.

Examples

Run this code

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

## ---------------------------------------------------------------------
## 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("-", "*", "-"))))

## GRangesList object
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)

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

## Parallel set difference of two GRangesList objects
psetdiff(grlist, shift(grlist, 3))

Run the code above in your browser using DataLab

Data Engineering and BI courses are free this week!