Vector-class {S4Vectors} | R Documentation

## Vector objects

### Description

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:

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` and a `"["` method.

### Accessors

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)`: 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=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 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.

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

  `as.env(x)`: Constructs an environment object containing the elements of `mcols(x)`.

### Subsetting

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]`.

### Convenience wrappers for common subsetting operations

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.

### Concatenation

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)`. `NULL`s 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`.

### Displaying

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

### See Also

- Rle, Hits, IRanges and XRaw for example implementations.

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

- DataTable which is the type of objects returned by the `mcols` accessor.

- The Annotated class, which Vector extends.

### Examples

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

[Package S4Vectors version 0.24.4 Index]