inter-range-methods: Inter range transformations of a GRanges or GRangesList...
In Bioconductor/GenomicRanges: Representation and manipulation of genomic intervals
inter-range-methods R Documentation
Inter range transformations of a GRanges or GRangesList object
Description
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.
Usage
## 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), ignore.strand=FALSE)
## 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)
Arguments
x
A GenomicRanges or GenomicRangesList object.
drop.empty.ranges, min.gapwidth, with.revmap, with.inframe.attrib, start, end
See ?`inter-range-methods` in the IRanges
package.
ignore.strand
TRUE or FALSE. Whether the strand of the input ranges
should be ignored or not. See details below.
...
For range, additional GenomicRanges objects to consider.
Ignored otherwise.
na.rm
Ignored.
Details
On a GRanges object
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 metadata 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.
On a GRangesList/GenomicRangesList object
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.
Author(s)
H. Pagès and P. Aboyoun
See Also
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.
Examples
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=3, end=12)
gaps(gr, start=3, end=12, ignore.strand=TRUE)
## Note that if the lengths of the underlying sequences are known, then
## by default 'gaps(gr)' returns the regions of the sequences that are
## not covered by 'gr':
seqlengths(gr) # lengths of underlying sequences are not known
seqlengths(gr) <- c(chr1=50, chr2=30, chr3=18)
gaps(gr)
gaps(gr, ignore.strand=TRUE)
## ---------------------------------------------------------------------
## 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)
Bioconductor/GenomicRanges documentation built on Nov. 17, 2024, 11:43 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| inter-range-methods | R Documentation |
Inter range transformations of a GRanges or GRangesList object
Description
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.
Usage
## 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), ignore.strand=FALSE)
## 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)
Arguments
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. |
Details
On a GRanges object
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 metadata 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.
On a GRangesList/GenomicRangesList object
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.
Author(s)
H. Pagès and P. Aboyoun
See Also
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.
-
endoapplyin the S4Vectors package.
Examples
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=3, end=12)
gaps(gr, start=3, end=12, ignore.strand=TRUE)
## Note that if the lengths of the underlying sequences are known, then
## by default 'gaps(gr)' returns the regions of the sequences that are
## not covered by 'gr':
seqlengths(gr) # lengths of underlying sequences are not known
seqlengths(gr) <- c(chr1=50, chr2=30, chr3=18)
gaps(gr)
gaps(gr, ignore.strand=TRUE)
## ---------------------------------------------------------------------
## 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)
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.