IRanges-constructor         package:IRanges         R Documentation

_T_h_e _I_R_a_n_g_e_s _c_o_n_s_t_r_u_c_t_o_r _a_n_d _s_u_p_p_o_r_t_i_n_g _f_u_n_c_t_i_o_n_s

_D_e_s_c_r_i_p_t_i_o_n:

     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.

_U_s_a_g_e:

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

_A_r_g_u_m_e_n_t_s:

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

_I_R_a_n_g_e_s _c_o_n_s_t_r_u_c_t_o_r:

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

     _C_a_t_e_g_o_r_y _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.

     _C_a_t_e_g_o_r_y _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).

_S_u_p_p_o_r_t_i_n_g _f_u_n_c_t_i_o_n_s:


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


_A_u_t_h_o_r(_s):

     H. Pages

_S_e_e _A_l_s_o:

     IRanges-class, 'narrow'

_E_x_a_m_p_l_e_s:

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

