Vector objects
The Vector virtual class serves as the heart of the S4Vectors 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 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 and a "[" method.
In the following code snippets, x is a Vector object.
length(x):
Get the number of elements in x.
lengths(x, use.names=TRUE):
Get the length of each of the elements.
Note: The lengths method for Vector objects is currently
defined as an alias for elementNROWS (with addition
of the use.names argument), so is equivalent to
sapply(x, NROW), not to sapply(x, length).
NROW(x):
Equivalent to either nrow(x) or length(x), depending on
whether x has dimensions (i.e. dim(x) is not NULL)
or not (i.e. dim(x) is NULL).
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=TRUE), 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 DataFrame object.
When setting the metadata columns, the supplied value must be NULL
or a DataFrame 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.
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).
In the code snippets below, x is a Vector object.
x[i]:
When supported, return a new Vector object of the same class as x
made of the elements selected by i. i can be missing;
an NA-free logical, numeric, or character vector or factor (as ordinary
vector or Rle object); or a IntegerRanges object.
x[i, j]:
Like the above, but allow the user to conveniently subset the metadata
columns thru j.
NOTE TO DEVELOPERS: A Vector subclass with a true 2-D semantic (e.g.
SummarizedExperiment) needs to overwrite
the "[" method for Vector objects. This means that code intended
to operate on an arbitrary Vector derivative x should not use
this feature as there is no guarantee that x supports it. For
this reason this feature should preferrably be used interactively
only.
x[i] <- value:
Replacement version of x[i].
In the code snippets below, x is a Vector object.
subset(x, subset, select, drop=FALSE, ...):
Return a new Vector object made of the subset using logical vector
subset, where missing values are taken as FALSE.
TODO: Document select, drop, and ....
window(x, start=NA, end=NA, width=NA):
Extract the subsequence from x that corresponds to the window
defined by start, end, and width.
At most 2 of start, end, and width can be set
to a non-NA value, which must be a non-negative integer.
More precisely:
If width is set to NA, then start or
end or both can be set to NA. In this case
start=NA is equivalent to start=1 and
end=NA is equivalent to end=length(x).
If width is set to a non-negative integer value, then
one of start or end must be set to a non-negative
integer value and the other one to NA.
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) and 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.
In the code snippets below, x is a Vector object.
c(x, ..., ignore.mcols=FALSE):
Concatenate x and the Vector objects in ... together.
Any object in ... should belong to the same class as x
or to one of its subclasses. If not, then an attempt will be made to
coerce it with as(object, class(x), strict=FALSE).
NULLs are accepted and ignored.
The result of the concatenation is an object of the same class
as x.
Handling of the metadata columns:
If only one of the Vector objects has metadata columns,
then the corresponding metadata columns are attached to
the other Vector objects and set to NA.
When multiple Vector objects have their own metadata columns, the user must ensure that each such DataFrame have identical layouts to each other (same columns defined), in order for the concatenation to be successful, otherwise an error will be thrown.
The user can call c(x, ..., ignore.mcols=FALSE) in
order to concatenate Vector objects with differing sets of
metadata columns, which will result in the concatenated
object having NO metadata columns.
IMPORTANT NOTE: Be aware that calling c with named arguments
(e.g. c(a=x, b=y)) tends to break method dispatch so please
make sure that args is an unnamed list when using
do.call(c, args) to concatenate a list of objects together.
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.
expand.grid(...): Find cartesian product of every
vector in ... and return a data.frame, each column of
which corresponds to an argument.
See expand.grid.
[FOR ADVANCED USERS OR DEVELOPERS]
Displaying of a Vector object is controlled by 2 internal helpers,
classNameForDisplay and showAsCell.
For most objects classNameForDisplay(x) just returns class(x).
However, for some objects it can return the name of a parent class that is
more suitable for display because it's simpler and as informative as the
real class name. See SimpleList objects (defined in this package)
and CompressedList objects (defined in the IRanges
package) for examples of objects for which classNameForDisplay
returns the name of a parent class.
showAsCell(x) produces a character vector parallel to
x (i.e. with one string per vector element in x) that
contains compact string representations of each elements in x.
Note that classNameForDisplay and showAsCell are generic
functions so developers can implement methods to control how their own
Vector extension gets displayed.
Vector-comparison for comparing, ordering, and tabulating vector-like objects.
Vector-setops for set operations on vector-like objects.
Vector-merge for merging vector-like objects.
Factor for a direct Vector extension that serves a similar role as factor in base R.
List for a direct Vector 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.
DataFrame which is the type of object returned by the
mcols accessor.
The Annotated class, which Vector extends.
showClass("Vector") # shows (some of) the known subclassesPlease choose more modern alternatives, such as Google Chrome or Mozilla Firefox.