Inter range transformations of a GRanges or GRangesList object
This man page documents inter range transformations of a GenomicRanges object (i.e. of an object that belongs to the GenomicRanges class or one of its subclasses, this includes for example GRanges objects), or a GRangesList object.
See ?`intra-range-methods` and
?`inter-range-methods` in the IRanges
package for a quick introduction to intra range and inter
range transformations.
See ?`intra-range-methods` for
intra range transformations of a GenomicRanges object or
GRangesList object.
## S4 method for signature 'GenomicRanges'
range(x, ..., with.revmap=FALSE, ignore.strand=FALSE, na.rm=FALSE)
## S4 method for signature 'GRangesList'
range(x, ..., with.revmap=FALSE, ignore.strand=FALSE, na.rm=FALSE)
## S4 method for signature 'GenomicRanges'
reduce(x, drop.empty.ranges=FALSE, min.gapwidth=1L, with.revmap=FALSE,
with.inframe.attrib=FALSE, ignore.strand=FALSE)
## S4 method for signature 'GRangesList'
reduce(x, drop.empty.ranges=FALSE, min.gapwidth=1L, with.revmap=FALSE,
with.inframe.attrib=FALSE, ignore.strand=FALSE)
## S4 method for signature 'GenomicRanges'
gaps(x, start=1L, end=seqlengths(x))
## S4 method for signature 'GenomicRanges'
disjoin(x, with.revmap=FALSE, ignore.strand=FALSE)
## S4 method for signature 'GRangesList'
disjoin(x, with.revmap=FALSE, ignore.strand=FALSE)
## S4 method for signature 'GenomicRanges'
isDisjoint(x, ignore.strand=FALSE)
## S4 method for signature 'GRangesList'
isDisjoint(x, ignore.strand=FALSE)
## S4 method for signature 'GenomicRanges'
disjointBins(x, ignore.strand=FALSE)x |
A GenomicRanges or GenomicRangesList object. |
drop.empty.ranges, min.gapwidth, with.revmap, with.inframe.attrib, start, end |
See |
ignore.strand |
|
... |
For |
na.rm |
Ignored. |
range returns an object of the same type as x
containing range bounds for each distinct (seqname, strand) pairing.
The names (names(x)) and the metadata columns in x are
dropped.
reduce returns an object of the same type as x
containing reduced ranges for each distinct (seqname, strand) pairing.
The names (names(x)) and the metadata columns in x are
dropped.
See ?reduce for more information about range
reduction and for a description of the optional arguments.
gaps returns an object of the same type as x
containing complemented ranges for each distinct (seqname, strand) pairing.
The names (names(x)) and the columns in x are dropped.
For the start and end arguments of this gaps method, it is expected that
the user will supply a named integer vector (where the names correspond to
the appropriate seqlevels). See ?gaps for more
information about range complements and for a description of the optional
arguments.
disjoin returns an object of the same type as x
containing disjoint ranges for each distinct (seqname, strand) pairing.
The names (names(x)) and the metadata columns in x are
dropped. If with.revmap=TRUE, a metadata column that maps the
ouput ranges to the input ranges is added to the returned object.
See ?disjoin for more information.
isDisjoint returns a logical value indicating whether the ranges
in x are disjoint (i.e. non-overlapping).
disjointBins returns bin indexes for the ranges in x, such
that ranges in the same bin do not overlap. If ignore.strand=FALSE,
the two features cannot overlap if they are on different strands.
When they are supported on GRangesList object x, the above inter
range transformations will apply the transformation to each of the list
elements in x and return a list-like object parallel to
x (i.e. with 1 list element per list element in x).
If x has names on it, they're propagated to the returned object.
H. Pagès and P. Aboyoun
The GenomicRanges and GRanges classes.
The IntegerRanges class in the IRanges package.
The inter-range-methods man page in the IRanges package.
GenomicRanges-comparison for comparing and ordering genomic ranges.
endoapply in the S4Vectors package.
gr <- GRanges(
seqnames=Rle(paste("chr", c(1, 2, 1, 3), sep=""), c(1, 3, 2, 4)),
ranges=IRanges(1:10, width=10:1, names=letters[1:10]),
strand=Rle(strand(c("-", "+", "*", "+", "-")), c(1, 2, 2, 3, 2)),
score=1:10,
GC=seq(1, 0, length=10)
)
gr
gr1 <- GRanges(seqnames="chr2", ranges=IRanges(3, 6),
strand="+", score=5L, GC=0.45)
gr2 <- GRanges(seqnames="chr1",
ranges=IRanges(c(10, 7, 19), width=5),
strand=c("+", "-", "+"), score=3:5, GC=c(0.3, 0.5, 0.66))
gr3 <- GRanges(seqnames=c("chr1", "chr2"),
ranges=IRanges(c(1, 4), c(3, 9)),
strand=c("-", "-"), score=c(6L, 2L), GC=c(0.4, 0.1))
grl <- GRangesList(gr1=gr1, gr2=gr2, gr3=gr3)
grl
## ---------------------------------------------------------------------
## range()
## ---------------------------------------------------------------------
## On a GRanges object:
range(gr)
range(gr, with.revmap=TRUE)
## On a GRangesList object:
range(grl)
range(grl, ignore.strand=TRUE)
range(grl, with.revmap=TRUE, ignore.strand=TRUE)
# ---------------------------------------------------------------------
## reduce()
## ---------------------------------------------------------------------
reduce(gr)
gr2 <- reduce(gr, with.revmap=TRUE)
revmap <- mcols(gr2)$revmap # an IntegerList
## Use the mapping from reduced to original ranges to group the original
## ranges by reduced range:
relist(gr[unlist(revmap)], revmap)
## Or use it to split the DataFrame of original metadata columns by
## reduced range:
relist(mcols(gr)[unlist(revmap), ], revmap) # a SplitDataFrameList
## [For advanced users] Use this reverse mapping to compare the reduced
## ranges with the ranges they originate from:
expanded_gr2 <- rep(gr2, elementNROWS(revmap))
reordered_gr <- gr[unlist(revmap)]
codes <- pcompare(expanded_gr2, reordered_gr)
## All the codes should translate to "d", "e", "g", or "h" (the 4 letters
## indicating that the range on the left contains the range on the right):
alphacodes <- rangeComparisonCodeToLetter(pcompare(expanded_gr2, reordered_gr))
stopifnot(all(alphacodes %in% c("d", "e", "g", "h")))
## On a big GRanges object with a lot of seqlevels:
mcols(gr) <- NULL
biggr <- c(gr, GRanges("chr1", IRanges(c(4, 1), c(5, 2)), strand="+"))
seqlevels(biggr) <- paste0("chr", 1:2000)
biggr <- rep(biggr, 25000)
set.seed(33)
seqnames(biggr) <- sample(factor(seqlevels(biggr), levels=seqlevels(biggr)),
length(biggr), replace=TRUE)
biggr2 <- reduce(biggr, with.revmap=TRUE)
revmap <- mcols(biggr2)$revmap
expanded_biggr2 <- rep(biggr2, elementNROWS(revmap))
reordered_biggr <- biggr[unlist(revmap)]
codes <- pcompare(expanded_biggr2, reordered_biggr)
alphacodes <- rangeComparisonCodeToLetter(pcompare(expanded_biggr2,
reordered_biggr))
stopifnot(all(alphacodes %in% c("d", "e", "g", "h")))
table(alphacodes)
## On a GRangesList object:
reduce(grl) # Doesn't really reduce anything but note the reordering
# of the inner elements in the 2nd and 3rd list elements:
# the ranges are reordered by sequence name first (which
# should appear in the same order as in 'seqlevels(grl)'),
# and then by strand.
reduce(grl, ignore.strand=TRUE) # 2nd list element got reduced
## ---------------------------------------------------------------------
## gaps()
## ---------------------------------------------------------------------
gaps(gr, start=1, end=10)
## ---------------------------------------------------------------------
## disjoin(), isDisjoint(), disjointBins()
## ---------------------------------------------------------------------
disjoin(gr)
disjoin(gr, with.revmap=TRUE)
disjoin(gr, with.revmap=TRUE, ignore.strand=TRUE)
isDisjoint(gr)
stopifnot(isDisjoint(disjoin(gr)))
disjointBins(gr)
stopifnot(all(sapply(split(gr, disjointBins(gr)), isDisjoint)))
## On a GRangesList object:
disjoin(grl) # doesn't really disjoin anything but note the reordering
disjoin(grl, with.revmap=TRUE)Please choose more modern alternatives, such as Google Chrome or Mozilla Firefox.