IRanges-constructor {IRanges} | R Documentation |
The IRanges
function is a constructor that can be used
to create IRanges instances.
solveUserSEW0
and solveUserSEW
are utility functions that
solve a set of user-supplied start/end/width values.
## IRanges constructor: IRanges(start=NULL, end=NULL, width=NULL, names=NULL) ## Supporting functions (not for the end user): solveUserSEW0(start=NULL, end=NULL, width=NULL) solveUserSEW(refwidths, start=NA, end=NA, width=NA, translate.negative.coord=TRUE, allow.nonnarrowing=FALSE)
start, end, width |
For IRanges and solveUserSEW0 : NULL ,
or vector of integers (eventually with NAs).
For |
names |
A character vector or NULL .
|
refwidths |
Vector of non-negative integers containing the reference widths. |
translate.negative.coord, allow.nonnarrowing |
TRUE or FALSE .
|
Return the IRanges object containing the ranges specified by
start
, end
and width
.
Input falls into one of two categories:
start
, end
and width
are numeric vectors
(or NULLs). If necessary they are expanded cyclically to the
length of the longest (NULL arguments are filled with NAs).
After this expansion, each row in the 3-column matrix obtained
by binding those 3 vectors together is "solved" i.e. NAs are
treated as unknown in the equation end = start + width - 1
.
Finally, the solved matrix is returned as an IRanges
instance.
start
argument is a logical vector or logical Rle object
and IRanges(start)
produces the same result as
as(start, "IRanges")
.
Note that, in that case, the returned IRanges instance is guaranteed
to be normal.
names
argument is never recycled (to remain
consistent with what `names<-`
does on standard vectors).
solveUserSEW0(start=NULL, end=NULL, width=NULL)
:
solveUserSEW(refwidths, start=NA, end=NA, width=NA,
translate.negative.coord=TRUE,
allow.nonnarrowing=FALSE)
:
start
, end
and width
must have the same number of
elements as, or less elements than, refwidths
. In the latter case,
they are expanded cyclically to the length of refwidths
(provided
none are of zero length). After this expansion, each row in the 3-column
matrix obtained by binding those 3 vectors together must contain at least
one NA (otherwise an error is returned).
Then each row is "solved" i.e. the 2 following transformations are
performed (i
is the indice of the row):
(1) if translate.negative.coord
is TRUE then a
negative value of start[i]
or end[i]
is
considered to be a -refwidths[i]
-based coordinate so
refwidths[i]+1
is added to it to make it 1-based;
(2) the NAs in the row are treated as unknowns which values are deduced
from the known values in the row and from refwidths[i]
.
The exact rules for (2) are the following.
Rule (2a): if the row contains at least 2 NAs, then width[i]
must be
one of them (otherwise an error is returned), and if start[i]
is one
of them it is replaced by 1, and if end[i]
is one of them it is
replaced by refwidths[i]
, and finally width[i]
is replaced by
end[i] - start[i] + 1
.
Rule (2b): if the row contains only 1 NA, then it is replaced by the solution
of the width[i] == end[i] - start[i] + 1
equation.
Finally, the set of solved rows is returned as an IRanges object
(with the same number of elements as refwidths
).
Note that an error is raised if either (1) the set of
user-supplied start/end/width values is invalid or (2)
allow.nonnarrowing
is FALSE and the ranges represented by the
solved start/end/width values are not narrowing
the ranges represented by the user-supplied start/end/width values.
H. Pages
## --------------------------------------------------------------------- ## A. USING THE IRanges() CONSTRUCTOR ## --------------------------------------------------------------------- IRanges(start=11, end=rep.int(20, 5)) IRanges(start=11, width=rep.int(20, 5)) IRanges(-2, 20) # only one range IRanges(start=c(2, 0, NA), end=c(NA, NA, 14), width=11:0) IRanges() # IRanges instance of length zero IRanges(names=character()) ## With logical input: x <- IRanges(c(FALSE, TRUE, TRUE, FALSE, TRUE)) # logical vector input isNormal(x) # TRUE x <- IRanges(Rle(1:30) %% 5 <= 2) # logical Rle input isNormal(x) # TRUE ## --------------------------------------------------------------------- ## B. USING solveUserSEW() ## --------------------------------------------------------------------- refwidths <- c(5:3, 6:7) refwidths solveUserSEW(refwidths) solveUserSEW(refwidths, start=4) solveUserSEW(refwidths, end=3, width=2) solveUserSEW(refwidths, start=-3) solveUserSEW(refwidths, start=-3, width=2) solveUserSEW(refwidths, end=-4) ## The start/end/width arguments are expanded cyclically solveUserSEW(refwidths, start=c(3, -4, NA), end=c(-2, NA))