S4Vectors (version 0.10.2)

List-utils: 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:
## ------------------------
"lapply"(X, FUN, ...)
"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:
## ------------------------------------------------
"Reduce"(f, x, init, right=FALSE, accumulate=FALSE)
"Filter"(f, x)
"Find"(f, x, right=FALSE, nomatch=NULL)
"Map"(f, ...)
"Position"(f, x, right=FALSE, nomatch=NA_integer_)
## Evaluation of an expression in a List object:
## ---------------------------------------------
"within"(data, expr, ...)

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, a set of list, data.frame or List objects to compute over.

For pc, one or more list-like objects.

For Map, one or more List objects. (FIXME: Mixing List objects with ordinary lists doesn't seem to work properly at the moment.)

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.

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.

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 a 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(...) combines list-like objects 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.

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.

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)