GappedRanges-class          package:IRanges          R Documentation

GappedRanges objects

Description:

     The GappedRanges class is a vector-like container for storing a
     set of "gapped ranges".

Details:

     A "gapped range" is conceptually the union of 1 or more
     non-overlapping (and non-empty) ranges ordered from left to right.
     More precisely, a "gapped range" can be represented by a normal
     IRanges object of length >= 1. In particular normality here
     ensures that the individual ranges are non-empty and are separated
     by non-empty gaps. The start of a "gapped range" is the start of
     its first range. The end of a "gapped range" is the end of its
     last range. If we ignore the gaps, then a GappedRanges object can
     be seen as a Ranges object.

Constructor:

     No constructor function is provided for GappedRanges objects. The
     coercion methods described below can be used to create
     GappedRanges objects.

Coercion:


      'as(from, "GappedRanges")': Turns a CompressedNormalIRangesList
          or CompressedIRangesList object into a GappedRanges object.

      'as(from, "RangesList")': Turns a GappedRanges object into a
          RangesList object (more precisely the result will be a
          CompressedNormalIRangesList object).


Accessor methods:

     In the code snippets below, 'x' is a GappedRanges object.


      'length(x)': Returns the number of "gapped ranges" in 'x'.

      'start(x), end(x)': Returns an integer vector of length
          'length(x)' containing the start and end (respectively) of
          each "gapped range" in 'x'. See Details section above for the
          exact definitions of the start and end of a "gapped range".

      'width(x)': Defined as 'end(x) - start(x) + 1L'.

      'ngap(x)': Returns an integer vector of length 'length(x)'
          containing the number of gaps for each "gapped range" in 'x'.
          Equivalent to 'elementLengths(x) - 1L'.

      'names(x)': 'NULL' or a character vector of length 'length(x)'.


Subsetting and related operations:

     In the code snippets below, 'x' is a GappedRanges object.


      'x[i]': Returns a new GappedRanges object made of the selected
          "gapped ranges". 'i' can be a numeric, character or logical
          vector, or any of the types supported by the '[' method for
          CompressedNormalIRangesList objects.

      'x[[i]]': Returns the NormalIRanges object representing the i-th
          element in 'x'. Equivalent to 'as(from, "RangesList")[[i]]'.
          'i' can be a single numeric value or a single character
          string.

      'elemenType(x)': Returns the type of 'x[[i]]' as a single string
          (always '"NormalIRanges"'). Note that the semantic of the
          '[[' method for GappedRanges objects is different from the
          semantic of the method for Ranges objects (the latter returns
          an integer vector).

      'elementLengths(x)': Semantically equivalent to

          sapply(seq_len(length(x)), function(i) length(x[[i]]))

          but much faster. Note that the semantic of the
          'elementLengths' method for GappedRanges objects is different
          from the semantic of the method for Ranges objects (the
          latter returns the 'width' of the Ranges object).


Combining and related operations:

     In the code snippets below, 'x' is a GappedRanges object.


      'c(x, ...)': Combine 'x' and the GappedRanges objects in '...'
          together. The result is an object of the same class as 'x'.


Author(s):

     H. Pages

See Also:

     Ranges-class, CompressedNormalIRangesList-class

Examples:

       ## The 3 following IRanges objects are normal. Each of them will be
       ## stored as a "gapped range" in the GappedRanges object 'gr'.
       ir1 <- IRanges(start=c(11, 21, 23), end=c(15, 21, 30))
       ir2 <- IRanges(start=-2, end=15)
       ir3 <- IRanges(start=c(-2, 21), end=c(10, 22))
       irl <- IRangesList(ir1, ir2, ir3)

       gr <- as(irl, "GappedRanges")
       gr

       length(gr)
       start(gr)
       end(gr)
       width(gr)
       ngap(gr)
       gr[-1]
       gr[ngap(gr) >= 1]
       gr[[1]]
       as.integer(gr[[1]])
       gr[[2]]
       as.integer(gr[[2]])
       as(gr, "RangesList")
       start(as(gr, "RangesList"))  # not the same as 'start(gr)'

