XVector-class            package:IRanges            R Documentation

XVector objects

Description:

     The XVector virtual class is a general container for storing an
     "external vector". It inherits from the Sequence, which has a very
     rich interface.

     The following classes derive directly from the XVector class:

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

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

     The XDouble class is a container for storing an "external double
     vector" i.e. an external sequence of numeric values (stored as
     double values at the C level).

     Also the XString class from the Biostrings package.

     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.

Additional Subsetting operations on XVector objects:

     In the code snippets below, 'x' is an XVector 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 XVector 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 XVector 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' right value for this). Unlike the extraction method
          above, this replacement method always copies the sequence
          data of 'x' (even for XVector objects). NOTE: Only works for
          XRaw (and derived) objects for now.


Author(s):

     H. Pages

See Also:

     Sequence-class, Views-class, 'solveUserSEW', DNAString-class

Examples:

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

