XStringViews-class        package:Biostrings        R Documentation

_T_h_e _X_S_t_r_i_n_g_V_i_e_w_s _c_l_a_s_s

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

     The XStringViews class is the basic container for storing a set of
     views (start/end locations) on the same sequence (an XString
     object).

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

     An XStringViews object contains a set of views (start/end
     locations) on the same XString object called "the subject string"
     or "the subject sequence" or simply "the subject". Each view is
     defined by its start and end locations: both are integers such
     that start <= end. An XStringViews object is in fact a particular
     case of an IRanges object (the XStringViews class contains the
     IRanges class) so it can be manipulated in the same way: see
     IRanges for more information. Note that two views can overlap and
     that a view can be "out of limits" i.e. it can start before the
     first letter of the subject or/and end after its last letter.

_A_c_c_e_s_o_r _m_e_t_h_o_d_s:

     In the code snippets below, 'x' is an XStringViews object.


      'subject(x)': The subject of 'x'. This is always an XString
          object.

      'nchar(x)': A vector of non-negative integers containing the
          number of letters in each view. Values in 'nchar(x)' coincide
          with values in 'width(x)' except for "out of limits" views
          where they are lower.


_O_t_h_e_r _m_e_t_h_o_d_s:

     In the code snippets below, 'x', 'object', 'e1' and 'e2' are
     XStringViews objects, and 'i' can be a numeric or logical vector.


      'x[[i]]': Extract a view as an XString object. 'i' must be a
          single numeric value (a numeric vector of length 1). Can't be
          used for extracting a view that is "out of limits" (raise an
          error). The returned object has the same XString subtype as
          'subject(x)'.

      'e1 == e2': A vector of logicals indicating the result of the
          view by view comparison. The views in the shorter of the two
          XStringViews object being compared are recycled as necessary.

          Like for comparison between XString objects, comparison
          between two XStringViews objects with subjects of different
          classes is not supported with one exception: when the
          subjects are DNAString and RNAString instances.

          Also, like with XString objects, comparison between an
          XStringViews object with a BString subject and a character
          vector is supported (see examples below).

      'e1 != e2': Equivalent to '!(e1 == e2)'.

      'as.character(x, use.names, check.limits)': Convert 'x' to a
          character vector of the same length as 'x'. 'use.names'
          controls whether or not 'desc(x)' should be used to set the
          names of the returned vector (default is 'TRUE').
          'check.limits' controls whether or not an error should be
          raised if 'x' contains "out of limit" views (default is
          'TRUE'). With 'check.limits=FALSE' then "out of limit" views
          are padded with spaces.

      'as.matrix(x, mode, use.names, check.limits)': Depending on what
          'mode' is choosen ('"integer"' or '"character"'), return
          either a 2-column integer matrix containing 'start(x)' and
          'end(x)' or a character matrix containing the "exploded"
          representation of the views. 'mode="character"' can only be
          used on an XStringViews object with equal-width views.
          Arguments 'use.names' and 'check.limits' are ignored with
          'mode="integer"'. With 'mode="character"', 'use.names'
          controls whether or not 'desc(x)' should be used to set the
          row names of the returned matrix (default is 'TRUE'), and
          'check.limits' controls whether or not an error should be
          raised if 'x' contains "out of limit" views (default is
          'TRUE'). With 'check.limits=FALSE' then "out of limit" views
          are padded with spaces.

      'as.list(x)': Convert 'x' to a list of XString objects. Can't be
          used if 'x' has "out of limits" views (raise an error).

      'toString(x)': Equivalent to 'toString(as.character(x))'.


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

     H. Pages

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

     IRanges-class, XStringViews-constructors, XString-class,
     XStringSet-class, 'letter'

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

       ## One standard way to create an XStringViews object is to use
       ## the "views" constructor:
       s <- DNAString("-CTC-N")
       v4 <- views(s, 3:0, 5:8)
       v4
       subject(v4)
       length(v4)
       start(v4)
       end(v4)
       width(v4)

       ## Attach a comment to views #3 and #4:
       desc(v4)[3:4] <- "out of limits"
       desc(v4)

       ## A more programatical way to "tag" the "out of limits" views:
       desc(v4)[start(v4) < 1 | nchar(subject(v4)) < end(v4)] <- "out of limits"
       ## or just:
       desc(v4)[nchar(v4) < width(v4)] <- "out of limits"

       ## Two equivalent ways to extract a view as an XString object:
       s2a <- v4[[2]]
       s2b <- subXString(subject(v4), start(v4)[2], end(v4)[2])
       identical(s2a, s2b) # TRUE

       ## It is an error to try to extract an "out of limits" view:
       #v4[[3]] # Error!

       v12 <- views(DNAString("TAATAATG"), -2:9, 0:11)
       v12 == DNAString("TAA")
       v12[v12 == v12[4]]
       v12[v12 == v12[1]]
       v12[3] == views(RNAString("AU"), 0, 2)

       ## Here the first view doesn't even overlap with the subject:
       views(BString("aaa--b"), -3:4, -3:4 + c(3:6, 6:3))

