File: Views-class.Rd

package info (click to toggle)
r-bioc-iranges 2.16.0-1
  • links: PTS, VCS
  • area: main
  • in suites: buster
  • size: 1,808 kB
  • sloc: ansic: 4,789; sh: 4; makefile: 2
file content (188 lines) | stat: -rw-r--r-- 5,450 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
\name{Views-class}
\docType{class}

\alias{class:Views}
\alias{Views-class}

\alias{parallelSlotNames,Views-method}

\alias{subject}
\alias{subject,Views-method}
\alias{ranges,Views-method}
\alias{ranges<-}
\alias{ranges<-,Views-method}
\alias{start,Views-method}
\alias{width,Views-method}
\alias{names,Views-method}
\alias{start<-,Views-method}
\alias{end<-,Views-method}
\alias{width<-,Views-method}
\alias{names<-,Views-method}
\alias{Views}
\alias{unlist,Views-method}
\alias{coerce,Vector,Views-method}
\alias{coerce,Views,IntegerRanges-method}
\alias{coerce,Views,IRanges-method}
\alias{coerce,Views,NormalIRanges-method}
\alias{as.matrix,Views-method}

\alias{bindROWS,Views-method}

\alias{trim}
\alias{trim,Views-method}
\alias{subviews}
\alias{subviews,Views-method}
\alias{successiveViews}


\title{Views objects}

\description{
  The Views virtual class is a general container for storing a set of
  views on an arbitrary \link{Vector} 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: \link{RleViews},
  \link[XVector]{XIntegerViews} (defined in the XVector package),
  \link[Biostrings]{XStringViews} (defined in the Biostrings package),
  etc...
}

\section{Constructor}{
  \describe{
    \item{}{
      \code{Views(subject, start=NULL, end=NULL, width=NULL, names=NULL)}:
      This constructor is a generic function with dispatch on argument
      \code{subject}. Specific methods must be defined for the subclasses
      of the Views class. For example a method for
      \link[Biostrings:XString-class]{XString} subjects is defined
      in the Biostrings package that returns an
      \link[Biostrings:XStringViews-class]{XStringViews}
      object. There is no default method.

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

\section{Coercion}{
  In the code snippets below, \code{from} is a Views object:

  \describe{
    \item{}{
      \code{as(from, "IRanges")}: Creates an \code{IRanges} object
      containing the view locations in \code{from}.
    }
  }
}

\section{Accessor-like methods}{
  All the accessor-like methods defined for \code{IRanges} objects
  work on Views objects. In addition, the following accessors are defined
  for Views objects:

  \describe{
    \item{}{
      \code{subject(x)}:
      Return the subject of the views.
    }
  }
}

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

\section{Concatenation}{
  \describe{
    \item{}{
      \code{c(x, ..., ignore.mcols=FALSE)}: Concatenate \code{Views} objects.
      They must have the same subject.
    }
  }
}

\section{Other methods}{
  \describe{
    \item{}{
       \code{trim(x, use.names=TRUE)}:
       Equivalent to
       \code{restrict(x, start=1L, end=length(subject(x)), keep.all.ranges=TRUE,
                      use.names=use.names)}.
    }
    \item{}{
       \code{subviews(x, start=NA, end=NA, width=NA, use.names=TRUE)}:
       \code{start}, \code{end}, and \code{width} arguments must be vectors
       of integers, eventually with NAs, that contain coordinates relative
       to the current ranges. Equivalent to
       \code{trim(narrow(x, start=start, end=end, width=width, use.names=use.names))}.
    }
    \item{}{
       \code{successiveViews(subject, width, gapwidth=0, from=1)}:
       Equivalent to \code{Views(subject, successiveIRanges(width, gapwidth, from))}.
       See \code{?successiveIRanges} for a description of the \code{width},
       \code{gapwidth} and \code{from} arguments.
    }
  }
}

\author{Hervé Pagès}

\seealso{
  \link{IRanges-class},
  \link{Vector-class},
  \link{IRanges-utils},
  \link[XVector]{XVector}.

  Some direct subclasses of the Views class:
  \link{RleViews-class},
  \link[XVector]{XIntegerViews-class},
  \link[XVector]{XDoubleViews-class},
  \link[Biostrings]{XStringViews-class}.

  \code{\link{findOverlaps}}.
}

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

## Create a set of 4 views on an XInteger subject of length 10:
subject <- Rle(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)

## See ?`XIntegerViews-class` in the XVector package for more examples.
}

\keyword{methods}
\keyword{classes}