| 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, widthThe start, end, or width of the window. Two of the three are required.
frequency, deltaOptional 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:
timesVector 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.outNon-negative integer. The desired length of the output vector.
eachNon-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:
SHIFTA non-negative integer vector of shift values.
X, YThe Vector or R vector objects to shift.
FUNThe 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.
simplifyA logical value specifying whether or not the result should be simplified to a vector or matrix if possible.
verboseA 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:
byAn object with start, end, and
width methods.
FUNThe function, found via match.fun, to be
applied to each window of x.
start, end, widththe start, end, or width
of the window. If by is missing, then must supply two of the
three.
frequency, deltaOptional arguments that specify the sampling frequency and increment within the window.
Further arguments for FUN.
simplifyA 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