intra-range-methods {IRanges} | R Documentation |
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.
Range-based endomorphisms are grouped in 2 categories:
Intra range transformations like shift()
that
transform each range individually (and independently of the other
ranges) and return an object of the same length as the
input object. Those transformations are described in this man page.
Inter range transformations like reduce()
that
transform all the ranges together as a set to produce a new set
of ranges and return an object not necessarily of the same length
as the input object.
Those transformations are described in the inter-range-methods
man page (see ?`inter-range-methods`
).
## shift() shift(x, shift=0L, use.names=TRUE) ## narrow() narrow(x, start=NA, end=NA, width=NA, use.names=TRUE) ## resize() resize(x, width, fix="start", use.names=TRUE, ...) ## flank() flank(x, width, start=TRUE, both=FALSE, use.names=TRUE, ...) ## promoters() promoters(x, upstream=2000, downstream=200, ...) ## reflect() reflect(x, bounds, use.names=TRUE) ## restrict() restrict(x, start=NA, end=NA, keep.all.ranges=FALSE, use.names=TRUE) ## threebands() threebands(x, start=NA, end=NA, width=NA)
x |
A Ranges, 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 |
use.names |
|
start, end |
|
width |
|
both |
If |
bounds |
An IRanges object to serve as the reference bounds for the reflection, see below. |
fix |
|
upstream, downstream |
Single Default values for |
keep.all.ranges |
|
... |
Additional arguments for methods. |
Here we start by describing how each transformation operates on a
Ranges object 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 Ranges 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 upsteam
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 GenomicRanges
objects see ?"promoters,GRanges-method"
.
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)
.
When x
in a RangesList object, doing any of the transformation
above is equivalent to applying the transformation to each RangesList
top-level element separately.
H. Pages, M. Lawrence, P. Aboyoun
inter-range-methods for inter range transformations.
The Ranges, Views, RangesList, and MaskCollection classes.
The intra-range-methods man page in the XVector package for methods that operate on XVectorList objects.
The intra-range-methods man page in the GenomicRanges package for methods that operate on GenomicRanges and other objects.
setops-methods for set operations on IRanges objects.
solveUserSEW
for the SEW (Start/End/Width)
interface.
## --------------------------------------------------------------------- ## shift() ## --------------------------------------------------------------------- ## On a Ranges object ir1 <- successiveIRanges(c(19, 5, 0, 8, 5)) ir1 shift(ir1, shift=-3) ## On a RangesList 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) ## --------------------------------------------------------------------- ## narrow() ## --------------------------------------------------------------------- ## On a Ranges 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 a RangesList 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 a Ranges object resize(ir2, 200) resize(ir2, 2, fix="end") ## On a RangesList object resize(collection, width=200) ## --------------------------------------------------------------------- ## flank() ## --------------------------------------------------------------------- ## On a Ranges 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 a RangesList object flank(collection, width=10) ## --------------------------------------------------------------------- ## promoters() ## --------------------------------------------------------------------- ## On a Ranges 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 a RangesList object promoters(collection, upstream=5, downstream=2) ## --------------------------------------------------------------------- ## reflect() ## --------------------------------------------------------------------- ## On a Ranges object bounds <- IRanges(c(0, 5, 3), c(10, 6, 9)) reflect(ir3, bounds) ## reflect() does not yet support RangesList objects! ## --------------------------------------------------------------------- ## restrict() ## --------------------------------------------------------------------- ## On a Ranges object restrict(ir1, start=12, end=34) restrict(ir1, start=20) restrict(ir1, start=21) restrict(ir1, start=21, keep.all.ranges=TRUE) ## On a RangesList object restrict(collection, start=2, end=8) ## --------------------------------------------------------------------- ## threebands() ## --------------------------------------------------------------------- ## On a Ranges 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 RangesList objects.