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

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' of each of the elements.

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

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.

stack(x, indName = "space", valuesName = "values"): 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. indName specifies the column name for the index (source name) column and valuesName specifies the column name for the values.

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

Functional Programming

The R base package defines some Higher-Order functions that are commonly found in Functional Programming Languages. See ?Reduce for the details, and, in particular, for a description of their arguments. The IRanges package provides methods for List objects, so, in addition to be a vector, the x argument can also be a List object.

Reduce(f, x, init, right = FALSE, accumulate = FALSE): Uses a binary function to successively combine the elements of x and a possibly given initial value. See ?Reduce (in the base package) for the details.

Filter(f, x): Extracts the elements of x for which function f is TRUE. See ?Filter (in the base package) for the details.

Find(f, x, right = FALSE, nomatch = NULL): Extracts the first or last such element in x. See ?Find (in the base package) for the details.

Map(f, ...): Applies a function to the corresponding elements of given List objects. See ?Map (in the base package) for the details.

Position(f, x, right = FALSE, nomatch = NA_integer_): Extracts the first or last such position in x. See ?Position (in the base package) for the details.

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

Author(s)

P. Aboyoun and H. Pages

See Also

Vector for the parent class.

SimpleList and CompressedList for direct extensions.

IRanges and CompressedLogicalList for example implementations.

Examples

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

[Package IRanges version 1.12.1 Index]