List-class: List objects

In Bioconductor/S4Vectors: Foundation of vector-like and list-like containers in Bioconductor

List objects

Description

List objects are Vector objects with a "[[", elementType and elementNROWS 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 (defined in the IRanges package) 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 and derivatives are typically constructed using one of the following methods:

Use of a constructor function

Many constructor functions are provided in S4Vectors and other Bioconductor packages for List objects and derivatives e.g. List(), IntegerList(), RleList(), IntegerRangesList(), GRangesList(), etc...

Which one to use depends on the particular type of List derivative one wishes to construct e.g. use IntegerList() to get an IntegerList object, RleList() to get an RleList object, etc...

Note that the name of a constructor function is always the name of a valid class. See the man page of a particular constructor function for the details.

Coercion to List or to a List subclass

Many coercion methods are defined in S4Vectors and other Bioconductor packages to turn all kinds of objects into List objects.

One general and convenient way to convert any vector-like object x into a List is to call as(x, "List"). This will yield an object from a subclass of List. Note that this subclass will typically extend CompressedList but not necessarily (see ?CompressedList in the IRanges package for more information about CompressedList objects).

However, if a specific type of List derivative is desired (e.g. CompressedGRangesList), then coercing explicitly to that class is preferrable as it is more robust and more readable.

Use of splitAsList(), relist(), or extractList()

splitAsList() behaves like base::split() except that it returns a List derivative instead of an ordinary list. See ?splitAsList for more information.

The relist() methods for List objects and derivatives, as well as the extractList() function, are defined in the IRanges package. They provide very efficient ways to construct a List derivative from the vector-like object passed to their first argument (flesh for relist() and x for extractList()). See ?extractList in the IRanges package for more information.

Accessors

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

length(x):

Get the number of list elements in x.

names(x), names(x) <- value:

Get or set the names of the elements in the List.

mcols(x, use.names=FALSE), mcols(x) <- value:

Get or set the metadata columns. See Vector man page for more information.

elementType(x):

Get the scalar string naming the class from which all elements must derive.

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

Coercion

To List.

as(x, "List"):

Converts a vector-like object into a List, usually a CompressedList derivative. One notable exception is when x is an ordinary list, in which case as(x, "List") returns a SimpleList derivative.

To explicitly request a SimpleList derivative, call as(x, "SimpleList").

See ?CompressedList (you might need to load the IRanges package first) and ?SimpleList for more information about the CompressedList and SimpleList representations.

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

as.list(x, ...), as(from, "list"):

Turns x into an ordinary list.

unlist(x, recursive=TRUE, use.names=TRUE):

Concatenates the elements of x into a single vector-like object (of class elementType(x)).

as.data.frame(x, row.names=NULL, optional=FALSE , value.name="value", use.outer.mcols=FALSE, group_name.as.factor=FALSE, ...):

Coerces a List to a data.frame. The result has the same length as unlisted x with two additional columns, group and group_name. group is an integer that indicates which list element the record came from. group_name holds the list name associated with each record; value is character by default and factor when group_name.as.factor is TRUE.

When use.outer.mcols is TRUE the metadata columns on the outer list elements of x are replicated out and included in the data.frame. List objects that unlist to a single vector (column) are given the column name 'value' by default. A custom name can be provided in value.name.

Splitting values in the resulting data.frame by the original groups in x should be done using the group column as the f argument to splitAsList. To relist data, use x as the skeleton argument to relist.

Subsetting

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

x[i]:

Return a new List object made of the list elements selected by subscript i. Subscript i can be of any type supported by subsetting of a Vector object (see Vector man page for the details), plus the following types: IntegerList, LogicalList, CharacterList, integer-RleList, logical-RleList, character-RleList, and IntegerRangesList. Those additional types perform subsetting within the list elements rather than across them.

x[i] <- value:

Replacement version of x[i].

x[[i]]:

Return the selected list element i, where i is an numeric or character vector of length 1.

x[[i]] <- value:

Replacement version of x[[i]].

x$name, x$name <- value:

Similar to x[[name]] and x[[name]] <- value, but name is taken literally as an element name.

Author(s)

P. Aboyoun and H. Pagès

See Also

• splitAsList for splitting a vector-like object into a List object.

• relist and extractList in the IRanges package for efficiently constructing a List derivative from a vector-like object.

• List-utils for common operations on List objects.

• Vector objects for the parent class.

• The SimpleList class for a direct extension of the List class.

• The CompressedList class defined in the IRanges package for another direct extension of the List class.

• The IntegerList, RleList, and IRanges classes and constructors defined in the IRanges package for some examples of List derivatives.

Examples

showClass("List")  # shows only the known subclasses define in this package

## ---------------------------------------------------------------------
## A. CONSTRUCTION
## ---------------------------------------------------------------------
x <- sample(500, 20)
y0 <- splitAsList(x, x %% 4)
y0

levels <- paste0("G", 1:10)
f1 <- factor(sample(levels, length(x), replace=TRUE), levels=levels)
y1 <- splitAsList(x, f1)
y1

f2 <- factor(sample(levels, 26, replace=TRUE), levels=levels)
y2 <- splitAsList(letters, f2)
y2

library(IRanges)  # for the NumericList() constructor and the
                  # coercion to CompressedCharacterList

NumericList(A=runif(10), B=NULL, C=runif(3))

## Another way to obtain 'splitAsList(letters, f2)' but using
## 'splitAsList()' should be preferred as it is a lot more efficient:
y2b <- as(split(letters, f2), "CompressedCharacterList")  # inefficient!
stopifnot(identical(y2, y2b))

## ---------------------------------------------------------------------
## B. SUBSETTING
## ---------------------------------------------------------------------
## Single-bracket and double-bracket subsetting behave like on ordinary
## lists:
y1[c(10, 1, 2, 2)]
y1[c(-10, -1, -2)]
y1[c(TRUE, FALSE)]
y1[c("G8", "G1")]
head(y1)
tail(y1, n=3)
y1[[2]]     # note the difference with y1[2]
y1[["G2"]]  # note the difference with y1["G2"]

y0[["3"]]
y0[[3]]

## In addition to all the forms of subscripting supported by ordinary
## lists, List objects and derivatives accept a subscript that is a
## list-like object. This form of subsetting is called "list-style
## subsetting":
i <- list(4:3, -2, 1)    # ordinary list
y1[i]
i <- y1 >= 200           # LogicalList object
y1[i]

## List-style subsetting also works with an RleList or IntegerRangesList
## subscript:
i <- RleList(y1 >= 200)  # RleList object
y1[i]
i <- IRangesList(RleList(y1 >= 200))  # IRangesList object
y1[i]

## ---------------------------------------------------------------------
## C. THE "UNLIST -> TRANFORM -> RELIST" IDIOM
## ---------------------------------------------------------------------
## The "unlist -> transform -> relist" idiom is a very efficient way to
## apply the same simple transformation to all the **inner elements** of
## a list-like object (i.e. to all the elements of its list elements).
## The result is another list-like object with the same shape as the
## original object (but not necessarily the same class):
relist(sqrt(unlist(y1)), y1)
relist(toupper(unlist(y2)), y2)

## However note that sqrt(), toupper(), and many other base functions,
## can be used directly on a List derivative. This is because the IRanges
## package defines methods for these functions that know how to handle
## List objects:
sqrt(y1)     # same as 'relist(sqrt(unlist(y1)), y1)'
toupper(y2)  # same as 'relist(toupper(unlist(y2)), y2)'

Bioconductor/S4Vectors documentation built on Nov. 2, 2024, 4:34 p.m.