The Ranges virtual class is a general container for storing
a set of integer ranges.
Details
A Ranges object is a vector-like object where each element describes
a "range of integer values".
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, one-dimensional 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 non-negative 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 a Ranges object is the number of ranges in it, not the
number of integer values in its ranges.
A Ranges object is considered empty iff all its ranges are empty.
Ranges objects have a vector-like 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 Ranges class itself is a virtual class. The following classes derive
directly from the Ranges class: IRanges, NCList,
PartitioningByEnd.
Methods
In the code snippets below, x, y and object are
Ranges objects. Not all the functions described below will necessarily
work with all kinds of Ranges objects but they should work at least
for IRanges objects.
Note that many more operations on Ranges 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
?`intra-range-methods`), or the man page for inter range
transformations (e.g. reduce(), see
?`inter-range-methods`), or the man page for
findOverlaps methods (see ?`findOverlaps-methods`),
or the man page for RangesList objects where the split
method for Ranges objects 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 non-negative 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.
update(object, ...):
Convenience method for combining multiple modifications of
object in one single call. For example
object <- update(object, start=start(object)-2L,
end=end(object)+2L)
is equivalent to
start(object) <- start(object)-2L; end(object) <- end(object)+2L.
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. Ranges with a width less than the width
argument are returned unchanged.
isEmpty(x):
Return a logical value indicating whether x is empty or not.
as.matrix(x, ...):
Convert x into a 2-column 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 and any
additional argument (...) is ignored.
See ?as.data.frame for more information about these
arguments.
as.integer(x):
Convert x into an integer vector, by converting each range
into the integer sequence formed by from:to and concatenating
them together.
unlist(x, recursive = TRUE, use.names = TRUE):
Similar to as.integer(x) except can add names to elements.
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 Ranges 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 Ranges
elements if of length 1.
length.out
Non-negative integer. The desired length of
the output vector.
each
Non-negative integer. Each element of x is
repeated each times.
c(x, ...):
Combine x and the Ranges objects in ... together.
Any object in ... must belong to the same class as x,
or to one of its subclasses, or must be NULL.
The result is an object of the same class as x.
NOTE: Only works for IRanges (and derived) objects for now.
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 GRanges, GAlignments,
Ranges and XString objects.
Normality
A Ranges 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
Ranges 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 a Ranges object is said to be "normal" when its ranges are:
(a) not empty (i.e. they have a non-null 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:
The obvious advantage of using a "normal" Ranges 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" Ranges:
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".
Author(s)
H. Pag<c3><83><c2><a8>s and M. Lawrence
See Also
IRanges objects (NormalIRanges objects are documented
in the same man page).
Ranges-comparison for comparing and ordering ranges.
findOverlaps-methods for finding/counting overlapping ranges.
intra-range-methods and
inter-range-methods for intra range and
inter range transformations of a Ranges object.
coverage-methods for computing the coverage
of a set of ranges.
setops-methods for set operations on ranges.
nearest-methods for finding the nearest range neighbor.
Examples
## ---------------------------------------------------------------------
## 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
Results
R version 3.3.1 (2016-06-21) -- "Bug in Your Hair"
Copyright (C) 2016 The R Foundation for Statistical Computing
Platform: x86_64-pc-linux-gnu (64-bit)
R is free software and comes with ABSOLUTELY NO WARRANTY.
You are welcome to redistribute it under certain conditions.
Type 'license()' or 'licence()' for distribution details.
R is a collaborative project with many contributors.
Type 'contributors()' for more information and
'citation()' on how to cite R or R packages in publications.
Type 'demo()' for some demos, 'help()' for on-line help, or
'help.start()' for an HTML browser interface to help.
Type 'q()' to quit R.
> library(IRanges)
Loading required package: BiocGenerics
Loading required package: parallel
Attaching package: 'BiocGenerics'
The following objects are masked from 'package:parallel':
clusterApply, clusterApplyLB, clusterCall, clusterEvalQ,
clusterExport, clusterMap, parApply, parCapply, parLapply,
parLapplyLB, parRapply, parSapply, parSapplyLB
The following objects are masked from 'package:stats':
IQR, mad, xtabs
The following objects are masked from 'package:base':
Filter, Find, Map, Position, Reduce, anyDuplicated, append,
as.data.frame, cbind, colnames, do.call, duplicated, eval, evalq,
get, grep, grepl, intersect, is.unsorted, lapply, lengths, mapply,
match, mget, order, paste, pmax, pmax.int, pmin, pmin.int, rank,
rbind, rownames, sapply, setdiff, sort, table, tapply, union,
unique, unsplit
Loading required package: S4Vectors
Loading required package: stats4
Attaching package: 'S4Vectors'
The following objects are masked from 'package:base':
colMeans, colSums, expand.grid, rowMeans, rowSums
> png(filename="/home/ddbj/snapshot/RGM3/R_BC/result/IRanges/Ranges-class.Rd_%03d_medium.png", width=480, height=480)
> ### Name: Ranges-class
> ### Title: Ranges objects
> ### Aliases: class:Ranges Ranges-class Ranges length,Ranges-method
> ### elementNROWS,Ranges-method width start,Ranges-method
> ### width,Ranges-method end,Ranges-method mid mid,Ranges-method start<-
> ### width<- end<- as.matrix,Ranges-method as.data.frame,Ranges-method
> ### as.integer,Ranges-method unlist,Ranges-method show,Ranges-method
> ### showAsCell,Ranges-method isEmpty,Ranges-method isNormal
> ### isNormal,Ranges-method whichFirstNotNormal
> ### whichFirstNotNormal,Ranges-method update,Ranges-method tile
> ### tile,Ranges-method
> ### Keywords: methods classes
>
> ### ** Examples
>
> ## ---------------------------------------------------------------------
> ## Basic manipulation
> ## ---------------------------------------------------------------------
> x <- IRanges(start=c(2:-1, 13:15), width=c(0:3, 2:0))
> x
IRanges object with 7 ranges and 0 metadata columns:
start end width
<integer> <integer> <integer>
[1] 2 1 0
[2] 1 1 1
[3] 0 1 2
[4] -1 1 3
[5] 13 14 2
[6] 14 14 1
[7] 15 14 0
> length(x)
[1] 7
> start(x)
[1] 2 1 0 -1 13 14 15
> width(x)
[1] 0 1 2 3 2 1 0
> end(x)
[1] 1 1 1 1 14 14 14
> isEmpty(x)
[1] FALSE
> as.matrix(x)
[,1] [,2]
[1,] 2 0
[2,] 1 1
[3,] 0 2
[4,] -1 3
[5,] 13 2
[6,] 14 1
[7,] 15 0
> as.data.frame(x)
start end width
1 2 1 0
2 1 1 1
3 0 1 2
4 -1 1 3
5 13 14 2
6 14 14 1
7 15 14 0
>
> ## Subsetting:
> x[4:2] # 3 ranges
IRanges object with 3 ranges and 0 metadata columns:
start end width
<integer> <integer> <integer>
[1] -1 1 3
[2] 0 1 2
[3] 1 1 1
> x[-1] # 6 ranges
IRanges object with 6 ranges and 0 metadata columns:
start end width
<integer> <integer> <integer>
[1] 1 1 1
[2] 0 1 2
[3] -1 1 3
[4] 13 14 2
[5] 14 14 1
[6] 15 14 0
> x[FALSE] # 0 range
IRanges object with 0 ranges and 0 metadata columns:
start end width
<integer> <integer> <integer>
> x0 <- x[width(x) == 0] # 2 ranges
> isEmpty(x0)
[1] TRUE
>
> ## Use the replacement methods to resize the ranges:
> width(x) <- width(x) * 2 + 1
> x
IRanges object with 7 ranges and 0 metadata columns:
start end width
<integer> <integer> <integer>
[1] 2 2 1
[2] 1 3 3
[3] 0 4 5
[4] -1 5 7
[5] 13 17 5
[6] 14 16 3
[7] 15 15 1
> end(x) <- start(x) # equivalent to width(x) <- 0
> x
IRanges object with 7 ranges and 0 metadata columns:
start end width
<integer> <integer> <integer>
[1] 2 2 1
[2] 1 1 1
[3] 0 0 1
[4] -1 -1 1
[5] 13 13 1
[6] 14 14 1
[7] 15 15 1
> width(x) <- c(2, 0, 4)
Warning message:
In x@width[] <- S4Vectors:::numeric2integer(value) :
number of items to replace is not a multiple of replacement length
> x
IRanges object with 7 ranges and 0 metadata columns:
start end width
<integer> <integer> <integer>
[1] 2 3 2
[2] 1 0 0
[3] 0 3 4
[4] -1 0 2
[5] 13 12 0
[6] 14 17 4
[7] 15 16 2
> start(x)[3] <- end(x)[3] - 2 # resize the 3rd range
> x
IRanges object with 7 ranges and 0 metadata columns:
start end width
<integer> <integer> <integer>
[1] 2 3 2
[2] 1 0 0
[3] 1 3 3
[4] -1 0 2
[5] 13 12 0
[6] 14 17 4
[7] 15 16 2
>
> ## Name the elements:
> names(x)
NULL
> names(x) <- c("range1", "range2")
> x
IRanges object with 7 ranges and 0 metadata columns:
start end width
<integer> <integer> <integer>
range1 2 3 2
range2 1 0 0
NA 1 3 3
NA -1 0 2
NA 13 12 0
NA 14 17 4
NA 15 16 2
> x[is.na(names(x))] # 5 ranges
IRanges object with 5 ranges and 0 metadata columns:
start end width
<integer> <integer> <integer>
NA 1 3 3
NA -1 0 2
NA 13 12 0
NA 14 17 4
NA 15 16 2
> x[!is.na(names(x))] # 2 ranges
IRanges object with 2 ranges and 0 metadata columns:
start end width
<integer> <integer> <integer>
range1 2 3 2
range2 1 0 0
>
> ir <- IRanges(c(1,5), c(3,10))
> ir*1 # no change
IRanges object with 2 ranges and 0 metadata columns:
start end width
<integer> <integer> <integer>
[1] 1 3 3
[2] 5 10 6
> ir*c(1,2) # zoom second range by 2X
IRanges object with 2 ranges and 0 metadata columns:
start end width
<integer> <integer> <integer>
[1] 1 3 3
[2] 6 8 3
> ir*-2 # zoom out 2X
IRanges object with 2 ranges and 0 metadata columns:
start end width
<integer> <integer> <integer>
[1] -1 4 6
[2] 2 13 12
>
>
>
>
>
> dev.off()
null device
1
>