Ranges-class             package:IRanges             R Documentation

_R_a_n_g_e_s _o_b_j_e_c_t_s

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

     The Ranges virtual class is a general container for storing a set
     of integer ranges.

_D_e_t_a_i_l_s:

     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. Note that for an empty range, the end is smaller
     than the start.

     Two ranges are considered equal iff they share the same start and
     width. Note that with this definition, 2 empty ranges are
     generally not equal (they need to share the same start to be
     considered equal).

     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 and XRanges.

_M_e_t_h_o_d_s:

     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. Also more operations on Ranges objects
     are described in the man page for IRanges-utils ('shift',
     'restrict', 'narrow', 'reduce', 'gaps'), for IntervalTree objects
     ('overlap') and for RangesList objects ('split' method for Ranges
     objects).


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

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

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

      'duplicated(x)': Determine which elements of 'x' are equal to
          elements with smaller subscripts, and returns a logical
          vector indicating which elements are duplicates. It is
          semantically equivalent to 'duplicated(as.data.frame(x))'
          (see '?duplicated' for more information).

      '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)': Return a new Ranges object made of the repeated
          elements.

      'c(x, ...)': Concatenate 'x' and the Ranges objects in '...'
          together. The result is returned as an IRanges object.


_N_o_r_m_a_l_i_t_y:

     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:

     start(x)[i] <= end(x)[i] < start(x)[i+1] <= end(x)[i+1]

     for every 1 <= 'i' < 'length(x)'.

     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 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 a logical value 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".


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

     H. Pages

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

     IRanges-class, IRanges-utils, IRanges-setops, XRanges-class,
     RangedData-class, IntervalTree-class, 'update', 'as.matrix',
     'as.data.frame', 'duplicated', 'rep'

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

       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
       duplicated(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

