Vector-class {IRanges} | R Documentation |
The Vector virtual class serves as the heart of the IRanges package
and has over 90 subclasses. It serves a similar role as vector
in base R. The Vector class includes two slots: metadata
(via extension of the Annotated class) and
elementMetadata
. Their purpose is defined below.
The Vector class supports the storage of global and element-wise metadata
with its metadata
and elementMetadata
slots. The
metadata
slot can store a list of metadata pertaining to the whole
object and the elementMetadata
slot can store a
DataTable (or NULL
) for element-wise metadata with a
row for each element and a column for each metadata variable.
To be functional, a class that inherits from Vector must define at
least a length
, names
and "["
method.
In the following code snippets, x
is a Vector object.
length(x)
:
Get the number of elements in x
.
NROW(x)
:
Defined as length(x)
for any Vector object that is
not a DataTable object.
If x
is a DataTable object, then it's
defined as nrow(x)
.
names(x)
, names(x) <- value
:
Get or set the names of the elements in the Vector.
nlevels(x)
:
Returns the number of factor levels.
elementMetadata(x), elementMetadata(x) <- value
:
Get or set the DataTable holding local metadata on each
element. The rows are either not named or named according to the names
of the elements.
Optional, may be NULL
.
values(x), values(x) <- value
:
Alternative to elementMetadata
functions.
In the code snippets below, x
is a Vector object or regular R vector
object. The R vector object methods for window
and seqselect
are defined in this package and the remaining methods are defined in base R.
x[i, drop=TRUE]
:
If defined, returns a new Vector object made of selected elements
i
, which can be missing; an NA-free logical, numeric, or
character vector; or a logical Rle object. The drop
argument
specifies whether or not to coerce the returned sequence to a standard
vector.
x[i] <- value
:
Equivalent to seqselect(x, i) <- value
.
window(x, start = NA, end = NA, width = NA, frequency = NULL, delta = NULL, ...)
:
Extract the subsequence window from the Vector object using:
start
, end
, width
The start, end, or width of the window. Two of the three are required.
frequency
, delta
Optional arguments that specify the sampling frequency and increment within the window.
In general, this is more efficient than using "["
operator.
window(x, start = NA, end = NA, width = NA, keepLength = TRUE) <- value
:
Replace the subsequence window specified on the left (i.e. the subsequence
in x
specified by start
, end
and width
)
by value
.
value
must either be of class class(x)
, belong to a subclass
of class(x)
, be coercible to class(x)
, or be NULL
.
If keepLength
is TRUE
, the elements of value
are
repeated to create a Vector with the same number of elements as the
width of the subsequence window it is replacing.
If keepLength
is FALSE
, this replacement method can modify
the length of x
, depending on how the length of the left
subsequence window compares to the length of value
.
seqselect(x, start=NULL, end=NULL, width=NULL)
:
Similar to window
, except that multiple consecutive subsequences
can be requested for concatenation. As such two of the three start
,
end
, and width
arguments can be used to specify the
consecutive subsequences. Alternatively, start
can take a Ranges
object or something that can be converted to a Ranges object like an
integer vector, logical vector or logical Rle. If the concatenation of
the consecutive subsequences is undesirable, consider using
Views
.
seqselect(x, start=NULL, end=NULL, width=NULL) <- value
:
Similar to window<-
, except that multiple consecutive subsequences
can be replaced by a value
whose length is a divisor of the number
of elements it is replacing. As such two of the three start
,
end
, and width
arguments can be used to specify the
consecutive subsequences. Alternatively, start
can take a Ranges
object or something that can be converted to a Ranges object like an
integer vector, logical vector or logical Rle.
head(x, n = 6L)
:
If n
is non-negative, returns the first n elements of the Vector
object.
If n
is negative, returns all but the last abs(n)
elements
of the Vector object.
tail(x, n = 6L)
:
If n
is non-negative, returns the last n elements of the Vector
object.
If n
is negative, returns all but the first abs(n)
elements
of the Vector object.
rev(x)
:
Return a new Vector object made of the original elements in the reverse
order.
rep(x, times, length.out, each)
, rep.int(x, times)
:
Repeats the values in x
through one of the following conventions:
times
Vector giving the number of times to repeat each
element if of length length(x)
, or to repeat the whole vector
if of length 1.
length.out
Non-negative integer. The desired length of the output vector.
each
Non-negative integer. Each element of x
is
repeated each
times.
subset(x, subset)
:
Return a new Vector object made of the subset using logical vector
subset
, where missing values are taken as FALSE.
In the code snippets below, x
is a Vector object.
c(x, ...)
:
Combine x
and the Vector objects in ...
together.
Any object in ...
must belong to the same class as x
,
or to one of its subclasses, or must be NULL
.
The result is an object of the same class as x
.
append(x, values, after = length(x))
: Insert the
Vector
values
onto x
at the position given by
after
. values
must have an elementType
that extends
that of x
.
In the code snippets below, x
is a Vector object.
tapply(X, INDEX, FUN = NULL, ..., simplify = TRUE)
:
Like the standard tapply
function defined in the
base package, the tapply
method for Vector objects applies a
function to each cell of a ragged array, that is to each (non-empty)
group of values given by a unique combination of the levels of certain
factors.
shiftApply(SHIFT, X, Y, FUN, ..., OFFSET = 0L, simplify = TRUE, verbose = FALSE)
:
Let i
be the indices in SHIFT
,
X_i = window(X, 1 + OFFSET, length(X) - SHIFT[i])
, and
Y_i = window(Y, 1 + SHIFT[i], length(Y) - OFFSET)
. Calculates
the set of FUN(X_i, Y_i, ...)
values and return the results in a
convenient form:
SHIFT
A non-negative integer vector of shift values.
X
, Y
The Vector or R vector objects to shift.
FUN
The function, found via match.fun
, to be
applied to each set of shifted vectors.
Further arguments for FUN
.
A non-negative integer offset to maintain throughout the shift operations.
simplify
A logical value specifying whether or not the result should be simplified to a vector or matrix if possible.
verbose
A logical value specifying whether or not to
print the i
indices to track the iterations.
aggregate(x, by, FUN, start = NULL, end = NULL, width = NULL,
frequency = NULL, delta = NULL, ..., simplify = TRUE))
:
Generates summaries on the specified windows and returns the result in a
convenient form:
by
An object with start
, end
, and
width
methods.
FUN
The function, found via match.fun
, to be
applied to each window of x
.
start
, end
, width
the start, end, or width
of the window. If by
is missing, then must supply two of the
three.
frequency
, delta
Optional arguments that specify the sampling frequency and increment within the window.
Further arguments for FUN
.
simplify
A logical value specifying whether or not the result should be simplified to a vector or matrix if possible.
P. Aboyoun
Rle and XRaw for example implementations.
List for a direct extension that serves a similar role as list in base R.
DataTable which is the type of objects returned by the
elementMetadata
accessor.
Annotated which Vector extends.
showClass("Vector") # shows (some of) the known subclasses