List-utils {S4Vectors} | R Documentation

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

[Package S4Vectors version 0.22.1 Index]