Views-class             package:IRanges             R Documentation

Views objects

Description:

     The Views virtual class is a general container for storing a set
     of views on an arbitrary Sequence object, called the "subject".

     Its primary purpose is to introduce concepts and provide some
     facilities that can be shared by the concrete classes that derive
     from it.

     Some direct subclasses of the Views class are: XIntegerViews,
     RleViews, XStringViews (defined in the Biostrings package), etc...

Constructor:


      'Views(subject, start=NULL, end=NULL, width=NULL, names=NULL)':
          This constructor is a generic function with dispatch on
          argument 'subject'. Specific methods must be defined for the
          subclasses of the Views class. For example a method for
          XString subjects is defined in the Biostrings package that
          returns an XStringViews object. There is no default method.

          The treatment of the 'start', 'end' and 'width' arguments is
          the same as with the 'IRanges' constructor, except that, in
          addition, 'Views' allows 'start' to be a Ranges object. With
          this feature, 'Views(subject, IRanges(my_starts, my_ends,
          my_widths, my_names))' and 'Views(subject, my_starts,
          my_ends, my_widths, my_names)' are equivalent (except when
          'my_starts' is itself a Ranges object).


Coercion:

     In the code snippets below, 'from' is a Views object:


      'as(from, "IRanges")': Creates an 'IRanges' object containing the
          view locations in 'from'.


Accessor-like methods:

     All the accessor-like methods defined for 'IRanges' objects work
     on Views objects. In addition, the following accessors are defined
     for Views objects:


      'subject(x)': Return the subject of the views.


Subsetting and appending:

     '"["', 'c' and '"[["' work on a Views object. The first two
     operations are just inherited from the 'IRanges' class but now
     they return a Views object. However, the '"[["' method for Views
     objects has a different semantic than the method for 'IRanges'
     objects.


      'x[[i]]': Extracts the view selected by 'i' as an object of the
          same class as 'subject(x)'. Subscript 'i' can be a single
          integer or a character string. The result is the subsequence
          of 'subject(x)' defined by 'window(subject(x),
          start=start(x)[i], end=end(x)[i])' or an error if the view is
          "out of limits" (i.e. 'start(x)[i] < 1' or 'end(x)[i] >
          length(subject(x))').


Other methods:


      'trim(x, use.names=TRUE)': Equivalent to 'restrict(x, start=1L,
          end=length(subject(x)), keep.all.ranges=TRUE,
          use.names=use.names)'.

      'subviews(x, start=NA, end=NA, width=NA, use.names=TRUE)':
          'start', 'end', and 'width' arguments must be vectors of
          integers, eventually with NAs, that contain coordinates
          relative to the current ranges. Equivalent to 'trim(narrow(x,
          start=start, end=end, width=width, use.names=use.names))'.

      'gaps(x, start=NA, end=NA)': 'start' and 'end' can be single
          integers or NAs. The gap extraction will be restricted to the
          window specified by 'start' and 'end'. 'start=NA' and
          'end=NA' are interpreted as 'start=1' and
          'end=length(subject(x))', respectively, so, if 'start' and
          'end' are not specified, then gaps are extracted with respect
          to the entire subject.

      'successiveViews(subject, width, gapwidth=0, from=1)': Equivalent
          to 'Views(subject, successiveIRanges(width, gapwidth,
          from))'. See '?successiveIRanges' for a description of the
          'width', 'gapwidth' and 'from' arguments.


Author(s):

     H. Pages

See Also:

     IRanges-class, Sequence-class, IRanges-utils, XVector.

     Some direct subclasses of the Views class: XIntegerViews-class,
     RleViews-class, XStringViews-class.

Examples:

       showClass("Views")  # shows (some of) the known subclasses

       ## Create a set of 4 views on an XInteger subject of length 10:
       subject <- XInteger(10, 3:-6)
       v1 <- Views(subject, start=4:1, end=4:7)

       ## Extract the 2nd view:
       v1[[2]]

       ## Some views can be "out of limits"
       v2 <- Views(subject, start=4:-1, end=6)
       trim(v2)
       subviews(v2, end=-2)

       ## gaps() 
       v3 <- Views(subject, start=c(8, 3), end=c(14, 4))
       gaps(v3)

       ## Views on a big XInteger subject:
       subject <- XInteger(99999, sample(99, 99999, replace=TRUE) - 50)
       v4 <- Views(subject, start=1:99*1000, end=1:99*1001)
       v4
       v4[-1]
       v4[[5]]

       ## 31 adjacent views:
       successiveViews(subject, 40:10)

