List-utils: Common operations on List objects

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

Common operations on List objects

Description

Various functions and methods for looping on List objects, functional programming on List objects, and evaluation of an expression in a List object.

Usage

## Looping on List objects:
## ------------------------

## S4 method for signature 'List'
lapply(X, FUN, ...)

## S4 method for signature 'List'
sapply(X, FUN, ..., simplify=TRUE, USE.NAMES=TRUE)

endoapply(X, FUN, ...)

revElements(x, i)

mendoapply(FUN, ..., MoreArgs=NULL)

pc(...)

## Functional programming methods for List objects:
## ------------------------------------------------

## S4 method for signature 'List'
Reduce(f, x, init, right=FALSE, accumulate=FALSE)
## S4 method for signature 'List'
Filter(f, x)
## S4 method for signature 'List'
Find(f, x, right=FALSE, nomatch=NULL)
## S4 method for signature 'List'
Map(f, ...)
## S4 method for signature 'List'
Position(f, x, right=FALSE, nomatch=NA_integer_)

## Evaluation of an expression in a List object:
## ---------------------------------------------

## S4 method for signature 'List'
within(data, expr, ...)

## Constructing list matrices:
## ---------------------------------------------

## S4 method for signature 'List'
rbind(..., deparse.level=1L)
## S4 method for signature 'List'
cbind(..., deparse.level=1L)

Arguments

X, x	A list, data.frame or List object.
FUN	The function to be applied to each element of X (for endoapply) or for the elements in ... (for mendoapply).
...	For lapply, sapply, and endoapply, optional arguments to FUN. For mendoapply, pc and Map, one or more list-like objects.
simplify, USE.NAMES	See ?base::sapply for a description of these arguments.
MoreArgs	A list of other arguments to FUN.
i	Index specifying the elements to replace. Can be anything supported by `[<-`.
f, init, right, accumulate, nomatch	See ?base::Reduce for a description of these arguments.
data	A List object.
expr	Expression to evaluate.
deparse.level	See ?base::rbind for a description of this argument.

Details

Looping on List objects

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.

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.

endoapply and mendoapply perform the endomorphic equivalents of lapply and mapply by returning objects of the same class as the inputs rather than an ordinary list.

revElements(x, i) reverses the list elements in x specified by i. It's equivalent to, but faster than, doing x[i] <- endoapply(x[i], rev).

pc(...) combine list-like objects by concatenating them in an element-wise fashion. It's similar to, but faster than, mapply(c, ..., SIMPLIFY=FALSE). With the following differences:

1. pc() ignores the supplied objects that are NULL.

2. pc() does not recycle its arguments. All the supplied objects must have the same length.

3. If one of the supplied objects is a List object, then pc() returns a List object.

4. pc() always returns a homogenous list or List object, that is, an object where all the list elements have the same type.

Functional programming methods for List objects

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

Evaluation of an expression in a List object

within evaluates expr within as.env(data) via eval(data). 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.

Binding Lists into a matrix

There are methods for cbind and rbind that will bind multiple lists together into a basic list matrix. The usual geometric constraints apply. In the future, this might return a List (+ dimensions), but for now the return value is an ordinary list.

Value

endoapply returns an object of the same class as X, each element of which is the result of applying FUN to the corresponding element of X.

mendoapply returns an object of the same class as the first object specified in ..., each element of which is the result of applying FUN to the corresponding elements of ....

pc returns a list or List object of the same length as the input objects.

See ?base::Reduce for the value returned by the functional programming methods.

See ?base::within for the value returned by within.

cbind and rbind return a list matrix.

Author(s)

P. Aboyoun and H. Pagès

See Also

• The List class.

• base::lapply and base::mapply for the default lapply and mapply methods.

• base::Reduce for the default functional programming methods.

• base::within for the default within method.

• base::cbind and base::rbind for the default matrix binding methods.

Examples

a <- data.frame(x = 1:10, y = rnorm(10))
b <- data.frame(x = 1:10, y = rnorm(10))

endoapply(a, function(x) (x - mean(x))/sd(x))
mendoapply(function(e1, e2) (e1 - mean(e1)) * (e2 - mean(e2)), a, b)

x <- list(a=11:13, b=26:21, c=letters)
y <- list(-(5:1), c("foo", "bar"), 0.25)
pc(x, y)

library(IRanges)
x <- IntegerList(a=11:13, b=26:21, c=31:36, d=4:2)
y <- NumericList(-(5:1), 1:2, numeric(0), 0.25)
pc(x, y)

Reduce("+", x)

Filter(is.unsorted, x)

pos1 <- Position(is.unsorted, x)
stopifnot(identical(Find(is.unsorted, x), x[[pos1]]))

pos2 <- Position(is.unsorted, x, right=TRUE)
stopifnot(identical(Find(is.unsorted, x, right=TRUE), x[[pos2]]))

y <- x * 1000L
Map("c", x, y)

rbind(x, y)
cbind(x, y)

Bioconductor/S4Vectors documentation built on Nov. 17, 2024, 6:55 p.m.