BStringViews-class {Biostrings}R Documentation

The BStringViews class

Description

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

Details

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.

Accesor methods

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.

Standard generic methods

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

Author(s)

H. Pages

See Also

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

Examples

  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)

[Package Biostrings version 2.6.6 Index]