IRanges-constructor {IRanges} | R Documentation

## 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 user-supplied start/end/width values.

### Usage

      ## 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)

### Arguments

`start, end, width` | For `IRanges` and `solveUserSEW0`: `NULL`, or vector of integers (eventually with NAs). For `solveUserSEW`: vector of integers (eventually with NAs).
`names` | A character vector or `NULL`.
`refwidths` | Vector of non-negative integers containing the reference widths.
`translate.negative.coord, allow.nonnarrowing` | `TRUE` or `FALSE`.

### 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` 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.
Category 2
  The `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.

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, 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.

### Author(s)

H. Pages

### See Also

IRanges-class, `narrow`

### Examples

      ## ---------------------------------------------------------------------
      ## 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))

[Package IRanges version 1.2.3 Index]