Vector-class {IRanges}R Documentation

Vector objects

Description

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:

  1. The global metadata annotates the object as a whole: this metadata is accessed via the metadata accessor and is represented as an ordinary list;

  2. 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.

Accessors

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.

elementMetadata(x, use.names=FALSE), elementMetadata(x) <- value, values(x, use.names=FALSE), values(x) <- value: Alternatives to mcols functions. Their use is discouraged.

Subsetting

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.

split(x, f, drop = FALSE) <- value: Virtually splits x by the factor f, replaces the elements of the resulting list with the elements from the list value, and restores x to its original form. Note that this works for any Vector, even though split itself is not universally supported.

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.

Combining

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).

Looping

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.

OFFSET

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.

Utilities

unique(x): Returns the unique elements in x. Requires that the Vector derivative support duplicated.

Coercion

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.

Author(s)

P. Aboyoun

See Also

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 mcols accessor.

Annotated which Vector extends.

Examples

  showClass("Vector")  # shows (some of) the known subclasses

[Package IRanges version 1.18.2 Index]