setops-methods: Set operations on GRanges and GRangesList objects

Description

Performs set operations on GRanges and GRangesList objects.

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, resolve.empty=c("none", "max.start", "start.x"), ignore.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: one of x or y must be a GRanges object, the other one can be a GRanges or GRangesList object.

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

resolve.empty

One of "none", "max.start", or "start.x" denoting how to handle ambiguous empty ranges formed by intersections. "none" - throw an error if an ambiguous empty range is formed, "max.start" - associate the maximum start value with any ambiguous empty range, and "start.x" - associate the start value of x with any ambiguous empty range. (See pintersect for the definition of an ambiguous range.)

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.

...

Further arguments to be passed to or from other methods.

Value

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

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

## 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))
## Not run: 
# pintersect(x, shift(x, 7))  # will fail
# ## End(Not run)
pintersect(x, shift(x, 7), resolve.empty="max.start")

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)

## 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 DataCamp Workspace