Intra range transformations of an IRanges, IPos, Views, RangesList, or MaskCollection object
Range-based transformations are grouped in 2 categories:
Intra range transformations (e.g. shift())
transform each range individually (and independently of the other
ranges). They return an object parallel to the input object,
that is, where the i-th range corresponds to the i-th range in the
input.
Those transformations are described below.
Inter range transformations (e.g. reduce())
transform all the ranges together as a set to produce a new set
of ranges. They return an object that is generally NOT
parallel to the input object.
Those transformations are described in the inter-range-methods
man page (see ?`inter-range-methods`).
Except for threebands(), all the transformations described in this
man page are endomorphisms that operate on a single "range-based"
object, that is, they transform the ranges contained in the input object
and return them in an object of the same class as the input object.
shift(x, shift=0L, use.names=TRUE) narrow(x, start=NA, end=NA, width=NA, use.names=TRUE) resize(x, width, fix="start", use.names=TRUE, ...) flank(x, width, start=TRUE, both=FALSE, use.names=TRUE, ...) promoters(x, upstream=2000, downstream=200, use.names=TRUE, ...) reflect(x, bounds, use.names=TRUE) restrict(x, start=NA, end=NA, keep.all.ranges=FALSE, use.names=TRUE) threebands(x, start=NA, end=NA, width=NA)
x |
An IRanges, IPos, Views, RangesList, or MaskCollection object. |
shift |
An integer vector containing the shift information. Recycled as
necessary so that each element corresponds to a range in Can also be a list-like object parallel to |
use.names |
|
start, end |
If Can also be list-like objects parallel to |
width |
If Can also be a list-like object parallel to |
fix |
If Can also be a list-like object parallel to |
... |
Additional arguments for methods. |
both |
If |
upstream, downstream |
Vectors of non-NA non-negative integers. Recycled as
necessary so that each element corresponds to a range in
Default values for |
bounds |
An IRanges object to serve as the reference bounds for the reflection, see below. |
keep.all.ranges |
|
Unless specified otherwise, when x is a RangesList
object, any transformation described here is equivalent to applying the
transformation to each list element in x.
shift shifts all the ranges in x by the amount specified
by the shift argument.
narrow narrows the ranges in x i.e. each range in the
returned IntegerRanges object is a subrange of the corresponding
range in x.
The supplied start/end/width values are solved by a call to
solveUserSEW(width(x), start=start, end=end, width=width)
and therefore must be compliant with the rules of the SEW
(Start/End/Width) interface (see ?solveUserSEW
for the details).
Then each subrange is derived from the original range according
to the solved start/end/width values for this range. Note that those
solved values are interpreted relatively to the original range.
resize resizes the ranges to the specified width where either
the start, end, or center is used as an anchor.
flank generates flanking ranges for each range in x. If
start is TRUE for a given range, the flanking occurs at
the start, otherwise the end. The widths of the flanks are given by
the width parameter. The widths can be negative, in which case
the flanking region is reversed so that it represents a prefix or
suffix of the range in x. The flank operation is
illustrated below for a call of the form flank(x, 3, TRUE),
where x indicates a range in x and - indicates
the resulting flanking region:
---xxxxxxx
If start were FALSE:
xxxxxxx---
For negative width, i.e. flank(x, -3, FALSE), where *
indicates the overlap between x and the result:
xxxx***
If both is TRUE, then, for all ranges in x, the
flanking regions are extended into (or out of, if width is
negative) the range, so that the result straddles the given endpoint
and has twice the width given by width. This is illustrated below
for flank(x, 3, both=TRUE):
---***xxxx
promoters generates promoter ranges for each range in x
relative to the transcription start site (TSS), where TSS is
start(x). The promoter range is expanded around the TSS
according to the upstream and downstream arguments.
upstream represents the number of nucleotides in the 5'
direction and downstream the number in the 3' direction.
The full range is defined as,
(start(x) - upstream) to (start(x) + downstream - 1).
For documentation for using promoters on a
GRanges object see
?`promoters,GenomicRanges-method` in
the GenomicRanges package.
reflect "reflects" or reverses each range in x relative to
the corresponding range in bounds, which is recycled as
necessary. Reflection preserves the width of a range, but shifts it
such the distance from the left bound to the start of the range
becomes the distance from the end of the range to the right
bound. This is illustrated below, where x represents
a range in x and [ and ] indicate the bounds:
[..xxx.....]
becomes
[.....xxx..]restrict restricts the ranges in x to the interval(s)
specified by the start and end arguments.
threebands extends the capability of narrow by returning
the 3 ranges objects associated to the narrowing operation.
The returned value y is a list of 3 ranges objects named
"left", "middle" and "right".
The middle component is obtained by calling narrow with the
same arguments (except that names are dropped). The left and right
components are also instances of the same class as x and they
contain what has been removed on the left and right sides (respectively)
of the original ranges during the narrowing.
Note that original object x can be reconstructed from the
left and right bands with punion(y$left, y$right, fill.gap=TRUE).
H. Pagès, M. Lawrence, and P. Aboyoun
inter-range-methods for inter range transformations.
The IRanges, IPos, Views, RangesList, and MaskCollection classes.
The intra-range-methods man page in the GenomicRanges package for intra range transformations of genomic ranges.
setops-methods for set operations on IRanges objects.
endoapply in the S4Vectors package.
## --------------------------------------------------------------------- ## shift() ## --------------------------------------------------------------------- ## On an IRanges object: ir1 <- successiveIRanges(c(19, 5, 0, 8, 5)) ir1 shift(ir1, shift=-3) ## On an IRangesList object: range1 <- IRanges(start=c(1, 2, 3), end=c(5, 2, 8)) range2 <- IRanges(start=c(15, 45, 20, 1), end=c(15, 100, 80, 5)) range3 <- IRanges(start=c(-2, 6, 7), width=c(8, 0, 0)) # with empty ranges collection <- IRangesList(one=range1, range2, range3) shift(collection, shift=5) # same as endoapply(collection, shift, shift=5) ## Sanity check: res1 <- shift(collection, shift=5) res2 <- endoapply(collection, shift, shift=5) stopifnot(identical(res1, res2)) ## --------------------------------------------------------------------- ## narrow() ## --------------------------------------------------------------------- ## On an IRanges object: ir2 <- ir1[width(ir1) != 0] narrow(ir2, start=4, end=-2) narrow(ir2, start=-4, end=-2) narrow(ir2, end=5, width=3) narrow(ir2, start=c(3, 4, 2, 3), end=c(12, 5, 7, 4)) ## On an IRangesList object: narrow(collection[-3], start=2) narrow(collection[-3], end=-2) ## On a MaskCollection object: mask1 <- Mask(mask.width=29, start=c(11, 25, 28), width=c(5, 2, 2)) mask2 <- Mask(mask.width=29, start=c(3, 10, 27), width=c(5, 8, 1)) mask3 <- Mask(mask.width=29, start=c(7, 12), width=c(2, 4)) mymasks <- append(append(mask1, mask2), mask3) mymasks narrow(mymasks, start=8) ## --------------------------------------------------------------------- ## resize() ## --------------------------------------------------------------------- ## On an IRanges object: resize(ir2, 200) resize(ir2, 2, fix="end") ## On an IRangesList object: resize(collection, width=200) ## --------------------------------------------------------------------- ## flank() ## --------------------------------------------------------------------- ## On an IRanges object: ir3 <- IRanges(c(2,5,1), c(3,7,3)) flank(ir3, 2) flank(ir3, 2, start=FALSE) flank(ir3, 2, start=c(FALSE, TRUE, FALSE)) flank(ir3, c(2, -2, 2)) flank(ir3, 2, both = TRUE) flank(ir3, 2, start=FALSE, both=TRUE) flank(ir3, -2, start=FALSE, both=TRUE) ## On an IRangesList object: flank(collection, width=10) ## --------------------------------------------------------------------- ## promoters() ## --------------------------------------------------------------------- ## On an IRanges object: ir4 <- IRanges(20:23, width=3) promoters(ir4, upstream=0, downstream=0) ## no change promoters(ir4, upstream=0, downstream=1) ## start value only promoters(ir4, upstream=1, downstream=0) ## single upstream nucleotide ## On an IRangesList object: promoters(collection, upstream=5, downstream=2) ## --------------------------------------------------------------------- ## reflect() ## --------------------------------------------------------------------- ## On an IRanges object: bounds <- IRanges(c(0, 5, 3), c(10, 6, 9)) reflect(ir3, bounds) ## reflect() does not yet support IRangesList objects! ## --------------------------------------------------------------------- ## restrict() ## --------------------------------------------------------------------- ## On an IRanges object: restrict(ir1, start=12, end=34) restrict(ir1, start=20) restrict(ir1, start=21) restrict(ir1, start=21, keep.all.ranges=TRUE) ## On an IRangesList object: restrict(collection, start=2, end=8) restrict(collection, start=2, end=8, keep.all.ranges=TRUE) ## --------------------------------------------------------------------- ## threebands() ## --------------------------------------------------------------------- ## On an IRanges object: z <- threebands(ir2, start=4, end=-2) ir2b <- punion(z$left, z$right, fill.gap=TRUE) stopifnot(identical(ir2, ir2b)) threebands(ir2, start=-5) ## threebands() does not support IRangesList objects.
Please choose more modern alternatives, such as Google Chrome or Mozilla Firefox.