The IRanges constructor and supporting functions
Description
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 usersupplied start/end/width values.
Usage
1 2 3 4 5 6 7 8 9  ## 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,
rep.refwidths=FALSE,
translate.negative.coord=TRUE,
allow.nonnarrowing=FALSE)

Arguments
start, end, width 
For For 
names 
A character vector or 
refwidths 
Vector of nonNA nonnegative integers containing the reference widths. 
rep.refwidths 

translate.negative.coord, allow.nonnarrowing 

IRanges constructor
Return the IRanges object containing the ranges specified by
start
, end
and width
.
Input falls into one of two categories:
 Category 1

start
,end
andwidth
are numeric vectors (or NULLs). If necessary they are recycled to the length of the longest (NULL arguments are filled with NAs). After this recycling, each row in the 3column matrix obtained by binding those 3 vectors together is "solved" i.e. NAs are treated as unknown in the equationend = start + width  1
. Finally, the solved matrix is returned as an IRanges instance.  Category 2

The
start
argument is a logical vector or logical Rle object andIRanges(start)
produces the same result asas(start, "IRanges")
. Note that, in that case, the returned IRanges instance is guaranteed to be normal.
Note that the names
argument is never recycled (to remain
consistent with what `names<`
does on standard vectors).
Supporting functions

solveUserSEW0(start=NULL, end=NULL, width=NULL)
: 
solveUserSEW(refwidths, start=NA, end=NA, width=NA, rep.refwidths=FALSE, translate.negative.coord=TRUE, allow.nonnarrowing=FALSE)
: Use ofrep.refwidths=TRUE
is supported only whenrefwidths
is of length 1. Ifrep.refwidths=FALSE
(the default) thenstart
,end
andwidth
are recycled to the length ofrefwidths
(it's an error if one of them is longer thanrefwidths
, or is of zero length whilerefwidths
is not). Ifrep.refwidths=TRUE
thenrefwidths
is first replicated L times where L is the length of the longest ofstart
,end
andwidth
. After this replication,start
,end
andwidth
are recycled to the new length ofrefwidths
(L) (it's an error if one of them is of zero length while L is != 0).From now,
refwidths
,start
,end
andwidth
are integer vectors of equal lengths. Each row in the 3column 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) iftranslate.negative.coord
is TRUE then a negative value ofstart[i]
orend[i]
is considered to be arefwidths[i]
based coordinate sorefwidths[i]+1
is added to it to make it 1based; (2) the NAs in the row are treated as unknowns which values are deduced from the known values in the row and fromrefwidths[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 ifstart[i]
is one of them it is replaced by 1, and ifend[i]
is one of them it is replaced byrefwidths[i]
, and finallywidth[i]
is replaced byend[i]  start[i] + 1
. Rule (2b): if the row contains only 1 NA, then it is replaced by the solution of thewidth[i] == end[i]  start[i] + 1
equation.Finally, the set of solved rows is returned as an IRanges object of the same length as
refwidths
(after replication ifrep.refwidths=TRUE
).Note that an error is raised if either (1) the set of usersupplied 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 usersupplied start/end/width values.
Author(s)
Hervé Pagès
See Also
IRangesclass,
narrow
Examples
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  ## 
## 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 recycled:
solveUserSEW(refwidths, start=c(3, 4, NA), end=c(2, NA))
## Using 'rep.refwidths=TRUE':
solveUserSEW(10, start=(1:6), rep.refwidths=TRUE)
solveUserSEW(10, end=(1:6), width=3, rep.refwidths=TRUE)
