BStringViews-class        package:Biostrings        R Documentation

_T_h_e _B_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:

     A container for a set of views on the same BString (or derived)
     object.

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

     A BStringViews object contains a set of views on the same BString
     (or derived) 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.
     Note that two views can overlap and that a view can be "out of
     limits" i.e. it starts before the first letter of the subject
     or/and ends 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 a BStringViews object.

      'subject(x)': The subject of 'x'. This is always a BString (or
          derived) object.

      'length(x)': The number of views in 'x'.

      'start(x)': The starting positions of the views. An integer
          vector of the same length as 'x'.

      'first(x)': deprecated. Use 'start' instead.

      'end(x)': The ending positions of the views. An integer vector of
          the same length as 'x'.

      'last(x)': deprecated. Use 'end' instead.

      'width(x)': The width of the views. Equivalent to 'end(x) -
          start(x) + 1L'. A vector of positive integers of the same
          length as 'x'.

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

      'desc(x)': 'NULL' or a character vector of the same length as 'x'
          containing a short user provided description or comment for
          each view. These are the only data in a BStringViews object
          that can safely be changed by the user. All the other data
          are immutable! As a general recommendation, the user should
          never try to modify an object by accessing its slots
          directly.

_S_t_a_n_d_a_r_d _g_e_n_e_r_i_c _m_e_t_h_o_d_s:

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

      'x[i]': Return a new BStringViews object made of the selected
          views. 'i' can be a numeric vector, a logical vector, 'NULL'
          or missing. The returned object has the same subject as 'x'.

      'x[[i]]': Extract a view as a BString (or derived) 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 belongs to the
          same class 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
          BStringViews object being compared are recycled as necessary.

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

          Also, like with BString objects, comparison between a
          BStringViews object with a subject of class "BString" 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 a BStringViews 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 BString 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:

     BStringViews-constructors, BString-class, DNAString-class,
     RNAString-class, AAString-class, 'letter'

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

       s <- DNAString("-CTC-N")

       ## One standard way to create a BStringViews object is to use
       ## the "views" constructor:
       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"

       ## Make a new BStringViews object by selecting some views only:
       v4[4:2]               # 3 views
       v4[-1]                # 3 views
       v4[c(2,4)]            # 2 views
       v4[width(v4) >= 5]    # 3 views
       v4[is.na(desc(v4))]   # 2 views
       v4[!is.na(desc(v4))]  # 2 views
       v4[3]                 # 1 view
       v4[FALSE]             # 0 view

       ## Two equivalent ways to extract a view as a BString (or derived) object:
       s2a <- v4[[2]]
       s2b <- subBString(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)

