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 supports the storage of global and element-wise metadata:
The global metadata annotates the object as a whole:
this metadata is accessed via the metadata
accessor and
is represented as an ordinary list;
The element-wise metadata annotates individual elements
of the object: this metadata is accessed via the mcols
accessor (mcols
stands for metadata columns) and
is represented as a DataTable object (i.e. as an instance
of a concrete subclass of DataTable, e.g. a DataFrame
object), with a row for each element and a column for each
metadata variable. Note that the element-wise metadata can also
be NULL
.
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.
rename(x, value, ...)
:
Replace the names of x
according to a mapping defined by a named
character vector, formed by concatenating value
with any
arguments in ...
. The names of the character vector
indicate the source names, and the corresponding values the
destination names. This also works on a plain old vector
.
nlevels(x)
:
Returns the number of factor levels.
mcols(x, use.names=FALSE)
, mcols(x) <- value
:
Get or set the metadata columns.
If use.names=TRUE
and the metadata columns are not NULL
,
then the names of x
are propagated as the row names of the
returned DataTable object.
When setting the metadata columns, the supplied value must be NULL
or a DataTable object holding element-wise metadata.
with(x, expr)
: Evaluates expr
within
as.env(x)
via eval(x)
.
eval(expr, envir, enclos=parent.frame())
: Evaluates
expr
within envir
, where envir
is coerced to
an environment with as.env(envir, enclos)
. The expr
is first processed with bquote
, such that any
escaped symbols are directly resolved in the calling frame.
elementMetadata(x, use.names=FALSE)
,
elementMetadata(x) <- value
,
values(x, use.names=FALSE)
,
values(x) <- value
:
Alternatives to mcols
functions. Their use is discouraged.
In the code snippets below, x
is a Vector object or regular R vector
object. The R vector object methods for window
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
:
Replacement version of x[i]
.
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) <- 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)
, or be coercible to class(x)
or a
subclass of class(x)
.
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.
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
.
mstack(..., .index.var = "name")
: A variant of
stack
, where the list is taken as the list of
arguments in ...
, each of which should be a Vector
or vector
(mixing the two will not work).
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.
as(from, "data.frame")
, as.data.frame(from)
:
Coerces from
, a Vector
, to a data.frame
by
first coercing the Vector
to a vector
via
as.vector
. Note that many Vector
derivatives do not
support as.vector
, so this coercion is possible only for
certain types.
as.env(x)
: Constructs an environment object
containing the elements of mcols(x)
.
P. Aboyoun
Vector-comparison for comparing, ordering, and tabulating vector-like objects.
List for a direct extension that serves a similar role as list in base R.
extractList for grouping elements of a vector-like object into a list-like object.
DataTable which is the type of objects returned by the
mcols
accessor.
Annotated which Vector extends.
showClass("Vector") # shows (some of) the known subclasses