Description Details Methods Normality Author(s) See Also Examples
The IPosRanges virtual class is a general container for storing a vector of ranges of integer positions.
An IPosRanges object is a vectorlike object where each element describes a "range of integer positions".
A "range of integer values" is a finite set of consecutive integer values. Each range can be fully described with exactly 2 integer values which can be arbitrarily picked up among the 3 following values: its "start" i.e. its smallest (or first, or leftmost) value; its "end" i.e. its greatest (or last, or rightmost) value; and its "width" i.e. the number of integer values in the range. For example the set of integer values that are greater than or equal to 20 and less than or equal to 400 is the range that starts at 20 and has a width of 421. In other words, a range is a closed, onedimensional interval with integer end points and on the domain of integers.
The starting point (or "start") of a range can be any integer (see
start
below) but its "width" must be a nonnegative integer
(see width
below). The ending point (or "end") of a range is
equal to its "start" plus its "width" minus one (see end
below).
An "empty" range is a range that contains no value i.e. a range that
has a null width. Depending on the context, it can be interpreted
either as just the empty set of integers or, more precisely,
as the position between its "end" and its "start" (note that
for an empty range, the "end" equals the "start" minus one).
The length of an IPosRanges object is the number of ranges in it, not the number of integer values in its ranges.
An IPosRanges object is considered empty iff all its ranges are empty.
IPosRanges objects have a vectorlike semantic i.e. they only support single subscript subsetting (unlike, for example, standard R data frames which can be subsetted by row and by column).
The IPosRanges class itself is a virtual class. The following classes derive directly from it: IRanges, IPos, NCList, and GroupingRanges.
In the code snippets below, x
, y
and object
are
IPosRanges objects. Not all the functions described below will necessarily
work with all kinds of IPosRanges derivatives but they should work at
least for IRanges objects.
Note that many more operations on IPosRanges objects are described in
other man pages of the IRanges package. See for example the man page
for intra range transformations (e.g. shift()
, see
?`intrarangemethods`
), or the man page for inter range
transformations (e.g. reduce()
, see
?`interrangemethods`
), or the man page for
findOverlaps
methods (see ?`findOverlapsmethods`
),
or the man page for IntegerRangesList objects where the split
method for IntegerRanges derivatives is documented.
length(x)
:
The number of ranges in x
.
start(x)
:
The start values of the ranges.
This is an integer vector of the same length as x
.
width(x)
:
The number of integer values in each range.
This is a vector of nonnegative integers of the same length as x
.
end(x)
:
start(x) + width(x)  1L
mid(x)
: returns the midpoint of the range,
start(x) + floor((width(x)  1)/2)
.
names(x)
:
NULL
or a character vector of the same length as x
.
tile(x, n, width, ...)
:
Splits each range in x
into subranges as specified by n
(number of ranges) or width
. Only one of n
or width
can be specified. The return value is a IRangesList
the same
length as x
. IPosRanges with a width less than the width
argument are returned unchanged.
slidingWindows(x, width, step=1L)
: Generates sliding
windows within each range of x
, of width width
, and
starting every step
positions. The return value is a
IRangesList
the same length as x
. IPosRanges
with a width less than the width
argument are returned
unchanged. If the sliding windows do not exactly cover x
,
the last window is partial.
isEmpty(x)
:
Return a logical value indicating whether x
is empty or not.
as.matrix(x, ...)
:
Convert x
into a 2column integer matrix
containing start(x)
and width(x)
.
Extra arguments (...
) are ignored.
as.data.frame(x, row.names=NULL, optional=FALSE)
:
Convert x
into a standard R data frame object.
row.names
must be NULL
or a character vector giving
the row names for the data frame, and optional
is ignored.
See ?as.data.frame
for more information about these
arguments.
x[[i]]
:
Return integer vector start(x[i]):end(x[i])
denoted by i
.
Subscript i
can be a single integer or a character string.
x[i]
:
Return a new IPosRanges object (of the same type as x
) made
of the selected ranges.
i
can be a numeric vector, a logical vector, NULL
or missing. If x
is a NormalIRanges object and
i
a positive numeric subscript (i.e. a numeric vector of
positive values), then i
must be strictly increasing.
rep(x, times, length.out, each)
:
Repeats the values in x
through one of the following conventions:
times
Vector giving the number of times to repeat each
element if of length length(x)
, or to repeat the
IPosRanges elements if of length 1.
length.out
Nonnegative integer. The desired length of the output vector.
each
Nonnegative integer. Each element of x
is
repeated each
times.
c(x, ..., ignore.mcols=FALSE)
:
Concatenate IPosRanges object x
and the IPosRanges objects
in ...
together.
See ?c
in the S4Vectors package
for more information about concatenating Vector derivatives.
x * y
:
The arithmetic operation x * y
is for centered zooming. It
symmetrically scales the width of x
by 1/y
, where
y
is a numeric vector that is recycled as necessary. For
example, x * 2
results in ranges with half their previous width
but with approximately the same midpoint. The ranges have been
“zoomed in”. If y
is negative, it is equivalent to
x * (1/abs(y))
. Thus, x * 2
would double the widths in
x
. In other words, x
has been “zoomed out”.
x + y
: Expands the ranges in x
on either side by the
corresponding value in the numeric vector y
.
show(x)
:
By default the show
method displays 5 head and 5 tail
lines. The number of lines can be altered by setting the global
options showHeadLines
and showTailLines
. If the
object length is less than the sum of the options, the full object
is displayed. These options affect display of IRanges,
IPos, Hits, GRanges,
GPos, GAlignments,
XStringSet objects, and more...
An IPosRanges object x
is implicitly representing an arbitrary
finite set of integers (that are not necessarily consecutive). This set is
the set obtained by taking the union of all the values in all the ranges in
x
. This representation is clearly not unique: many different
IPosRanges objects can be used to represent the same set of integers.
However one and only one of them is guaranteed to be normal.
By definition an IPosRanges object is said to be normal when its ranges are: (a) not empty (i.e. they have a nonnull width); (b) not overlapping; (c) ordered from left to right; (d) not even adjacent (i.e. there must be a non empty gap between 2 consecutive ranges).
Here is a simple algorithm to determine whether x
is normal:
(1) if length(x) == 0
, then x
is normal;
(2) if length(x) == 1
, then x
is normal iff
width(x) >= 1
;
(3) if length(x) >= 2
, then x
is normal iff:
1 
for every 1 <= i
< length(x)
.
The obvious advantage of using a normal IPosRanges object to represent a given finite set of integers is that it is the smallest in terms of number of ranges and therefore in terms of storage space. Also the fact that we impose its ranges to be ordered from left to right makes it unique for this representation.
A special container (NormalIRanges) is provided for holding a normal IRanges object: a NormalIRanges object is just an IRanges object that is guaranteed to be normal.
Here are some methods related to the notion of normal IPosRanges:
isNormal(x)
:
Return TRUE or FALSE indicating whether x
is normal or not.
whichFirstNotNormal(x)
:
Return NA
if x
is normal, or the smallest valid
indice i
in x
for which x[1:i]
is not normal.
H. Pagès and M. Lawrence
The IRanges class, a concrete IPosRanges direct subclass for storing a set of integer ranges.
The IPos class, an IPosRanges direct subclass for representing a set of integer positions (i.e. integer ranges of width 1).
IPosRangescomparison for comparing and ordering ranges.
findOverlapsmethods for finding/counting overlapping ranges.
intrarangemethods and interrangemethods for intra range and inter range transformations of IntegerRanges derivatives.
coveragemethods for computing the coverage of a set of ranges.
setopsmethods for set operations on ranges.
nearestmethods for finding the nearest range neighbor.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41  ## 
## Basic manipulation
## 
x < IRanges(start=c(2:1, 13:15), width=c(0:3, 2:0))
x
length(x)
start(x)
width(x)
end(x)
isEmpty(x)
as.matrix(x)
as.data.frame(x)
## Subsetting:
x[4:2] # 3 ranges
x[1] # 6 ranges
x[FALSE] # 0 range
x0 < x[width(x) == 0] # 2 ranges
isEmpty(x0)
## Use the replacement methods to resize the ranges:
width(x) < width(x) * 2 + 1
x
end(x) < start(x) # equivalent to width(x) < 0
x
width(x) < c(2, 0, 4)
x
start(x)[3] < end(x)[3]  2 # resize the 3rd range
x
## Name the elements:
names(x)
names(x) < c("range1", "range2")
x
x[is.na(names(x))] # 5 ranges
x[!is.na(names(x))] # 2 ranges
ir < IRanges(c(1,5), c(3,10))
ir*1 # no change
ir*c(1,2) # zoom second range by 2X
ir*2 # zoom out 2X

Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.