Views-class             package:IRanges             R Documentation

_V_i_e_w_s _o_b_j_e_c_t_s

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

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

     More specific classes like the XIntegerViews container derive
     directly from the Views class.

     The primary purpose of the Views virtual class is to introduce
     concepts and provide some facilities shared by the more specific
     containers.

_U_s_a_g_e:

     ## Constructor:

       Views(subject, start=NA, end=NA, names=NULL)

     ## Accessor:

       subject(x)

     ## View extraction:

       ## S4 method for signature 'Views':
       x[[i, j, ...]]

     ## Utilities:

       ## S4 method for signature 'Views':
       restrict(x, start, end, keep.all.ranges=FALSE, use.names=TRUE)

       trim(x, use.names=TRUE)

       ## S4 method for signature 'Views':
       narrow(x, start=NA, end=NA, width=NA, use.names=TRUE)

       subviews(x, start=NA, end=NA, width=NA, use.names=TRUE)

       ## S4 method for signature 'Views':
       gaps(x, start=NA, end=NA)

       successiveViews(subject, width, gapwidth=0, from=1)

_A_r_g_u_m_e_n_t_s:

 subject: The Sequence object on which to create the views. 

start, end: For 'Views', they must be integer vectors (eventually with
          NAs) specifying the starting and ending positions of the
          views to create.

          For 'restrict', they must be single integers specifying the
          restriction window.

          For 'narrow' and 'subviews', they can be single integers or
          NAs.

          For 'gaps', they 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
          from the entire subject. 

   width: For 'narrow' and 'subviews', can be 'NA', a single integer,
          or an integer vector of the same length as 'x'.

          For 'successiveViews', must be a vector of positive integers
          (with no NAs) specifying the widths of the views to create. 

   names: If not 'NULL', the names to assign to the views. 

       x: A Views object. 

i, j, ...: Only one subscript is allowed ('x[[i]]'). 

keep.all.ranges: Not supported for Views objects (must be 'FALSE'). 

use.names: 'TRUE' or 'FALSE'. Should names be preserved? 

gapwidth: A single integer or an integer vector with one less element
          than the 'width' vector specifying the widths of the gaps
          separating one view from the next one. 

    from: A single integer specifying the starting position of the
          first view. 

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

     'restrict' will drop the views that don't overlap with the window
     specified by 'start' and 'end' and drop the parts of the remaining
     views that are outside the window.

     [TODO: give some details about 'trim']

     [TODO: give some details about 'subviews']

     'x[[i, exact=TRUE]]' extracts the view selected by 'i'. Subscript
     'i' can be a single integer or a character string. It cannot be
     used for extracting a view that is "out of limits" (an error will
     be raised). The returned object belongs to the same class as
     'subject(x)'.

     'successiveViews' returns a Views object containing the views on
     'subject' that have the widths specified in the 'width' vector and
     are separated by the gaps specified in 'gapwidth'. The first view
     starts at position 'from'.

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

     IRanges-class, IRanges-utils, Sequence, XSequence,
     XIntegerViews-class, XStringViews-class

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

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

       ## 'start' and 'end' are recycled
       Views(subject, 2:1, 4)
       Views(subject, 5:7, )
       Views(subject, , 5:7)

       ## Some views can be "out of limits"
       v2 <- Views(subject, 4:-1, 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)

