List-class {IRanges}R Documentation

List objects

Description

List objects are Vector objects with a "[[", elementType and elementLengths method. The List class serves a similar role as list in base R.

It adds one slot, the elementType slot, to the two slots shared by all Vector objects.

The elementType slot is the preferred location for List subclasses to store the type of data represented in the sequence. It is designed to take a character of length 1 representing the class of the sequence elements. While the List class performs no validity checking based on elementType, if a subclass expects elements to be of a given type, that subclass is expected to perform the necessary validity checking. For example, the subclass IntegerList has elementType = "integer" and its validity method checks if this condition is TRUE.

To be functional, a class that inherits from List must define at least a "[[" method (in addition to the minimum set of Vector methods).

Construction

List objects are typically constructed by calling the constructor of a concrete implementation, such as RangesList or IntegerList. A general and convenient way to convert any vector-like object into a List is to call as(x, "List"). This will typically yield an object from a subclass of CompressedList.

Accessors

In the following code snippets, x is a List object.

elementType(x): Get the scalar string naming the class from which all elements must derive.

elementLengths(x): Get the length (or nb of row for a matrix-like object) of each of the elements. Equivalent to sapply(x, NROW).

isEmpty(x): Returns a logical indicating either if the sequence has no elements or if all its elements are empty.

Element extraction (list style)

In the code snippets below, x is a List object.

x[[i]]: If defined, return the selected element i, where i is an numeric or character vector of length 1.

x$name: Similar to x[[name]], but name is taken literally as an element name.

Looping

In the code snippets below, x is a List object.

lapply(X, FUN, ...): Like the standard lapply function defined in the base package, the lapply method for List objects returns a list of the same length as X, with each element being the result of applying FUN to the corresponding element of X.

sapply(X, FUN, ..., simplify = TRUE, USE.NAMES = TRUE): Like the standard sapply function defined in the base package, the sapply method for List objects is a user-friendly version of lapply by default returning a vector or matrix if appropriate.

mapply(FUN, ..., MoreArgs = NULL, SIMPLIFY = TRUE, USE.NAMES = TRUE): Like the standard mapply function defined in the base package, the mapply method for List objects is a multivariate version of sapply.

endoapply(X, FUN, ...): Similar to lapply, but performs an endomorphism, i.e. returns an object of class(X).

mendoapply(FUN, ..., MoreArgs = NULL): Similar to mapply, but performs an endomorphism across multiple objects, i.e. returns an object of class(list(...)[[1]]).

revElements(x, i): A convenient way to do x[i] <- endoapply(x[i], rev). There is a fast method for CompressedList objects, otherwise expect it to be rather slow.

Coercion

In the code snippets below, x is a List object.

as.env(x, enclos = parent.frame()): Creates an environment from x with a symbol for each names(x). The values are not actually copied into the environment. Rather, they are dynamically bound using makeActiveBinding. This prevents unnecessary copying of the data from the external vectors into R vectors. The values are cached, so that the data is not copied every time the symbol is accessed.

as.list(x, ...), as(from, "list"): Turns x into a standard list.

unlist(x, recursive = TRUE, use.names = TRUE): Concatenates the elements of x into a single elementType(x) object.

relist(flesh, skeleton): Convert flesh to a list with the same structure (element lengths) as skeleton, a List object. This makes sense when flesh[i] corresponds somehow to unlist(skeleton)[i].

unsplit(value, f, drop = FALSE): Unlists value, where the order of the returned vector is as if value were originally created by splitting that vector on the factor f.

stack(x, index.var = "name", value.var = "value"): As with stack on a list, constructs a DataFrame with two columns: one for the unlisted values, the other indicating the name of the element from which each value was obtained. index.var specifies the column name for the index (source name) column and value.var specifies the column name for the values.

Evaluating

In the code snippets below, envir and data are List objects.

eval(expr, envir, enclos = parent.frame()): Converts the List object specified in envir to an environment using as.env, with enclos as its parent, and then evaluates expr within that environment.

with(data, expr, ...): Equivalent to eval(quote(expr), data, ...).

within(data, expr, ...): Similar to with, except assignments made during evaluation are taken as assignments into data, i.e., new symbols have their value appended to data, and assigning new values to existing symbols results in replacement.

Author(s)

P. Aboyoun and H. Pages

See Also

Examples

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

[Package IRanges version 1.18.0 Index]