IRanges-utils {IRanges} | R Documentation |
Utility functions for creating or modifying IRanges objects.
## Create an IRanges instance: successiveIRanges(width, gapwidth=0, from=1) ## Turn a logical vector into a set of ranges: whichAsIRanges(x) ## Modify an IRanges object (endomorphisms): shift(x, shift, use.names=TRUE) restrict(x, start=NA, end=NA, keep.all.ranges=FALSE, use.names=TRUE) narrow(x, start=NA, end=NA, width=NA, use.names=TRUE) threebands(x, start=NA, end=NA, width=NA) reduce(x, with.inframe.attrib=FALSE) gaps(x, start=NA, end=NA) ## Other utilities ## S4 method for signature 'Ranges': reflect(x, bounds) ## S4 method for signature 'Ranges': flank(x, width, start = TRUE, both = FALSE) ## S4 method for signature 'Ranges': range(x, ..., na.rm = FALSE) ## Coercion: asNormalIRanges(x, force=TRUE)
width |
For successiveIRanges , must be a vector of non-negative integers
(with no NAs) specifying the widths of the ranges to create.
For narrow and threebands , a vector of integers, eventually
with NAs. See the SEW (Start/End/Width) interface for the details
(?solveUserSEW ).
For flank , the width of the flanking regions. Note that if
both is TRUE , this is effectively doubled. Recycled as
necessary so that each element
corresponds to a range in x .
|
gapwidth |
A single integer or an integer vector with one less element than
the width vector specifying the widths of the gaps separating
one range from the next one.
|
from |
A single integer specifying the starting position of the first range. |
x |
A logical vector for whichAsIRanges .
An IRanges object for shift , restrict , narrow ,
threebands , reduce , gaps and asNormalIRanges .
|
shift |
A single integer. |
use.names |
TRUE or FALSE . Should names be preserved?
|
start, end |
A single integer or NA for all functions except narrow
and threebands .
For narrow and threebands , the supplied start
and end arguments must be vectors of integers, eventually with NAs,
that contain coordinates relative to the current ranges.
See the Details section below.
For flank , start is a logical indicating whether
x should be flanked at the start (TRUE ) or the end
(FALSE ). Recycled as necessary so that each element
corresponds to a range in x .
|
keep.all.ranges |
TRUE or FALSE . Should ranges that become "out of limits"
after restriction be kept?
|
with.inframe.attrib |
TRUE or FALSE . For internal use.
|
bounds |
An IRanges object to serve as the reference bounds for the reflection, see below. |
both |
If TRUE , extends the flanking region width positions
into the range. The resulting range thus straddles the end
point, with width positions on either side.
|
... |
Additional Ranges to consider.
|
na.rm |
Ignored |
force |
TRUE or FALSE . Should x be turned into a
NormalIRanges object even if isNormal(x) is FALSE ?
|
successiveIRanges
returns an IRanges object containing the ranges on
subject
that have the widths specified in the width
vector
and are separated by the gaps specified in gapwidth
.
The first range starts at position from
.
whichAsIRanges
returns an IRanges object containing all of
the ranges where x
is TRUE
.
shift
shifts all the ranges in x
.
restrict
restricts the ranges in x
to the interval
specified by the start
and end
arguments.
narrow
narrows the ranges in x
i.e. each range in the
returned IRanges 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.
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)
.
reduce
first orders the ranges in x
from left to right,
then merges the overlapping or adjacent ones.
gaps
returns the normal IRanges object describing
the set of integers obtained by removing the set of integers described
by x
from the interval specified by the start
and
end
arguments.
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..]
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:
---xxxxxxxIf
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
range
returns an IRanges
instance with a single range,
from the minimum start to the maximum end in the combined ranges of
x
and the arguments in ...
.
If force=TRUE
(the default), then asNormalIRanges
will
turn x
into a NormalIRanges instance by reordering and
reducing the set of ranges if necessary (i.e. only if isNormal(x)
is FALSE
, otherwise the set of ranges will be untouched).
If force=FALSE
, then asNormalIRanges
will turn x
into a NormalIRanges instance only if isNormal(x)
is
TRUE
, otherwise it will raise an error.
Note that when force=FALSE
, the returned object is guaranteed
to contain exactly the same set of ranges than x
.
as(x, "NormalIRanges")
is equivalent to asNormalIRanges(x, force=TRUE)
.
H. Pages and M. Lawrence
Ranges-class,
IRanges-class,
IRanges-setops,
solveUserSEW
,
successiveViews
vec <- as.integer(c(19, 5, 0, 8, 5)) whichAsIRanges(vec >= 5) x <- successiveIRanges(vec) x shift(x, -3) restrict(x, start=12, end=34) y <- x[width(x) != 0] narrow(y, start=4, end=-2) narrow(y, start=-4, end=-2) narrow(y, end=5, width=3) narrow(y, start = c(3, 4, 2, 3), end = c(12, 5, 7, 4)) z <- threebands(y, start=4, end=-2) y0 <- punion(z$left, z$right, fill.gap=TRUE) identical(y, y0) # TRUE threebands(y, start=-5) x <- IRanges(start=c(-2L, 6L, 9L, -4L, 1L, 0L, -6L, 10L), width=c( 5L, 0L, 6L, 1L, 4L, 3L, 2L, 3L)) reduce(x) gaps(x) gaps(x, start=-6, end=20) # Regions of the -6:20 range that are not masked by 'x'. ir1 <- IRanges(c(2,5,1), c(3,7,3)) bounds <- IRanges(c(0, 5, 3), c(10, 6, 9)) reflect(ir1, bounds) flank(ir1, 2) flank(ir1, 2, FALSE) flank(ir1, 2, c(FALSE, TRUE, FALSE)) flank(ir1, c(2, -2, 2)) flank(ir1, 2, both = TRUE) flank(ir1, 2, FALSE, TRUE) flank(ir1, -2, FALSE, TRUE) asNormalIRanges(x) # 3 ranges ordered from left to right and separated by # gaps of width >= 1. ## More on normality: example(`IRanges-class`) isNormal(x16) # FALSE if (interactive()) x16 <- asNormalIRanges(x16) # Error! whichFirstNotNormal(x16) # 57 isNormal(x16[1:56]) # TRUE xx <- asNormalIRanges(x16[1:56]) class(xx) max(xx) min(xx)