Sequence-class            package:IRanges            R Documentation

_S_e_q_u_e_n_c_e _o_b_j_e_c_t_s

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

     The Sequence virtual class is a general container for storing a
     sequence i.e. an ordered set of elements. These containers come in
     three types:  XSequence, XRle [DEPRECATED], and Rle.

     The XSequence virtual class is a general container for storing an
     "external sequence". The following classes derive directly from
     the XSequence class.

     The XRaw class is a container for storing an external sequence of
     bytes (stored as char values at the C level).

     The XInteger class is a container for storing an external sequence
     of integer values (stored as int values at the C level).

     The XNumeric class is a container for storing an external sequence
     of numeric values (stored as double values at the C level).

     Also the XString class from the Biostrings package

     The XRle [DEPRECATED - use Rle] virtual class is a general
     container for storing an "external sequence" that is stored in a
     run-length encoding format. The following classes derive directly
     from the XRle class.

     The XRleInteger [DEPRECATED - use Rle] class is a container for
     storing an external run-length encoding of integers (stored as int
     values at the C level).

     The purpose of the X* containers is to provide a "pass by address"
     semantic and also to avoid the overhead of copying the sequence
     data when a linear subsequence needs to be extracted.

     For information on the Rle class, type 'help(Rle)'.

_C_o_m_b_i_n_i_n_g:

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


      'c(x, ...)': Combine 'x' and the Sequence objects in '...'
          together. Any object in '...' must belong to the same class
          as 'x', or to one of its subclasses, or must be 'NULL'. The
          result is an object of the same class as 'x'. NOTE: Only
          works for XRaw (and derived) objects for now.


_S_u_b_s_e_t_t_i_n_g:

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


      'subseq(x, start=NA, end=NA, width=NA)': Extract the subsequence
          from 'x' specified by 'start', 'end' and 'width'. The
          supplied start/end/width values are solved by a call to
          'solveUserSEW(length(x), start=start, end=end, width=width)'
          and therefore must be compliant with the rules of the SEW
          (Start/End/Width) interface (see '?solveUserSEW' for the
          details).

          A note about performance: 'subseq' does NOT copy the sequence
          data of an XSequence object. Hence it's very efficient and is
          therefore the recommended way to extract a linear subsequence
          (i.e. a set of consecutive elements) from an XSequence
          object. For example, extracting a 100Mb subsequence from
          Human chromosome 1 (a 250Mb DNAString object) with 'subseq'
          is (almost) instantaneous and has (almost) no memory
          footprint (the cost in time and memory does not depend on the
          length of the original sequence or on the length of the
          subsequence to extract).

      'subseq(x, start=NA, end=NA, width=NA) <- value': Replace the
          subsequence specified on the left (i.e. the subsequence in
          'x' specified by 'start', 'end' and 'width') by 'value'.
          'value' must belong to the same class as 'x', or to one of
          its subclasses, or must be 'NULL'. This replacement method
          can modify the length of 'x', depending on how the length of
          the left subsequence compares to the length of 'value'. It
          can be used for inserting elements in 'x' (specify an empty
          left subsequence for this) or deleting elements from 'x' (use
          a 'NULL' rigth value for this). Unlike the extraction method
          above, this replacement method always copies the sequence
          data of 'x' (even for XSequence objects). NOTE: Only works
          for XRaw (and derived) objects for now.

      'x[i, drop=TRUE]': Return a new Sequence object made of the
          selected elements (subscript 'i' must be an NA-free numeric
          vector specifying the positions of the elements to select).
          The 'drop' argument specifies whether or not to coerce the
          returned sequence to a standard vector.

      'rep(x, times)': Return a new Sequence object made of the
          repeated elements.


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

     Rle-class, Views-class, 'solveUserSEW', DNAString-class

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

       ## ---------------------------------------------------------------------
       ## A. XRaw OBJECTS
       ## ---------------------------------------------------------------------

       x1 <- XRaw(4)  # values are not initialized
       x1
       x2 <- as(c(255, 255, 199), "XRaw")
       x2
       y <- c(x1, x2, NULL, x1)  # NULLs are ignored
       y
       subseq(y, start=-4)
       subseq(y, start=-4) <- x2
       y

       ## ---------------------------------------------------------------------
       ## B. XInteger OBJECTS
       ## ---------------------------------------------------------------------

       x3 <- XInteger(12, val=c(-1:10))
       x3
       length(x3)

       ## Subsetting
       x4 <- XInteger(99999, val=sample(99, 99999, replace=TRUE) - 50)
       x4
       subseq(x4, start=10)
       subseq(x4, start=-10)
       subseq(x4, start=-20, end=-10)
       subseq(x4, start=10, width=5)
       subseq(x4, end=10, width=5)
       subseq(x4, end=10, width=0)

       x3[length(x3):1]
       x3[length(x3):1, drop=FALSE]

       x5 <- LETTERS
       subseq(x5, 8, 11) <- x5[11:8]  # swap 8<->11 and 9<->10 elements
       subseq(x5, start=1, width=0) <- c("xx", "yyy")  # insert 2 elements at the beginning
       subseq(x5, end=-1, width=0) <- letters[1:3]  # insert 3 elements at the end
       subseq(x5, end=-4, width=5) <- NULL  # remove 5 elements before the just added ones

