Vector-class {S4Vectors} | R Documentation |
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 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
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)
.
See ?BiocGenerics::lengths
in the
BiocGenerics package for more information about this.
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.
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 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 an ordinary
vector.
x[i] <- value
:
Replacement version of x[i]
.
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
.
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.
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.
DataTable which is the type of objects returned by the
mcols
accessor.
The Annotated class, which Vector extends.
showClass("Vector") # shows (some of) the known subclasses